# result-rpc

> Typed RPC for React. Errors accumulate along the call path and discharge along the component tree.

# The client
Source: https://result-rpc.com/concepts/client

```ts
import { createBrowserClient, batchFetchTransport } from "result-rpc/client";
import { appContract } from "../shared/contract";

export const client = createBrowserClient({
  contract: appContract,
  transport: batchFetchTransport({ url: "/rpc" }),
});

const result = await client.doc.byId({ id: "doc_123" });
```

Calls issued in the same microtask share one HTTP request. Every batch item
keeps its own status, decoder, rich-value envelope, and tagged Result. Use
`fetchTransport` when batching is not wanted; the client API is unchanged.
Because the batch itself is one successful protocol exchange, its outer HTTP
status is 200; an item's domain status (for example 409) remains in that item
and is reported by the server hooks, but browser network panels show the outer
batch status.

`batchFetchTransport` also implements the streaming path used by
subscriptions. Use this same client instance beneath `ResultRpcProvider`; a
separate fetch client is neither required nor compatible with that runtime's
cache and ownership context.

One deliberate carve-out from "every call resolves `Result`": input that the
procedure's **own input codec** rejects throws a `TypeError` at the call site
and never reaches the wire. That is a programmer error — the types prevent it
for structural codecs, and for runtime-validating codecs (`wire.standard`)
your form validates the human first (see [Forms and the
wire](/guides/forms/)). Errors-as-values is a contract about _outcomes of
operations_, not a net under code the compiler already rejects.

The direct client is the honest base: it always resolves the complete union.
Narrowing is a property of where a call is _rendered_, and the direct client
is not rendered anywhere, so it never subtracts anything. Every failure in the
union is already a reified `TaggedError`: definition `.is()` guards,
`instanceof Error`, `toJSON`, and direct `yield*` all work after transport.

```ts
Result<
  Doc,
  | Unauthorized
  | DocNotFound
  | ServerInternal
  | Offline
  | NetworkFailure
  | Timeout
  | HttpFailure
  | ProtocolViolation
  | DecodeFailure
>;
```

Handle the union with an ordinary switch (`result.error satisfies never` in
the default arm keeps it exhaustive), or build a reusable projection — a
message catalog, a metrics mapper — once, from the same definition map
middleware and shells use:

```ts
import { errorCatalog } from "result-rpc";

const message = errorCatalog(
  { DocNotFound, Unauthorized },
  {
    "doc/not-found": (e) => `Doc ${e.data.docId} is gone`,
    "auth/unauthorized": () => "Sign in to continue",
  },
);
```

Adding a definition to the map breaks every catalog missing the new tag. For
inline one-offs, `matchError(result.error, { ...handlers })` gives the same
exhaustiveness on a single value. At an `unknown` boundary, use the catalog's
exact guard before projecting:

```ts
if (message.is(caught)) return message(caught);
```

The full composition surface — `gen` with `yield*`, `tryPromise`, `all`, the
transform family — is covered in
[Result composition](/concepts/results/).

## Cancellation is not an operation error

Query cancellation updates lifecycle state without producing an `Err`,
consuming a retry, or entering an error boundary.

Direct calls accept an `AbortSignal`:

```ts
const controller = new AbortController();

const pending = client.doc.byId({ id: "doc_123" }, { signal: controller.signal });

controller.abort();
```

Internally result-rpc uses a tagged `control/cancelled` sentinel so
cancellation does not depend on platform-specific `AbortError` identity. It is
control flow and is excluded from the recoverable error union. Its sibling,
`control/claimed`, is what a shell-claimed mutation rejects with — the same
family, one `catch` at the call site, and `isCancelled`/`isClaimed` to tell
the two events apart when the UX differs.

## Server-side calls stay in-process

```ts
import { createServerClient } from "result-rpc/server";
import { appRouter } from "./router";

const serverClient = createServerClient(appRouter, {
  context,
});

const result = await serverClient.doc.byId({ id: "doc_123" });
```

The server client still runs middleware and input/output codecs, but it does
not manufacture browser failures that cannot happen in-process. Use
`createParityClient` from `result-rpc/testing` when a test should cross the
serializer, protocol envelope, fetch handler, and browser decoder.

---

# The client boundary
Source: https://result-rpc.com/concepts/client-boundary

Read this page before you wire a client. It is the one place where a wrong
import is a **security bug**, not a style choice.

## result-rpc is not tRPC here

tRPC ships **a type** to the client. `AppRouter` is imported `import type`, erased
at build, and the browser gets nothing but inference. You can point tRPC's client
at your server router because only its shape survives.

result-rpc ships **a value** to the client — a real runtime built from your
contract, with codecs that encode inputs and decode outputs. That value has to
exist in the browser. So the question "what ends up in my bundle?" has a real
answer. `createBrowserClient` therefore accepts contracts only.

The rule is one sentence:

> **Build the browser client from a `contract()`, and define that contract in a
> module that never imports handler or server code.**

Do that and your bundle contains codecs and error definitions — nothing else.
You still control imports: merely importing a server module from a browser entry
can make it reachable before any call runs.

## What a contract carries, and what a router carries

Two different values, two different payloads:

- **`contract()`** — procedure _shapes_ only: input codec, output codec, declared
  error definitions, `.affects()`/`.writes()` invalidation maps. No handlers, no
  middleware. This is the browser-safe surface, and the client only ever reads
  these fields.
- **`router()`** (and any implemented procedure) — _everything the contract has,
  plus the handler function and its middleware chain_, which close over your
  database, your services, your environment. Server-only.

The browser client is constructed from the contract. Fetch handlers and server
clients are constructed from the implemented router.

## Why the split matters

A handler that closes over a secret:

```ts
// server.ts
const server = serverRpc.context<AppContext>()
const getUser = server.implement(getUserContract).handler(async ({ input }) => {
  const key = process.env.STRIPE_SECRET_KEY!   // closed over by the handler
  const row = await db.query.users.findFirst(...)
  return ok(row)
})
export const appRouter = server.router({ users: { get: getUser } })
```

A client entry imports the standalone contract:

```ts
// client.ts
import { appContract } from "./contract";
createBrowserClient({ contract: appContract, transport });
// bundle: STRIPE_SECRET_KEY → 0 hits. db driver → 0 hits.
```

The layout is the protection. A top-level `server.router(...)` or `.handler(...)`
call is potentially side-effecting, so a browser entry that imports the server
module may retain its graph. Keep the import direction clean.

## The safe layout

The dependency arrow points **from server to contract**, never the reverse:

```
contract.ts   ── imports: result-rpc, wire codecs, models, error defs
   ▲                (and `import type` from server is fine — types are erased)
   │
server.ts     ── imports contract.ts, implements handlers, builds the router
client.ts     ── imports contract.ts, builds the browser client
```

```ts
// contract.ts — no server imports; safe to reach from anywhere
import { rpc, wire } from "result-rpc"
import type { AppContext } from "./server"     // type-only: erased at build
export const getUserContract = rpc.context<AppContext>()
  .procedure().input(...).output(...).query()
export const appContract = rpc.context<AppContext>().contract({
  users: { get: getUserContract },
})
```

```ts
// server.ts — imports the contract to implement it
import { serverRpc } from "result-rpc/server"
import { getUserContract } from "./contract"
const server = serverRpc.context<AppContext>()
const getUser = server.implement(getUserContract).handler(...)
export const appRouter = server.router({ users: { get: getUser } })
```

```ts
// client.ts — imports the contract only
import { appContract } from "./contract";
export const client = createBrowserClient({ contract: appContract, transport });
```

Three cheap rules keep this honest:

1. **Contracts import no runtime server code.** `import type` is fine; a value
   import from a server module is the footgun.
2. **`.affects()` targets are contract references**, never implemented
   procedures — an implemented procedure passed as a target drags its handler
   into the contract graph.
3. **Never import the router into anything a browser bundles.** Colocating "for
   convenience" ships handlers; there is no convenience worth a leaked secret.

## Isomorphic loaders are a second leak vector

The rule above is about _what you import_. Some frameworks add a second hazard:
code that **looks** server-side but runs in both places.

TanStack Router/Start **loaders are isomorphic** — they run on the server during
SSR and in the browser on client-side navigation. A loader that imports your
database module directly will typecheck, work perfectly in dev SSR, and then
ship your database driver (and whatever it closes over) to the browser the first
time a user navigates client-side. Nothing warns you, because nothing is
technically wrong: you asked for that module in code that runs on the client.

There is no `'use client'` directive protecting you here, the way RSC frameworks
protect a server component. The fix is to put an explicit server wall inside the
loader:

```ts
// ☠️ the loader imports the server module directly — ships the db on client nav
import { db } from "./db";
export const Route = createFileRoute("/")({
  loader: async () => db.query.spots.findMany(),
});

// ✅ the server wall is a server function; the loader only calls it
const loadSpots = createServerFn().handler(async () => {
  const { db } = await import("./db"); // server-only, never bundled
  return runtime.dehydrate();
});
export const Route = createFileRoute("/")({ loader: () => loadSpots() });
```

The general test applies to any framework: **for every module a client bundle can
reach, ask what it transitively imports.** RSC's `'use client'`/server-component
split answers that question for you; isomorphic loaders make it your job.

## Monorepos and pre-built `packages/api`

If you ship a built `packages/api` (emitted `.d.ts` + `.js`), consumers get the
clean boundary automatically — in **both** dimensions:

- **Runtime**: they import `appContract` from the package's built output; the
  handler code lives in a server entry the client build never touches.
- **Types**: client callables are projected from the contract's associated
  `record`; the root context never appears in their input, output, or error
  types. TypeScript still has to resolve whatever declarations the shared
  contract itself imports, so keep that module's context shape browser-safe
  (or put the public context interface in its own type-only module). Runtime
  bundlers erase those imports, but a declaration graph is still a graph.

The split protects the runtime bundle completely; keeping the shared contract's
type imports narrow does the corresponding job for editor and `tsc` performance.

## What is safe to expose

The contract _is_ your public API surface, and everything in it reaches the
client by design — that is correct and not a leak:

- **Field names and shapes** in your codecs (the client must decode them).
- **Error tags and their data shapes** for declared, `visibility: "public"`
  errors. The compiler rejects private (`visibility: "private"`) definitions
  from procedure, middleware, and layer error maps. They are server-side
  composition currency; the runtime also sanitizes an unsafe cast or
  JavaScript bypass to `server/internal` at the wire.
- **`.affects()`/`.writes()` maps** — these run _on the client_ (cache
  invalidation), so they are meant to ship. Keep them pure input→input
  transforms; never close a secret into one.

If a fact would be dangerous in the browser, it does not belong in the contract —
it belongs behind a handler.

`visibility: "private"` controls the error algebra; it is not a bundler
directive. Keep private definitions and the libraries they adapt in a
server-only module. Importing a mixed server error module from the contract can
still pull that module's runtime dependency graph into the browser even though
TypeScript correctly excludes its private errors from `.errors(...)`.

---

# Services and request context
Source: https://result-rpc.com/concepts/context

A procedure sees one `context`, but two different things feed it, with
different lifetimes and failure rules:

|                            | Services                                    | Request middleware                      |
| -------------------------- | ------------------------------------------- | --------------------------------------- |
| Examples                   | database pool, worker bindings, API clients | session, viewer, organization           |
| Lifetime                   | process                                     | request                                 |
| Shape                      | dependency graph                            | ordered chain                           |
| Can fail with a wire error | no — a broken service is a broken process   | yes — failures join the operation union |
| Owned by                   | `defineService` / `resolveServices`         | middleware                              |

## Services

If you have read about Effect: this is its service/dependency-injection idea
at its useful core — declare what each resource needs, resolve the graph once,
memoize by identity — without fibers, without `Effect.gen`, without a runtime.
It is a small feature, not a religion.

```ts
import { defineService, resolveServices } from "result-rpc";

const Db = defineService("db", {
  create: () => createPool(env.DATABASE_URL),
});

const Mailer = defineService("mailer", {
  needs: { db: Db },
  create: ({ db }) => createMailer(db),
});

const services = await resolveServices({ db: Db, mailer: Mailer });
```

The graph is resolved once at process start and memoized by definition
reference — a service two others depend on is constructed exactly once. The
sharp edge, stated plainly: identity is by reference, so store definitions in
module constants; two `defineService` calls are two services.

The resolved record becomes the root context that every request closes over:

```ts
export const handleRpc = createFetchHandler({
  router: appRouter,
  createContext: ({ request }) => ({ ...services, request }),
});
```

Nothing pulls services per call — the auth middleware reads `context.db`
because the root context guarantees it, and swapping the whole record for a
test double is one argument to `createContext`.

## Middleware composes by requirement, not by ordering

The footgun: middleware order as tribal knowledge — `session` must run before
`requireViewer`, enforced by a comment. Here a middleware declares what it
runs after; the dependency's output becomes its input, the dependency's errors
join the union, and any `.use()` site pulls the whole chain in dependency
order:

`next` takes only this middleware's declared contribution. result-rpc merges
it into the established context, so a middleware cannot accidentally discard
upstream fields and refinements need no whole-context spread.

```ts
import { serverRpc } from "result-rpc/server";

const server = serverRpc.context<AppContext>();
const session = server
  .middleware<{ viewer: User | null }>()
  .use(async ({ context, next }) => next({ context: { viewer: await userFromCookie(context) } }));

const requireViewer = server
  .middleware<{ viewer: User }>()
  .after(session) // handler sees viewer: User | null
  .errors({ Unauthorized })
  .use(({ context, errors, next }) =>
    context.viewer === null
      ? err(errors.Unauthorized())
      : next({ context: { viewer: context.viewer } }),
  );
```

A mutation then demands exactly one thing:

```ts
export const renameDoc = server
  .procedure()
  .input(RenameInput)
  .output(DocCodec)
  .use(requireViewer) // session comes along, in order
  .mutation(({ context, input }) =>
    // context.viewer: User
    context.db.docs.rename(input, context.viewer),
  );
```

`.use(session)` followed by `.use(requireViewer)` still runs `session` once —
composition is deduplicated by reference identity, the same rule as services
(module constants, not inline builds). A middleware whose input demands
context the procedure cannot supply is a type error, so requirements are
checked, not hoped for.

## Setting response headers, and logging someone in

Writing a response header is a **declared capability**. A procedure calls
`.headers()` and receives `context.headers`, a `Headers` to append to — a
session cookie on login, a `cache-control`, a rate-limit hint. A procedure that
does not declare it has no `context.headers` at all.

```ts
const login = server
  .procedure()
  .headers()
  .input(wire.object({ email: wire.string, password: wire.string }))
  .output(wire.object({ userId: wire.string }))
  .errors({ BadCredentials })
  .mutation(async ({ input, context, errors }) => {
    const user = await context.db.verify(input.email, input.password);
    if (!user) return err(errors.BadCredentials({}));

    context.headers.append(
      "set-cookie",
      `session=${await mintToken(user)}; HttpOnly; Path=/; SameSite=Lax; Max-Age=604800`,
    );
    return ok({ userId: user.id });
  });
```

Note the mutation returns a `Result` like anything else — bad credentials are a
declared failure, not an exception.

Reading cookies needs nothing new; `createContext` has the request:

```ts
createContext: ({ request }) => ({
  db,
  session: parseCookie(request.headers.get("cookie"))?.session,
});
```

A middleware that rotates a session cookie declares the same way, and then
every procedure using it must declare `.headers()` too — the same rule that
makes a middleware's errors part of its procedures' declared unions:

```ts
const rotateSession = server
  .middleware()
  .headers()
  .use(({ context, next }) => {
    context.headers.append("set-cookie", `session=${refresh(context)}; HttpOnly; Path=/`);
    return next({ context: {} });
  });
```

### Why declare it instead of just writing it

The declaration is recorded in the contract, which means a transport knows
_before dispatch_ that this call's response headers cannot be sent early.

That matters because batching and streaming pull in opposite directions. A
streamed batch sends its headers first and its results as they arrive — which
means a `set-cookie` written by a handler that has not finished yet arrives
after the headers are already on the wire, and is silently dropped. tRPC has
exactly this hazard: `ctx.resHeaders` works under `httpBatchLink` and silently
stops working under `httpBatchStreamLink`, with no error and no warning. The
usual workaround is to move the cookie into `responseMeta`, a hook that runs
before the procedure has produced a result.

Declaring the capability makes the conflict statically visible instead of
silent, and it is why the flag is part of the [contract
digest](/concepts/deploys/) — a client and server that disagreed about it
would reintroduce the same dropped cookie.

Two consequences follow:

**A batch shares one response.** Several procedures answered in one HTTP request
share its headers, so their `set-cookie`s combine rather than overwrite. That is
usually what you want; it does mean two logins in one batch set two cookies.

**A subscription cannot write response headers at all** — a compile error,
whether you declare `.headers()` directly or acquire it by `.use()`-ing a
middleware that declares it. Its response is on the wire before the stream, and
therefore before any of its middleware or handler code runs, so there is no
moment at which a write could land. Set the header in the request that opens
the stream instead.

**The capability survives `.use()`.** A middleware replaces the context, but
`headers` is re-applied from the capability rather than inherited from whatever
the middleware passed on — so `.headers().use(mw)` and `.use(mw).headers()`
behave identically. Builder order is not something you have to remember here,
which is the same promise middleware composition makes above.

The response is otherwise the protocol's. Status is derived from the failing
error's declared `httpStatus` rather than chosen by a handler — that is what
lets a client tell a real result-rpc failure from an intermediary's 502 — and
the body is always the Result envelope.

---

# Contract and procedures
Source: https://result-rpc.com/concepts/contract

```ts
import { rpc, wire, type InputOf, type ProcedureError, type ProcedureOutput } from "result-rpc";
import { DocNotFound, Unauthorized } from "./errors";

interface AppContext {
  docs: DocRepository;
  auth: AuthService;
}

export const app = rpc.context<AppContext>();

const DocCodec = wire.object({
  id: wire.string,
  title: wire.string,
  savedAt: wire.date,
});
type Doc = InputOf<typeof DocCodec>;

export const getDocContract = app
  .procedure()
  .input(wire.object({ id: wire.string }))
  .output(DocCodec)
  .errors({ Unauthorized, DocNotFound })
  .query();

export const appContract = app.contract({
  doc: {
    byId: getDocContract,
  },
});

type DocOutput = ProcedureOutput<typeof getDocContract>;
type GetDocFailure = ProcedureError<typeof getDocContract>;
```

One honest difference from tRPC: tRPC ships the router's _type_ to the client
(`import type AppRouter`), and in exchange the client can neither decode rich
values nor validate anything. result-rpc ships a small _value_ — the contract:
codecs, tags, and policies, no middleware or handler code, safe in any browser
bundle. It is the one place this library costs you a file tRPC doesn't, and it
is what pays for `Date`/`Map`/`BigInt` over the wire and codecs on both sides.

Browser clients are built from this contract. Implemented routers belong to
`createFetchHandler` and `createServerClient`.

`ProcedureOutput` and `ProcedureError` are the direct helpers when code names
one procedure. For forms, loaders, test fixtures, or adapters spanning a whole
application, `RouterInputs`, `RouterOutputs`, and `RouterErrors` preserve the
router's nested shape so a path can be indexed without rebuilding a codec or
union. All six helpers work on the shared contract; the nested helpers also
work on an implemented router in server-only code.

## Implement the contract on the server

```ts
import { err, ok } from "result-rpc";
import { serverRpc } from "result-rpc/server";
import { getDocContract, type AppContext } from "./contract";

const server = serverRpc.context<AppContext>();
export const getDoc = server
  .implement(getDocContract)
  .use(authenticated)
  .handler(async ({ input, errors, context }) => {
    const doc = await context.docs.find(input.id);

    if (!doc) return err(errors.DocNotFound({ docId: input.id }));

    return ok(doc);
  });
```

The handler must return the declared Result:

```ts
Result<Doc, Unauthorized | DocNotFound>;
```

Returning a different tag is a type error. Smuggling an undeclared or
malformed tag at runtime does not make it public: result-rpc logs the defect
and emits a sanitized `server/internal` value.

## Middleware participates in the same union

The tRPC footgun here is quiet: middleware that throws `TRPCError({ code:
"UNAUTHORIZED" })` adds a failure mode the procedure's type never mentions.
Here, middleware declares what it contributes, and the contribution lands in
the union:

```ts
import { err } from "result-rpc";
import { serverRpc } from "result-rpc/server";
import type { AppContext } from "./contract";
import { Unauthorized } from "./errors";

const server = serverRpc.context<AppContext>();
const authenticated = server
  .middleware<{ user: User }>()
  .errors({ Unauthorized })
  .use(async ({ context, errors, next }) => {
    const user = await context.auth.user();

    if (!user) {
      return err(errors.Unauthorized());
    }

    return next({
      context: { user },
    });
  });

export const getDoc = server.implement(getDocContract).use(authenticated).handler(/* ... */);
```

The procedure now returns:

```ts
Result<Doc, Unauthorized | DocNotFound>;
```

Builders are immutable, so a base forks freely — the `protectedProcedure`
pattern is one line:

```ts
const protectedProcedure = server.procedure().use(authenticated);

const renameDoc = protectedProcedure
  .input(RenameInput)
  .output(DocCodec)
  .errors({ DocNotFound, DocLocked }) // only its own domain errors;
  .mutation(/* ... */); // the auth union rides in with the base
```

Middleware definitions also join the handler's `errors` bag, so a handler can
return a middleware-contributed error without re-importing it — but choose
deliberately there: `errors.Unauthorized()` from an ownership check would hand
a 403-shaped outcome to whatever shell owns the auth union (whose reaction is
a sign-in redirect). Not-the-owner is its own domain error.

In contract-first code, middleware errors must already be present in the
shared contract; `server.implement(...).use(...)` rejects an undeclared
contribution. The code-first convenience form unions middleware definitions
automatically. Duplicate tags with different definitions are rejected rather
than silently overridden.

## Create the router and server

```ts
import { createFetchHandler, serverRpc } from "result-rpc/server";
import type { AppContext } from "./contract";
import { getDoc } from "./doc";

const server = serverRpc.context<AppContext>();
export const appRouter = server.router({
  doc: {
    byId: getDoc,
  },
});

export type AppRouter = typeof appRouter;

// Nested inference helpers mirror the router's shape — works on contracts too:
// type Inputs = RouterInputs<AppRouter>;  Inputs["doc"]["byId"]  → { id: string }
// type Outputs = RouterOutputs<AppRouter>; Outputs["doc"]["byId"] → Doc
// type Errors = RouterErrors<AppRouter>;   Errors["doc"]["byId"]  → declared union

export const handleRpc = createFetchHandler({
  router: appRouter,
  endpoint: "/rpc",
  createContext: ({ request }) => ({
    request,
    auth,
    docs,
  }),
  onInternalError: ({ incidentId, phase, cause, procedurePath }) => {
    logger.error({ incidentId, phase, cause, procedurePath });
  },
});
```

`onError` is the observability tap: it fires for every declared error that
crosses the wire — domain errors, bad requests, sanitized internals — with the
error value, its policy (severity, retry, status), and the procedure path, so
one hook feeds metrics and logging:

```ts
onError: ({ error, policy, procedurePath, httpStatus }) => {
  metrics.count(error._tag, { severity: policy?.severity });
};
```

Malformed input is the client's fault, not an incident: it becomes a public
`server/bad-request` (400) carrying path-and-message issues — never values —
while `onInternalError` stays reserved for genuine defects.

Unknown exceptions receive an incident ID and are passed to `onInternalError`
when configured. The client receives only:

```ts
{
  _tag: "server/internal",
  data: { incidentId: "inc_..." },
}
```

Exception messages, stacks, causes, queries, and response bodies are not
reflected over the wire.

---

# Deploys and stale clients
Source: https://result-rpc.com/concepts/deploys

Every deploy opens a compatibility window: new server, old tabs. In most
stacks the window is invisible — a stale client's failures are
indistinguishable from bugs (bad requests, decode failures), Sentry counts
every deploy as an incident spike, and the "fix" is a user who happens to
press reload. Closed unions make the window _more_ acute, not less: a stale
client cannot even decode an error tag added after it was built.

result-rpc makes the window a detected, owned state:

1. The server stamps every response with a digest of its contract —
   procedure paths, kinds, and every error tag with its policy
   (`x-result-rpc-contract`). A router and the contract it implements digest
   identically; nothing to configure.
2. The client compares the stamp to its own digest. The first mismatch emits
   a `skew` ClientEvent — observability sees the drift before anything fails.
3. When a request **fails** with a contract-shaped tag (`server/bad-request`,
   `client/decode-failure`, `client/protocol-violation`,
   `client/http-failure`) _while the digests differ_, the failure is
   reclassified as `client/stale`, carrying the original tag. Matching
   digests change nothing — a real defect stays a defect, and successful
   calls are never touched.

The stamp is required protocol evidence, not optional metadata. A missing or
empty `x-result-rpc-contract` is a `client/protocol-violation` in unary,
batched, and streaming responses. The built-in transports preserve it. A
custom `ClientTransport` must return the server stamp as `response.contract`,
and a proxy must forward or expose the header; otherwise the client fails
closed instead of silently disabling skew detection.

And `client/stale` has a built-in owner: the boundary's `StaleShell` claims
it, holds the affected operations, and reacts — by default with a page
reload, because the reload fetches the current client, which _is_ the fix.
Override it to taste:

```tsx
const { BoundaryProvider } = boundaryShells({
  onStale: () => toast("A new version is available", { action: reload }),
});
```

The automatic digest is structural: built-in codecs contribute their complete
nested shape, constraints, literals, model projections, and error-data schemas.
Adopted Standard Schemas and guarded serializable values contribute their
application-owned stable schema `id`. A field-level contract change therefore
changes the digest. You may instead make a build stamp the effective version on
both sides:

```ts
createFetchHandler({ router, contractVersion: BUILD_SHA, ... })
createBrowserClient({ contract, contractVersion: BUILD_SHA, ... })
```

Detection is failure-gated, so matching successful calls are never
reclassified.

`contractVersion` _replaces_ the structural digest entirely — it does not
combine with it. Matching version strings on both sides suppress stale
reclassification even when the underlying shapes differ, which is exactly
the escape hatch a deliberately loose client (a canary, a test double, a
tolerant reader during an expand window) needs.

The whole mid-deploy arc is pinned as a runnable test in
`examples/07-tracker`: a deliberately _stale-shaped_ client — the old
deploy, no schema preflight — sends a bad request across the real wire, the
server's input decode rejects it, and `server/bad-request` comes back
projected onto form fields with `fieldIssues`, asserted at exactly one wire
call. The failure mode every production app has during a rollout, and the
one no framework's docs can usually demonstrate.

Deploys then stay boring the same way database migrations do: **expand, then
contract**. Ship additive changes first (new procedures, new tags — old
clients never call what they don't know about), and make removals and
reshapes a later deploy, after the previous client generation has drained.
When a stale tab does cross the window, it reloads once instead of
mis-reporting a bug. This is the same discipline
[onwardpg](https://github.com/jokull/onwardpg) enforces for the database tier
— expand while old code is live, contract after it drains — applied one
level up, between the server and the browsers it left behind.

---

# Entities
Source: https://result-rpc.com/concepts/entities

Update your profile picture. The avatar in the header, the byline on every
cached doc, and the member row in settings all show the new picture
**immediately** — no query invalidated, no refetch issued, nothing written at
any call site:

```ts
export const User = defineModel("user", {
  key: "id",
  shape: { id: wire.string, name: wire.string, avatarUrl: wire.url },
})

const setAvatar = server.procedure()
  .input(wire.object({ key: wire.string }))   // a bucket reference; bytes are out of band
  .output(UserCard)                            // ← returns WHO changed
  .mutation(...)
```

The mutation returned a `user` entity; the cache knows every query whose
result contains `user:u_1`; each one is patched in place — automatic
invalidation and automatic updates by model + id.

On the client, the full extent of the wiring is the mutation call itself:

```tsx
<select onChange={(e) => assign.mutate({ issueId, assigneeId: e.target.value })}>
```

The list row, the detail header, and this very select all update in place.
A test in `examples/07-tracker` asserts it with per-procedure
request counters, not screenshots: after the mutation settles, the counts
equal `{ ...baseline, "issues.assign": 1 }` — one request in the whole
world, zero refetches anywhere.

A model is to values what an error definition is to failures — a named,
shared declaration. `Doc.all("why")` is every field; `Doc.pick("id",
"title")` declares a projection (the key field is mandatory — an entity
without its identity is just data). Use them anywhere in outputs, at any
depth, including inside each other. The mechanics are the decode pass you
already pay for: decoding brands entity objects, the runtime indexes every
cached result by the entities it contains, and mutations that return
entities patch by identity. There are no heuristics and no schema walking —
**an inline `wire.object` collects nothing, silently**; composing outputs
from model views is the one discipline this asks of query writers.

Here, **projection describes the declared wire shape, not a mapping
operation**. Model views are strict codecs: `Doc.pick("id", "title")` accepts
exactly those fields and rejects `{ id, title, privateNotes }`; it does not
silently strip `privateNotes`. Select those columns in the database query or
map the row to the exact output shape. TypeScript may accept a wider variable
because structural assignability permits extra properties, but the runtime
codec deliberately does not — otherwise accidental fields could cross the
wire unnoticed.

## Source compatibility

When a model mirrors part of an upstream row or domain type, attach a
compile-time drift proof without importing that source at runtime:

```ts
import type { docs } from "../server/schema.js";

export const Doc = defineModel("doc", {
  key: "id",
  shape: { id: wire.string, title: wire.string },
}).$satisfies<typeof docs.$inferSelect>();
```

Every model field must exist in the source with the same type and
nullability; extra source fields are allowed and remain outside the wire
contract. `$satisfies<Source>()` works with any source type and returns the
same model. The type-only import is erased, so the source module does not
enter the client graph. See [Model source compatibility](/concepts/model-sources/)
for exact matching rules, limitations, and non-database examples.

Patches follow the **projection rule**: merge only the fields the cached
object already has (one model, one field vocabulary; projections are
subsets). Fields the mutation didn't return stay stale-until-refetch —
correct and honest.

## The division of labor

> **Identities handle field freshness. `.affects()` handles membership.**

A rename updates every cached row by identity. Only "which cached lists
should now contain this new doc" needs a declaration — the same boundary
Graphcache draws with manual updaters, except ours is typed and lives in
the contract. The mutation writer's decision table:

| The write changes…                                        | Use                                                            |
| --------------------------------------------------------- | -------------------------------------------------------------- |
| Fields of an entity                                       | return the entity — auto-patch everywhere                      |
| Fields, but the output must stay scalar                   | `.writes(Doc, (input) => input.id)` — invalidation by identity |
| List membership                                           | `.affects(listQuery)`                                          |
| Entities the output can't mention (cascades, **deletes**) | `touch(Model, id)` in the handler                              |

`touch` rides the response envelope as `model:id` keys — identities only,
never values — and invalidates by identity client-side:

```ts
.mutation(({ input, context, touch }) => {
  await context.db.docs.delete(input.id)
  touch(Doc, input.id)                    // a deleted entity can't be returned
  return ok(true)
})
```

## Optimistic by identity, trivial with client-minted ids

`cache.updateEntity` addresses the cache the way you think about it:

```ts
const rename = useResultMutation(client.doc.rename, {
  optimistic: (input, cache) => ({
    rollback: cache.updateEntity(Doc, input.id, (doc) => ({ ...doc, title: input.title })),
  }),
  onFailure: (_e, _i, ctx) => ctx?.rollback(),
});
```

One line patches the detail view, every list row, every breadcrumb. And if
the client mints ids (cuid2, nanoid, uuidv7), optimistic **creates** stop
being a reconciliation problem: the optimistic entity is born under its
_final_ identity, so the server's response is a no-op patch or a field
correction — nothing re-keys, nothing flickers, and the id doubles as a
natural idempotency key. Add
[fractional indexing](https://github.com/rocicorp/fractional-indexing) and
order becomes a field too: a drag-reorder is one `sortKey` patch and every
cached list re-sorts locally — no list invalidation for reorders, ever.

## What the coherence oracle pins

The entity system is tested by an adversarial suite (30 attack probes,
`tests/entity/`) and a **coherence oracle**: seeded-random interleavings of
mounts, unmounts, mutations, and invalidations against a reference database,
asserting after every settle that active observers match the oracle exactly
(three seeds × 120 operations, ~25k assertions per run). The properties it
pins, several of them fixed by building it:

- **Brands survive every write path.** Entity identity rides a
  brand-preserving structural-sharing pass, so patching twice, refetching,
  hydrating from SSR, and even spreading an entity inside an `optimistic:`
  updater (`{ ...doc, title }` — the brand recovers when the key field
  matches) all keep the entity in the index. `structuredClone`d values held
  outside the cache stay inert — the WeakMap doesn't travel.
- **Patches never launder staleness.** A patch is entity-partial: it leaves
  the freshness clock and any pending invalidation exactly as they were, so
  a list created-into while unmounted still refetches its membership on
  remount, patch or no patch.
- **Rollback is entity-scoped.** Rolling back one entity's optimistic patch
  never erases a later confirmed write to a different entity in the same
  query — no whole-query snapshots.
- **In-flight responses can't regress a patch.** A refetch racing a patch is
  cancelled and the query reconciled — the stale response never lands on top
  of fresher entity state.
- **Subscription events patch caches.** A live event's decoded entities
  drive the same write-through as a mutation output: the header updates when
  the stream says so.
- **Racing mutation responses apply in arrival order** (no versions exist on
  the wire). For contended entities, `touch` or `invalidateEntity` reconciles
  — a refetch always converges. Documented semantics, pinned by test.

## A model is not a view

This is the one rule in the entity system that exists for **security**, not
ergonomics:

> A model is the full truth about a row. An output ships one audience's view of
> it. A model never reaches an output un-scoped.

```ts
export const User = defineModel("user", {
  key: "id",
  shape: {
    id: wire.string,
    name: wire.string,
    email: wire.string,
    avatarUrl: wire.url,
    latestLat: wire.number,
    latestLng: wire.number,
  },
});

// Name the audiences once, beside the model.
export const UserRef = User.pick("id", "name"); // a mention
export const UserCard = User.pick("id", "name", "avatarUrl"); // a card
export const UserSelf = User.all("the viewer is the subject of this record");
```

The identity declaration is part of the model's type, not a runtime convention.
Only fields whose codecs decode to `string` or `number` may be keys; nullable
and object-valued fields are rejected by `defineModel`. Every `pick` and
`select` must include all key fields, so omitting `locale` from a composite
`["id", "locale"]` identity is a compile error. The runtime checks remain as a
defense for untyped JavaScript inputs.

```ts
friends.output(wire.array(UserCard)); // can only ever ship three fields
me.output(UserSelf); // wide, and it says why
```

**Why it is not merely style.** The dangerous version of this bug is not
picking the wrong field today — that is visible in the diff of the endpoint
that leaks. It is someone adding `latestLat` to the model _next month_ for the
profile page, and every output that consumed the whole model silently
beginning to ship it. That leak appears in a diff which does not touch the
leaking endpoint, so no reviewer of that change is looking at your friend
list, and no test fails. A per-output allowlist cannot widen retroactively,
which closes the entire class.

Three forms, in order of how often you should reach for them:

| Form                  | Use it for                                                     |
| --------------------- | -------------------------------------------------------------- |
| `Model.pick("id", …)` | the flat 80% case; every key field is required by the compiler |
| `Model.select({ … })` | nesting and computed fields; all key fields remain required    |
| `Model.all("why")`    | genuinely every field — costs a sentence that lands in review  |

`select` takes one flat map: `true` for the model's own fields, a **codec** for
anything nested or computed, so relationships and one-off aggregates read
alike and every level keeps entity identity:

```ts
export const HotelCard = Hotel.select({
  id: true,
  name: true,
  topReviewer: UserCard, // another model's view — still patches
  recentReviews: wire.array(ReviewRow), // to-many
  reviewCount: wire.number, // computed, not a column
});
```

Be clear-eyed about what this buys: **selection is not authorization.** Picking
`latestLat` into a friend list is still a leak; the type system cannot know who
is looking. What it guarantees is that every widening is a local, visible,
reviewable act instead of an invisible consequence of an edit somewhere else.

Two supporting properties make the guarantee hold end to end. The explicit
model shape asks _may this field ever cross the wire_; `.pick()` at the output
asks _does this endpoint ship it_. An optional `$satisfies<Source>()` proof
catches upstream type drift without widening either allowlist. At the cache
layer, a patch only overwrites keys a row **already holds**, so a mutation
returning `UserSelf` cannot add coordinates to a cached `UserCard` row.

## When to mint a model (and when never to)

The system is opt-in **per node, not per query** — there is no gate where a
shape must be classified. Every new query starts life as one-off
`wire.object`s, exactly like the tRPC output you'd have written anyway. Mint
a model when you notice recurrence, and apply one rule: **will a mutation
somewhere else ever need to update this field on this screen without a
refetch?** No → leave it a one-off. Yes → model the keyed core, and
only its _context-free_ fields — values that are true about the entity in
every query (`name`, `phone`), never values relative to the query's input (a
`minAvailable` computed over the requested date range lives in the
surrounding one-off shape, where it is immune to patching by construction).

There is no demotion event. Aggregates never enter models, so a new
aggregate can never break one — compose (`{ order: Order.pick("id"),
rank }`) or skip the model for that query; both are correct. The asymmetry
is the point: **under-modeling costs nothing** (an unmodeled node degrades
to exactly the invalidate-and-refetch world you already live in), and
over-modeling is bounded by the context-free rule. Relationships are never
declared — they live in each query's output shape, discovered per result by
walking, so there is no relation schema to keep in sync.

`examples/08-bookings/NOTES.md` applies these rules to real-world
shapes — a four-level relational tree, locale-variant content under a
composite key, query-relative aggregates, derived summaries — with a table
justifying every single node as model, pick, or one-off, and request
counters proving each choice.

## What this deliberately is not

There is no normalized store. Per-query results stay the source of truth —
denormalized, exactly typed — with an identity index over them. The
store-as-source-of-truth design (Graphcache, Apollo) exists to serve
flexible queries and would trade away exact per-procedure output types,
which everything else here is built on. Permanent non-goal.

---

# Errors
Source: https://result-rpc.com/concepts/errors

Throwing `TRPCError({ code: "NOT_FOUND" })` for an anticipated outcome routes
that branch through a shared exception channel rather than making it part of
the procedure's exact return type. A custom formatter can enrich the channel,
but the caller still does not receive a closed, procedure-specific `E` union.

Here an error is a definition: a namespaced tag, a wire codec for its data,
and its policy (HTTP status, retry, visibility) — declared once, shared by
both sides:

```ts
import { error, wire } from "result-rpc";

export const DocNotFound = error({
  tag: "doc/not-found",
  data: wire.object({ docId: wire.string }),
  httpStatus: 404,
});

export const Unauthorized = error({ tag: "auth/unauthorized", httpStatus: 401 });

export type DocNotFound = ReturnType<typeof DocNotFound>;
export type Unauthorized = ReturnType<typeof Unauthorized>;
```

Or declare a whole namespace at once — keys become tags, so the tag string is
never written twice and cannot drift from the name:

```ts
export const docErrors = defineErrors("doc", {
  notFound: { data: wire.object({ docId: wire.string }), httpStatus: 404 },
  locked: { data: wire.object({ lockedBy: wire.string }), httpStatus: 409 },
});

docErrors.notFound({ docId }); // TaggedError<"doc/not-found", { docId: string }>
```

The key→tag rule is mechanical: camelCase keys become kebab-case tag
segments under the namespace — `notFound` → `doc/not-found`, `titleTaken` →
`doc/title-taken`. Shells index definitions by tag and tests assert tags, so knowing the
derivation beats guessing it at a distance.

Public definitions use the same map shape everywhere: procedure `.errors()`,
middleware `.errors()`, and shell `claims:` all take a map of definitions, so
one exported map is declared once and reused on both sides of the wire.
`pickErrors(docErrors, "locked")` selects the subset a procedure actually
declares. Grouping is always by these values, never by matching on the tag
string — the namespace prefix exists only so tags stay unique and readable.
Four namespaces are reserved for the framework's own errors: `client/`,
`server/`, `protocol/`, and `control/`; `error()` rejects tags that use them.

`retry` defaults to `"never"`, `visibility` to `"public"`, and `data` to an
empty object codec. Data-free definitions are called with no arguments:
`Unauthorized()`. `httpStatus` is an optional HTTP-adapter projection; when
omitted, the HTTP adapter carries the application failure in a neutral 200 RPC
envelope. When supplied, it accepts the common vocabulary by name —
`"not-found"`, `"conflict"`, `"too-many-requests"` — or any 4xx/5xx number.

Calling a definition creates the complete error value:

```ts
const failure = DocNotFound({ docId: "doc_123" });

failure instanceof Error; // true
DocNotFound.is(failure); // true
failure.name; // "doc/not-found"
failure.data.docId; // "doc_123"
failure.visibility; // "public"
failure.toJSON(); // { _tag: "doc/not-found", data: { docId: "doc_123" } }
```

The definition is the runtime identity and the namespaced tag is its portable
wire identity. A shape-compatible object is intentionally insufficient:

```ts
err({ _tag: "doc/not-found", data: { docId: "doc_123" } });
//  ^ type error — not a reified TaggedError
```

Each definition creates its own `TaggedError` subclass. On the server,
`DocNotFound.is(value)` verifies that exact definition's instance. Across the
wire, result-rpc downgrades the instance to its canonical `{ _tag, data }`
form, validates the tag against the procedure registry, decodes `data`, and
constructs a fresh instance from the same definition on the client:

```ts
const result = await client.doc.byId({ id: "missing" });

if (!result.ok && DocNotFound.is(result.error)) {
  result.error instanceof Error; // true, after the wire
  result.error.data.docId; // string
}
```

The client instance is faithful, not literally the server object: server
stack and cause are never transmitted. HTTP status and retry behavior remain
projections of the definition's identity. There is no public shallow
`Result.serialize()` — values cross the RPC boundary only through the
definition's actual encoder and decoder.

## Expected failures and unexpected exceptions

Expected failures are part of the contract. Unexpected exceptions are not.
If a caller can anticipate an outcome and make a useful decision from it,
return the declared tagged value through explicit control flow:

```ts
if (!doc) return err(errors.DocNotFound({ docId }));
```

Throwing that same outcome is not an alternate encoding. An exception escapes
the handler's declared `Result`, so the server boundary treats it as
unexpected: the private cause is sent to `onInternalError`, correlated with an
incident ID, and projected to the client as a sanitized `server/internal`.

```ts
throw new Error("database connection disappeared");
// server observability: original cause + incident ID
// client Result: ServerInternal({ incidentId })
```

This keeps the two paths useful. Declared failures produce structured Result
events suitable for product metrics, retries, and UI ownership. Unexpected
exceptions remain high-signal incidents with their causes available only on
the server. Throwing is still used for programmer errors, cancellation,
deliberate boundary escalation, and failures that were not adopted into a
declared domain error.

Use `tryPromise` at a throwing dependency boundary when the failure is an
anticipated part of the operation. Its catch mapper must construct a tagged
error, making the decision to expose, fold, or keep a provider failure private
visible in code.

## Public and private errors

Visibility is part of the definition and the resulting instance type. Omitted
means `"public"`. Use `visibility: "private"` for server-only failures that are
valuable while composing `Result`s but unsafe or meaningless as client API:

```ts
const UniqueConstraint = error({
  tag: "db/unique-constraint",
  data: wire.object({ constraint: wire.string }),
  visibility: "private",
});

r.procedure().errors({ UniqueConstraint });
//                    ^ type error: private errors cannot enter an RPC contract
```

Fold that failure into a public domain error before returning from the handler.
Private definitions cannot declare `httpStatus`; the public error owns that
projection if it needs one.
The type boundary covers procedures, middleware, and layers. Runtime
sanitization remains as defense in depth for JavaScript and unsafe casts.
Visibility is not a tree-shaking annotation: define private adapters in a
server-only module so their database or vendor imports never enter the client
bundle graph.

## The client-wide public union

Every client carries a flattened, `_tag`-discriminated union of all public
domain and framework errors in its contract:

```ts
import type { ClientErrors } from "result-rpc/client";

type AppError = ClientErrors<typeof client>;

if (client.$errors.is(unknownFailure)) {
  unknownFailure satisfies AppError;
  unknownFailure.visibility; // "public"
}

client.$errors.definitions; // runtime registry of the same public definitions
```

This is derived from the contract. Private definitions are absent by type, and
the client never trusts a visibility claim sent by the server.

This guarantee belongs to the result-rpc wire. `JSON.parse(JSON.stringify(error))`
produces the canonical plain representation, not another instance;
`DocNotFound.is(...)` correctly returns `false` until `DocNotFound.decode(...)`
upgrades it again. The same warning applies to framework RPC systems and
component-prop serializers that know nothing about the result-rpc contract.

## Result is total — partial availability is a value

`Result<T, E>` cannot say "the doc loaded, but its author panel is
unavailable." That is deliberate. GraphQL spent a decade with nullable
fields as ambient partial failure and is now retrofitting field-level error
semantics (Relay's `@catch`/`@throwOnFieldError`) — a directive on the
_query_, deciding per call site how much failure to tolerate.

Here the same fact is modeled where every other fact lives: in the output
type. If a field can be independently unavailable, say so in the schema —

```ts
.output(wire.object({
  doc: DocView,
  author: wire.union([
    User.pick("id", "name", "avatarUrl"),
    wire.object({ unavailable: wire.literal(true) }),
  ]),
}))
```

— and the component branches on a value, exhaustively, like everything
else. The operation still resolves one Result: the _call_ succeeded, and
"the author service was down" is part of what it successfully learned. No
directive vocabulary, no per-call-site tolerance policy, no nullable-means-
maybe-failed ambiguity: a partial outcome is a declared shape on the wire,
visible in the contract diff like any other API decision.

## The router is the error registry

One tag maps to exactly one definition across the whole application. Two
procedures reusing a tag must share the definition — the same reference — and
`server.router(...)` rejects a tag redeclared with a different definition at
build time. This is what makes tags safe as global registry keys: a shell uses
the tag to find a candidate and the exact definition to prove ownership, so a
tag can never mean two different things in one app. The
registry is inspectable at runtime:

```ts
// tag → definition. Keyed by `string`: this is the map the client decodes
// against and a devtools panel can enumerate, not a typed lookup.
appRouter.errors;
```

TypeScript catches incompatible duplicate declarations when their tag, codec,
or visibility types differ. It cannot mint a fresh nominal type for each call,
so two separate `error()` calls with exactly the same structural signature are
indistinguishable statically. Router construction therefore always performs
the final reference-identity check. Share exported definition constants; do
not redeclare a tag and rely on structural equality.

The key stays `string` on purpose. `ReadonlyMap` is invariant in its key type,
so narrowing it to the tag union would make a concrete router stop satisfying
`AnyRouter` — the erased runtime bound every function here accepts. For
compile-time exhaustiveness over declared errors, reach for
[`errorCatalog`](/concepts/client/) instead; that is
the typed door, and this is the runtime window.

## Retry policy follows the tag

Retry behavior is declared with the error rather than reconstructed from a
message or overlapping status code:

```ts
export const ServiceUnavailable = error({
  tag: "search/service-unavailable",
  httpStatus: 503,
  retry: "transient",
});

export const RateLimited = error({
  tag: "search/rate-limited",
  data: wire.object({
    retryAfterMs: wire.integer({ min: 0, max: 60_000 }),
  }),
  httpStatus: 429,
  retry: "after",
});
```

**Mutations are stricter by default.** A query retries `transient` and
`after` tags freely — reads are idempotent. A mutation whose connection
died mid-flight is _ambiguous_: the server may have processed it, and a
blind retry is the double-side-effect bug. So by default a mutation retries
only two failures: `client/offline` (the transport short-circuits before
sending — the request provably never left the client) and policy
`retry: "after"` (the server responded and scheduled the retry, so it chose
not to process the attempt). Everything else — network failure, timeout,
5xx — surfaces immediately. Idempotent mutations can opt back in with
`retry:`; idempotency keys are the roadmap item that will make full retry
the safe default. The `retryable` field on `client/network-failure` means
"provably never left the client" — and a fetch rejection cannot prove
that, so it is honest and `false`.

The query runtime owns query retry. A transport retry loop does not silently
run underneath it. Direct calls can opt into the same policy:

```ts
const result = await client.search.run(input, {
  retry: "from-error-policy",
});
```

---

# Layers
Source: https://result-rpc.com/concepts/layers

The footgun: every authenticated app maintains three artifacts that must agree
and drift apart anyway — the server middleware that resolves the session, the
`/me` endpoint the client bootstraps from, and the React context that hands
`user` to components. Three files, one concept, no compiler between them.

A **layer** (this word means exactly this artifact, nothing else in this
document) is the one shared declaration those three derive from: the context
key it fills, the wire codec of the value it guarantees, and the errors that
occur while establishing it.

```ts
// shared
import { defineLayer } from "result-rpc";

export const AuthLayer = defineLayer({
  name: "auth",
  key: "user", // the context property and the guarantee
  provides: UserCodec, // wire codec for the guaranteed value
  errors: { Unauthorized, SessionExpired },
});
```

The server half derives from it:

```ts
// server
import { serverRpc } from "result-rpc/server";

const server = serverRpc.context<AppContext>();
const authenticated = AuthLayer.middleware(server, async ({ context, errors }) => {
  const user = await context.auth.user();
  return user ? ok(user) : err(errors.Unauthorized());
});
// Middleware<AppContext, AppContext & { user: User }, typeof AuthLayer.errors>

export const whoami = AuthLayer.procedure(server, authenticated);
// the context procedure: {} -> User with the layer union. Its handler is
// derived — it returns the user the middleware placed in context — so the
// endpoint *cannot* disagree with the middleware. That is the drift, deleted.
```

(Contract-first codebases put `AuthLayer.contract(app)` in the shared contract,
then call `AuthLayer.implement(server, contract, authenticated)` on the server.)

And the React half is its sibling:

```tsx
// client
import { layerShell } from "result-rpc/react";

export const AuthShell = layerShell(AuthLayer, {
  from: DefectShell,
  select: (client) => client.auth.whoami,
  onError: () => redirect("/login"),
});
```

`select` is the deferred form: it receives the client registered with
`result-rpc/react` when the provider mounts. If a module already owns a concrete
client value, `procedure: client.auth.whoami` is also valid; a function belongs
under `select`, never `procedure`.

This **replaces** the hand-declared `AuthShell` from the shells section — same
name, same claims, drop-in for every `AuthShell.useQuery` call site — and adds
what the hand-rolled one couldn't have: `AuthShell.Provider` loads the value
through the context procedure (rendering `fallback` until it resolves),
provides it to the subtree, and auto-resumes held work when the value is
re-established. `defineShell` remains the tool for shells that aren't backed
by a context procedure — transport banners, defect boundaries. The load
itself runs under the enclosing shells, so an offline blip during
establishment pauses under the app shell like any other operation; only the
layer's own errors reach `onError`.

The middleware, the endpoint, and the shell all close over the same `provides`
codec and the same error map. There is nothing left to keep in sync.

## Optional layers refine into required ones

A session cookie may or may not resolve to a user, and public pages want
`viewer: User | null` while account pages want `User`. Declare the optional
layer with no errors — it always establishes — and derive the required layer
by refinement:

```ts
export const SessionLayer = defineLayer({
  name: "session",
  key: "viewer",
  provides: wire.nullable(UserCodec),
  errors: {}, // optional: cannot fail
});

export const ViewerLayer = SessionLayer.require({
  name: "viewer",
  provides: UserCodec, // the narrowed value
  errors: { Unauthorized }, // the union the refinement contributes
  refine: ({ value, errors }) => (value === null ? err(errors.Unauthorized()) : ok(value)),
});
```

On the server, context grows and narrows monotonically through the chain:

```ts
const session = SessionLayer.middleware(server, ({ context }) => ok(await userFromCookie(context))); // User | null — never fails

// No resolver: the refinement is derived. Passing `session` bundles the
// parent, so one `.use(requireViewer)` pulls the whole chain in order.
const requireViewer = ViewerLayer.middleware(server, session);

server
  .procedure()
  .use(requireViewer) // session runs first: viewer is User
  .query(({ context }) => ok(greet(context.viewer)));
```

Required layers always receive their parent middleware. Internally the
refinement composes it with `.after()`, so `requireViewer` is the **one composed
middleware** a procedure accepts:

```ts
export const viewer = ViewerLayer.procedure(server, requireViewer);
```

There is no parentless required-layer shortcut and no loose middleware array;
the input/output context relationship and the accumulated error map stay in
one inferred value.

On the client the same shape appears as nested providers — the optional shell
claims nothing and provides the nullable value; the required shell claims
`Unauthorized` and provides the narrowed one:

```tsx
const SessionShell = layerShell(SessionLayer, {
  from: DefectShell,
  select: (client) => client.session,
});
const ViewerShell = layerShell(ViewerLayer, {
  from: SessionShell,
  select: (client) => client.viewer,
  onError: () => redirect("/login"),
});

// public page, inside SessionShell
SessionShell.use(); // User | null

// account page, inside ViewerShell
ViewerShell.use(); // User
```

## Keeping it honest

Narrowing this cheap can quietly become swallowing, so both halves of the
claim are assertable. The absorbed set is a runtime value:

```ts
AuthShell.claimedTags;
// ["auth/unauthorized", "auth/session-expired", "client/stale",
//  "client/http-failure", "client/protocol-violation", "client/decode-failure",
//  "server/bad-request", "server/internal", "client/offline",
//  "client/network-failure", "client/timeout"]
```

and the component-visible union is a compile-time probe — a two-line pattern
that pins exactly what a component can be asked to render, forever. This is
the artifact tRPC cannot produce: a test asserting which error codes a call
site can surface.

```ts
type Equal<A, B> =
  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
type Assert<T extends true> = T;

// doc.byId resolves a dozen possible failures; with shells mounted the page sees one.
const probeDoc = () => ViewerShell.useQuery(client.doc.byId, { id: "x" });
type DocQueryError = Extract<ReturnType<typeof probeDoc>, { state: "failure" }>["error"];
export type _DocPageSeesOnlyNotFound = Assert<Equal<DocQueryError["_tag"], "doc/not-found">>;
```

Add an application-namespace tag to a shell and the probe breaks — narrowing
stays a deliberate, reviewable act. `examples/03-docs/app.test.tsx` runs these
against the full onion.

---

# Model source compatibility
Source: https://result-rpc.com/concepts/model-sources

A model is an explicit public wire contract. When it represents part of an
upstream row or domain object, `$satisfies<Source>()` proves that the selected
fields still agree with that source:

```ts
interface UserRow {
  id: string;
  name: string;
  avatarUrl: string | null;
  passwordHash: string;
}

export const User = defineModel("user", {
  key: "id",
  shape: {
    id: wire.string,
    name: wire.string,
    avatarUrl: wire.nullable(wire.string),
  },
}).$satisfies<UserRow>();
```

The assertion enforces one precise relationship:

- Every model field must exist in the source.
- Its TypeScript type and nullability must match exactly. (`readonly` is not a
  difference in values, so it is compared modulo `readonly` — wire codecs
  decode readonly by design, and a source column typed `string[]` matches.)
- The source may contain additional fields. They do not join the model.
- The method returns the same model and performs no runtime reflection.

`passwordHash` is allowed as a source field but is absent from the model, so
it cannot appear in a model view or RPC response. If `avatarUrl` becomes
non-nullable—or the model forgets that it is nullable—the assertion stops
type-checking. The compiler points at the bare `$satisfies<Source>()` call and
prints each mismatched field together with the model and source types; no
runtime argument is involved.

> **`strictNullChecks` is doing half the work.** Without it, `string` and
> `string | null` are the same type to the compiler, so the nullability half of
> this assertion cannot run — a model that forgot a column was nullable will
> pass. Mismatched scalars are still caught, and the message says so explicitly
> rather than implying a guarantee it did not check.

## Type-only sources

Use `import type` when the source lives in a server module:

```ts
import type { notes } from "../server/schema.js";

export const Note = defineModel("note", {
  key: "id",
  shape: {
    id: wire.string,
    title: wire.string,
    updatedAt: wire.date,
  },
}).$satisfies<typeof notes.$inferSelect>();
```

TypeScript erases that import. The client receives the `defineModel` codec,
not the database table, its builders, driver, or private column names. This
works with any source type: a query row, Prisma payload, Kysely result,
generated API type, or ordinary interface.

## What it does not prove

`$satisfies<Source>()` is a structural drift check. It does not derive or
validate:

- Runtime codecs or refinements
- That the model's declared identity matches a database primary key
- Length, uniqueness, foreign-key, or check constraints
- Mapping logic between differently shaped fields

Those remain explicit contract decisions. If the source uses `created_at`
and the public model uses `createdAt`, map the row in the handler and check
the model against the mapped domain type instead.

`defineModel` itself still enforces the local identity contract: key codecs
must decode to `string` or `number`, and every `pick`/`select` must include all
key fields. `$satisfies<Source>()` does not infer that those fields are the
source system's primary key; it only checks their TypeScript types.

This separation is deliberate: runtime reflection would require importing
and executing the source module in the browser, while type-only compatibility
keeps the model small, inspectable, and bundler-independent.

## Views remain the endpoint allowlist

The model shape answers “may this field cross the wire at all?” A view answers
“does this endpoint ship it?” Continue to scope outputs with `pick`, `select`,
or an explained `all`:

```ts
export const UserRef = User.pick("id", "name");
export const UserCard = User.pick("id", "name", "avatarUrl");
export const UserSelf = User.all("the viewer is the subject of this record");
```

Source compatibility does not widen any of those views.

---

# Mutations
Source: https://result-rpc.com/concepts/mutations

```tsx
import { useResultMutation } from "result-rpc/react";
import { client } from "./client";

function RenameDoc({ id }: { id: string }) {
  const rename = useResultMutation(client.doc.rename, {
    optimistic: ({ title }, cache) => {
      const rollback = cache.update(client.doc.byId, { id }, (doc) => doc && { ...doc, title });

      return { rollback };
    },
    onFailure: (_error, _input, context) => {
      context?.rollback();
    },
    onCancel: (_input, context) => {
      context?.rollback();
    },
  });

  async function submit(title: string) {
    const result = await rename.mutateAsync({ id, title });

    if (!result.ok && result.error._tag === "doc/title-conflict") {
      focusTitleField();
    }
  }

  return <RenameForm pending={rename.state === "pending"} onSubmit={submit} />;
}
```

Write the options inline, exactly as above. The hook reads them through a
ref: the observer is created once per procedure, inline objects and inline
callbacks never resubscribe it, and the current render's callbacks are the
ones that fire. (`MutationOptions` and `QueryCache` are exported from
`result-rpc/react` when you want to hoist an options object anyway.)

## `mutate` or `mutateAsync`

Two calls, the split TanStack Query established, and the difference is whether
anything is waiting on the outcome.

`mutate(input)` returns `void` and **never rejects**. It is the right call from
an event handler, where there is no continuation to protect and nowhere for a
rejection to go.

`mutateAsync(input)` returns `Promise<Result<…>>` and rejects with the
`cancelled` and `claimed` control signals. Reach for it when the next lines
depend on the answer — focusing a field on a conflict, closing a dialog on
success.

The rejection is not an error channel; it is the answer to "should my
continuation run?", and only a caller can be told that. A declared failure
still arrives as a `Result`, never as a throw.

`AuthShell.useMutation` is the narrowed form: claimed failures never reach
`onFailure`, failure `onSettled`, or the returned state—and never make another
request, whether retry was configured as a callback, a count, or inherited
from error policy. `onCancel` still runs with the optimistic context so local
work can be rolled back, and `mutateAsync` rejects with the distinguishable
`claimed` signal, as described under
[What a claimed error does](/concepts/shells/#what-a-claimed-error-does-to-the-operation).

Optimistic rollback runs before observers receive the final failure state.
Cancellation is explicit because cancelling a request cannot guarantee that a
server-side mutation did not happen: call `rename.cancel()`. Cancellation
resets lifecycle state and rejects a pending `mutateAsync` with the
`cancelled` control sentinel; it never appears as an operation `Err`.

## Declared invalidation

You noticed what the example above does _not_ contain: `onSettled` with a
`cache.invalidate` call. That line — the most-repeated and most-forgotten
line in any React Query app, whose absence is a stale-UI bug — lives in the
contract now. A mutation declares its blast radius once, where it is defined:

```ts
const byId = app
  .procedure()
  .input(wire.object({ id: wire.string }))
  .output(DocCodec)
  .query();

const rename = app
  .procedure()
  .input(wire.object({ id: wire.string, title: wire.string }))
  .output(DocCodec)
  .affects(byId, (input) => ({ id: input.id })) // rename touches this doc
  .affects(list) // and every cached list page
  .mutation();
```

Every `useResultMutation` of `rename` — in any component, forever —
invalidates those queries on success. The `map` turns the mutation's input
into the target's input; omitting it invalidates every cached input of the
target. The declaration is also documentation: the contract states which
reads each write disturbs, and a reviewer can see a missing `.affects()` in
the same diff that adds the mutation. Server-driven invalidation (the handler
reporting what it actually touched, over the response envelope) is the
planned extension of the same channel — and with entities (next section),
`.affects()` recedes to what only a declaration can express: membership.

---

# Pagination
Source: https://result-rpc.com/concepts/pagination

Most pagination libraries make you choose between two bad options: refetch the
whole list after every mutation, or hand-splice rows into cached pages and hope
your indices line up. result-rpc does neither. A paginated query is **one cache
entry per list**, and the entity cache patches rows across all loaded pages the
same way it patches everything else — by identity, at exactly one request.

## Declaring a paginated query

`.paginate()` finishes a query builder the way `.query()` does, but it reshapes
both ends of the wire. `.output()` declares the **row** codec; `.paginate()`
wraps it in the page envelope and splits the input into list identity and
cursor:

```ts
const feed = rpc
  .procedure()
  .input(wire.object({ q: wire.string })) // the list identity
  .output(MessageRow) // ONE row's view
  .paginate({ cursor: wire.string }); // cursor codec
```

On the wire the input becomes `{ list: { q }, cursor: string | null }` and the
output becomes `{ items: Message[], nextCursor: string | null }`. The handler
returns one page; `nextCursor: null` means "this is the last page":

```ts
const feed = server
  .procedure()
  .input(wire.object({ q: wire.string }))
  .output(MessageRow)
  .paginate({ cursor: wire.string }, async ({ input, context }) => {
    const after = input.cursor ?? undefined;
    const rows = await context.db.messages.page({ q: input.list.q, after, limit: 20 });
    return ok({
      items: rows.slice(0, 20),
      nextCursor: rows.length > 20 ? rows[19].id : null,
    });
  });
```

The cursor is opaque to the framework — a row id, an offset, a keyset tuple,
whatever your storage wants. It only has to survive the codec you declared.

## Consuming it

```tsx
function Feed({ q }: { q: string }) {
  const feed = AppShell.usePaginatedQuery(client.feed, { q });

  if (feed.state === "pending") return <Spinner />;
  if (feed.state === "failure") return <FeedError error={feed.error} />;

  return (
    <>
      {feed.rows.map((message) => (
        <Row key={message.id} message={message} />
      ))}
      {feed.hasNext && (
        <button onClick={feed.fetchNext} disabled={feed.fetchingNext}>
          Load more
        </button>
      )}
    </>
  );
}
```

`rows` is every loaded page flattened into one list. `fetchNext()` loads the
next page and appends it; `hasNext` falls straight out of the last page's
`nextCursor`. `AppShell.usePaginatedQuery` subtracts the errors claimed by that
shell and its parents from the failure union, exactly like `AppShell.useQuery`.
The remaining failure branch contains only errors this component still owns.
While a shell handles a claimed error, the hook shows the previous rows (or a
pending state when none exist).

The global `useResultPaginatedQuery` also participates in ambient claiming
when rendered under shell providers, but its declared return type remains the
complete procedure union. Use the shell hook when compile-time subtraction is
part of the component boundary.

## Why one cache entry matters

The list input keys the cache; the cursor never does. Every page of one list
lives under a single entry, and three things follow for free:

- **Entity patches reach every page.** A mutation that returns a `Message`
  entity patches that row wherever it sits — page one or page nine — at one
  request, no refetch. The same [entity](/concepts/entities/) machinery that
  patches a detail view and a list row patches paginated rows, because a
  paginated list is just more cached rows.
- **`.affects()` targets the whole list.** A mutation declaring
  `.affects(feed)` invalidates the list with its list-shaped input — you never
  name a cursor. Invalidation converges every loaded page.
- **`refetch()` converges the window.** Refetching replays every loaded page
  in sequence — each page's cursor comes from the previous page's fresh
  response — so the whole loaded window re-verifies, not just page one.

## Rows are deduplicated by identity

Between two fetches, an insert or delete can slide a row across a page
boundary, so the same entity would appear on two pages. `rows` deduplicates by
entity identity: the first occurrence wins its position, and because field
freshness is identity-driven, the dropped copy loses nothing — a patch reaches
the retained row regardless of which page carried it.

## Set a `staleTime` for stable lists

An actively-observed list with the default `staleTime` of `0` re-verifies its
loaded pages whenever the cache is written — correct convergence, but usually
more than you want for a scroll position the user is reading. Give long-lived
lists a `staleTime`:

```tsx
useResultPaginatedQuery(client.feed, { q }, { staleTime: 60_000 });
```

When a component boundary needs to name the inferred state, derive it from the
procedure instead of reconstructing its row, cursor, and error types:

```ts
import type { PaginatedStateOf } from "result-rpc/react";

type FeedState = PaginatedStateOf<AppClient["feed"]>;
```

The corresponding unary and mutation helpers are `QueryStateOf` and
`MutationStateOf`.

With a stale window, a mutation that patches a visible row does so in place at
exactly one request — the row updates, the scroll position holds, nothing
refetches.

`staleTime` is client-memory policy, not backend or CDN
`stale-while-revalidate`. The [React freshness guide](/concepts/react/#freshness-fetch-state-and-backend-caching)
defines the distinction and the relationship between terminal `state`,
concurrent `fetch`, and failed-refresh `previous`.

## Prefetching

`runtime.prefetchPaginated(client.feed, { q })` warms the first page — use it
in a router loader or during SSR, exactly like `prefetch` for unary queries.
Hydrated pages are normalized through the row codec on the way in, so their
entities index and patch even before a component observes the list.

---

# React hooks
Source: https://result-rpc.com/concepts/react

Hand the provider your client; it owns a query runtime for its lifetime:

```tsx
import { ResultRpcProvider } from "result-rpc/react";
import { client } from "./client";

export function Providers({ children }: { children: React.ReactNode }) {
  return <ResultRpcProvider client={client}>{children}</ResultRpcProvider>;
}
```

Pass an explicit `runtime` instead when the app needs the instance elsewhere —
SSR prefetching, imperative cache access.

## Register the application client once

The default React entry follows TanStack's `Register` pattern. Augment it once
and `useResultClient()` returns the application client with no call-site
generic; deferred layer-shell selectors receive the same type:

```ts
import type { client } from "../../client";

declare module "result-rpc/react" {
  interface Register {
    client: typeof client;
  }
}
```

```tsx
import { useResultClient } from "result-rpc/react";

function SaveButton() {
  const client = useResultClient();
  // client.doc.save is known here
}
```

Declaration merging is application-wide. A monorepo that compiles several
independent applications in one TypeScript program should bind a local React
surface instead of registering several clients globally:

```ts
import { createResultRpcReact } from "result-rpc/react";
import type { client } from "../../client";

export const appReact = createResultRpcReact<typeof client>();

export const {
  ResultRpcProvider: AppResultRpcProvider,
  useResultClient: useAppResultClient,
  layerShell: appLayerShell,
} = appReact;
```

Use those three scoped exports consistently inside that application. They
share one client type without global declaration merging. The scoped hook and
layer shells require that binding's matching provider; mixing bindings fails
at the mount site instead of returning a falsely typed client.

Query a procedure:

```tsx
import { useResultQuery } from "result-rpc/react";
import { client } from "./client";

export function DocPage({ id }: { id: string }) {
  const doc = useResultQuery(client.doc.byId, { id });

  switch (doc.state) {
    case "pending":
      return doc.fetch === "paused" ? <OfflinePlaceholder /> : <DocSkeleton />;

    case "success":
      return <DocView doc={doc.value} refreshing={doc.fetch === "fetching"} />;

    case "failure":
      return <DocFailure error={doc.error} previous={doc.previous} retry={doc.refetch} />;
  }
}
```

The hook-level `refetch()` starts a new attempt and returns `Promise<void>`.
Awaiting it tells you the attempt settled; the resulting `QueryState` arrives
through the next React render. It does not return a snapshot or another
`Result`. For imperative code, the lower-level runtime observer's `refetch()`
returns the resulting state directly.

`value` and `error` are not an independently-nullable pair — each exists only
under its own state, so the impossible combinations are unrepresentable:

```ts
doc.value; // Doc      — only when doc.state === "success"
doc.error; // GetDocError — only when doc.state === "failure"
```

When Result-typed code needs the settled outcome as the same `Result` the
direct client returns, `toResult(doc)` re-wraps it (`undefined` while
pending).

The query engine still caches successful values, retries transient failures,
tracks failure counts, pauses offline work, and supports invalidation. It uses
its failure channel internally and projects it back into the public Result
state.

## Freshness, fetch state, and backend caching

`staleTime` is a client-memory freshness window. While cached data is fresh,
mounting another observer reads it without starting a background request. Once
it is stale, the successful value can remain rendered while `fetch` changes to
`"fetching"`; `state` still describes the last terminal outcome, not whether a
request is currently in flight.

```tsx
const availability = useResultQuery(client.availability, {}, { staleTime: 15 * 60_000 });

if (availability.state === "success") {
  availability.value; // current cached success
  availability.fetch === "fetching"; // a background refresh is concurrent
}
```

That `{}` is the procedure's empty input. When passing options to a zero-input
query, the current form is `useResultQuery(procedure, {}, options)`.

If a background refresh fails, the terminal state becomes `"failure"` and
`previous` holds the last successful value. This makes stale-data-plus-error a
single explicit state rather than a hidden second error channel.

This cache lives in the result-rpc query runtime for one application session.
It does not set `Cache-Control`, populate a CDN, cache inside a Cloudflare
Worker, or implement HTTP `stale-while-revalidate`. Backend or edge caching
decides whether the request reaches the origin; query `staleTime` decides
whether the browser starts that request. Configure the two independently.

`useResultQuery` is the unnarrowed hook: it always yields the operation's
complete union. Application code normally reaches for a shell's hooks instead,
so that each part of the tree only presents the failures it is actually
responsible for — that is the next section.

For Suspense, use `useResultSuspenseQuery`. It suspends only while pending and
returns the same success-or-failure state after settlement; tagged failures
remain ordinary Result values rather than becoming a second thrown error type.

When a shell can claim one of those failures, use `ResultSuspense` instead of a
plain React `Suspense` boundary:

```tsx
<ResultSuspense fallback={<DocumentSkeleton />}>
  <Document />
</ResultSuspense>
```

The committed boundary owns the shell lease because a child that suspends on
its first render cannot install effect cleanup. Give independently removable
branches their own boundaries. If a retained boundary switches to a different
conditional subtree, pass that identity as `resetKey` so the old branch's
claims are released.

## Failed background refreshes preserve stale data

A refetch can fail while a cached value remains useful. That is represented
explicitly:

```tsx
if (doc.state === "failure" && doc.previous) {
  return (
    <>
      <DocView doc={doc.previous} stale />
      <RefreshFailure error={doc.error} />
    </>
  );
}
```

`previous` is cached success from an earlier attempt. It is not another error
channel.

## Offline is lifecycle before it is failure

When an operation is waiting for connectivity:

```ts
doc.fetch === "paused";
```

This does not consume a retry or immediately become `client/offline`. An
Offline error appears only if the configured policy settles an attempted
operation as a failure.

## SSR and hydration

```tsx
// Server
import { createQueryRuntime } from "result-rpc/query";

const runtime = createQueryRuntime({ client: serverClient });

await runtime.prefetch(serverClient.doc.byId, { id });

const dehydrated = runtime.dehydrate();

// Browser
return (
  <ResultRpcProvider client={client} hydrate={dehydrated}>
    {children}
  </ResultRpcProvider>
);
```

The cache format is versioned and each hydrated success is validated against
its procedure output codec before use. Invalid data removes only the affected
entry. A query that failed with a **declared** error is dehydrated too — that
error is the answer, and it is reified through the procedure's registry on the
way back in; framework and transport failures are left out, because they
describe one attempt on one machine. Cancellation and transient connection
state are never persisted.

---

# Result composition
Source: https://result-rpc.com/concepts/results

If you use neverthrow or better-result today, this page is the migration
note: the algebra you know is built in, and you can delete the dependency.
One rule is stricter — the error channel only admits reified result-rpc
`TaggedError` instances whose `data` is wire-safe. That restriction is the point. The standalone libraries
let any value ride the error channel because they never have to move it;
here every error is presumed to eventually cross a wire, land in a
procedure's declared union, and be matched exhaustively in a component. The
declared definition supplies both the nominal runtime type and the plain wire
shape, so a merely shape-compatible object is rejected by `err()`.

## The surface

|                     |                                             |
| ------------------- | ------------------------------------------- |
| Construct           | `ok`, `err`, `isOk`, `isErr`                |
| Transform           | `map`, `andThen`, `mapError`, `orElse`      |
| Unwrap              | `match`, `matchError`, `getOrElse`          |
| Observe             | `tap`, `tapError`, `tapBoth`                |
| Adopt throwing code | `tryCatch`, `tryPromise`                    |
| Combine             | `all` (tuple or record, first failure wins) |
| Compose             | `gen` (generator style, `yield*`)           |

All Result operations are standalone and tree-shakeable. A
`Promise<Result>` stays a plain promise you `await` — there is no
`ResultAsync` to learn.

## Generator composition

`yield*` works directly on any Result: it unwraps the value or
short-circuits the whole block on the first failure. The error union
accumulates automatically from everything yielded — no annotations:

```ts
import { gen } from "result-rpc";

const outcome = gen(function* () {
  const doc = yield* findDoc(id); // Result<Doc, DocNotFound>
  const body = yield* parseBody(doc); // Result<Body, ParseFailure>
  return render(doc, body);
});
// Result<Rendered, DocNotFound | ParseFailure>
```

Pass an async generator to compose awaited Results the same way — the return
type becomes a `Promise<Result>`:

```ts
const outcome = await gen(async function* () {
  const doc = yield* await fetchDoc(id);
  return yield* parseBody(doc);
});
```

Three idioms worth knowing: `return yield* err(SomeError({ ... }))` fails a
block explicitly; a `TaggedError` is itself yieldable, so
`return yield* SomeError({ ... })` is the shorter equivalent; and `finally`
blocks run even when an `Err` short-circuits — cleanup composes normally.

## The wire keeps the API, not the object identity

This is where result-rpc goes beyond Better Result's shallow serialization.
The client reconstructs the Result behavior and the exact declared
`TaggedError` type before returning:

```ts
import { gen } from "result-rpc";
import { client } from "./rpc-client";
import { docErrors } from "./errors";

const outcome = await gen(async function* () {
  // The response crossed HTTP. It is still a result-rpc Result, so yield*
  // unwraps success or propagates its reconstructed TaggedError.
  const doc = yield* await client.doc.byId({ id: "doc_missing" });
  const body = yield* parseBody(doc.body);
  return { doc, body };
});

if (!outcome.ok && docErrors.notFound.is(outcome.error)) {
  outcome.error instanceof Error; // true
  outcome.error.data.docId; // "doc_missing"

  const propagated = gen(function* () {
    return yield* outcome.error; // the reconstructed error is yieldable too
  });
}
```

The instance is newly constructed on the client; pretending it is the same
JavaScript object would be meaningless. What survives is the faithful public
API: definition guards, `Error` interoperability, typed data, `toJSON`, and
generator composition.

That fidelity is not portable through arbitrary serializers. JSON, Next
server actions/RPC, and component-prop serialization do not have the
procedure's error registry, so they cannot reconstruct the runtime types.
Unwrap before crossing one of those boundaries:

```tsx
const result = await client.doc.byId({ id });
if (!result.ok) return <NotFound docId={result.error.data.docId} />;
return <DocView doc={result.value} />; // pass T, not Result<T, E>
```

## The worked example: an upstream service, composed to the screen

The pattern that earns this page: a result-ified upstream (`safeJsonFetch`),
granular internally, **collapsed to one declared domain tag at the procedure
boundary** so the client union stays coarse.

The service keeps its own precise error vocabulary:

```ts
// server/services/rates.ts
import { defineErrors, err, gen, tryPromise, wire } from "result-rpc";

export const upstream = defineErrors("upstream", {
  unavailable: { data: wire.object({ status: wire.number }), httpStatus: 502, retry: "transient" },
  malformed: { data: wire.object({ reason: wire.string }), httpStatus: 502 },
});

export const safeJsonFetch = (url: string) =>
  gen(async function* () {
    const response = yield* await tryPromise(
      () => fetch(url),
      () => upstream.unavailable({ status: 0 }),
    );
    if (!response.ok) {
      return yield* err(upstream.unavailable({ status: response.status }));
    }
    return yield* await tryPromise(
      () => response.json() as Promise<unknown>,
      (cause) => upstream.malformed({ reason: String(cause) }),
    );
  });
// Promise<Result<unknown, UpstreamUnavailable | UpstreamMalformed>>
```

`tryPromise` is the border checkpoint: its catch handler must produce a
tagged error, so the upstream's `TypeError`/`SyntaxError` never travels past
the boundary as itself.

The procedure does **not** re-export that granularity. Two upstream tags
would be noise in every component that renders a quote — the caller can't do
anything different with `unavailable` versus `malformed`. So the handler
collapses them with `mapError`, and only the coarse tag enters the contract:

```ts
// server/router.ts
import { error, gen, err, mapError, ok, wire } from "result-rpc";
import { safeJsonFetch } from "./services/rates";

const RatesUnavailable = error({
  tag: "rates/unavailable",
  data: wire.object({}),
  httpStatus: 503,
  retry: "transient",
});

const quote = server
  .procedure()
  .input(wire.object({ currency: wire.string }))
  .output(wire.object({ currency: wire.string, rate: wire.number }))
  .errors({ RatesUnavailable })
  .query(({ input, errors }) =>
    gen(async function* () {
      const payload = yield* mapError(
        await safeJsonFetch(`https://rates.example/api/${input.currency}`),
        () => errors.RatesUnavailable({}), // two granular tags → one declared tag
      );
      const rate = (payload as { rate?: number }).rate;
      if (typeof rate !== "number") return yield* err(errors.RatesUnavailable({}));
      return { currency: input.currency, rate };
    }),
  );
```

The type system enforces the collapse: a handler returning an undeclared
`upstream/unavailable` is a compile error, and one smuggled at runtime is
sanitized to `server/internal`. Simplifying the union is not a style
suggestion — it is the only way past the `.errors()` gate.

On the client, nothing new to learn — it is the same flattened state every
query has, and the domain branch is exactly one tag wide:

```tsx
function Quote({ currency }: { currency: string }) {
  const quote = AppShell.useQuery(client.rates.quote, { currency });

  switch (quote.state) {
    case "pending":
      return <Skeleton />;
    case "success":
      return <Rate value={quote.value.rate} />;
    case "failure":
      return <RatesDown retry={quote.refetch} />;
    // quote.error: RatesUnavailable — the upstream vocabulary never leaked
  }
}
```

That is the full journey: throwing `fetch` → `tryPromise` → granular service
union → `mapError` collapse at the procedure → declared contract → flattened
hook state. One algebra, and each boundary decides how much detail the next
one deserves. When hook-state code needs to hand a settled outcome to
Result-typed code, `toResult(quote)` re-wraps it.

## Composition between layers

Layer middleware resolves to a Result, so `gen` composes there too — the
layer's declared union is the gate, exactly like a procedure's:

```ts
const session = defineLayer({
  name: "session",
  key: "viewer",
  provides: ViewerCodec,
  errors: { SessionExpired, SessionRevoked },
});

const sessionMiddleware = session.middleware(server, ({ context, errors }) =>
  gen(async function* () {
    const token = yield* readToken(context.cookie, errors); // Result<Token, SessionExpired>
    const viewer = yield* await lookupViewer(token, errors); // Result<Viewer, SessionRevoked>
    return viewer;
  }),
);
```

Everything downstream of the middleware sees `context.viewer` as guaranteed;
the failure paths travel the layer's union to the client, where the layer's
shell claims them. Composition on the server, subtraction on the client —
the same union both times.

## Credit and deliberate omissions

This surface ports the core DX of
[better-result](https://github.com/dmmulroy/better-result) and
[neverthrow](https://github.com/supermacro/neverthrow), and happily credits
both. Three things are deliberately not ported:

- **Serialization helpers.** Wire safety is handled by this library's own
  concern — error `data` goes through declared codecs, rich values through
  the versioned serializer. A Result-level `toJSON` would be a second,
  weaker wire story.
- **`ResultAsync` / chained async wrappers.** `await` plus `gen` covers the
  composition; a wrapper class would add a second calling convention to
  every API that touches a promise.
- **`getOrThrow`.** Re-throwing is the pattern the rest of the library
  exists to retire. Where you genuinely want to crash on `Err` (scripts,
  tests), `if (!result.ok) throw result.error` is one honest line.

---

# Shells
Source: https://result-rpc.com/concepts/shells

Remember the 401 interceptor. Now recall that React already solved this exact
shape once, for a different kind of failure. Render errors used to be every
component's private problem; error boundaries made them _positional_: throw
anywhere below, and the nearest boundary that claims it takes over. Three
properties made that design stick:

1. **Tree-positional** — ownership follows the UI, not the call site.
2. **It catches errors from components that never heard of it** — a boundary
   that only caught opted-in throws would be useless.
3. **Unclaimed errors fail loudly** rather than vanish.

A shell is the same contract, transplanted from thrown render errors to
failure _values_. A shell is a provider that claims a map of error definitions.
Any operation rendered beneath it — no matter which hook issued it — that fails
with an instance recognized by one of those definitions is routed to the shell
instead of surfacing as component state. The 401 interceptor becomes a typed
declaration with a position in the tree, and the errors it owns disappear from
the unions below it.

## Three tiers of failure, three built-in owners

The tiers are nothing more than which definition map you hand to which shell —
there is no classification field:

| What failed                      | Example tags                                                            | Reaction                                        | The map                  |
| -------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------- | ------------------------ |
| The domain said no               | `doc/not-found`, `auth/unauthorized`                                    | the component branches, or an auth shell reacts | your `defineErrors` maps |
| The world flaked                 | `client/offline`, `client/timeout`, `client/network-failure`            | pause, banner, resume                           | `transportErrors`        |
| The contract broke               | `client/protocol-violation`, `client/decode-failure`, `server/internal` | escalate to the error boundary                  | `defectErrors`           |
| A deploy left this client behind | `client/stale`                                                          | reload — the reload _is_ the fix                | `staleErrors`            |

The framework contributes every non-domain row, so the framework ships their
owners pre-assembled — assembling them by hand was the same ten lines in
every app:

```tsx
import { boundaryShells } from "result-rpc/react";

export const { TransportShell, DefectShell, StaleShell, BoundaryProvider, useConnectivity } =
  boundaryShells();
// TransportShell  claims transportErrors, pauses; useHeld() feeds the banner
// DefectShell     claims defectErrors, escalates to the React error boundary
// StaleShell      claims staleErrors; default reaction reloads the page
```

`BoundaryProvider` is also the browser bridge. It closes the reconnect arc
automatically — claim, hold, the browser fires `online` (or the window
regains focus while failures are held), resume — and the runtime feeds the
same connectivity source into the query engine's online manager. Opt out
with `boundaryShells({ autoResume: false })`.

Accurate connectivity is also the anti-thrash lever. While the browser is
offline, **reads pause** — fetches and retries wait as `fetch: "paused"`
instead of failing instantly and burning the retry budget, and the engine
continues them on reconnect (pinned by test: a query mounted while offline
makes **zero** wire calls, then exactly one on reconnect). **Writes stay loud** — a mutation attempted
offline fails once with `client/offline` for its owner to decide; the
framework never queues a side effect for silent later delivery. Offline
failures are never retried on a timer while the browser still reports
offline (recovery is the reconnect, not the clock), and focus-triggered
resumes are cooled down so alt-tabbing at a downed server never becomes a
retry storm.

The table-stakes offline banner is `useConnectivity()` — an honest
two-source signal, exhaustively switchable like everything else here:

```tsx
function ConnectionBanner() {
  const net = useConnectivity();
  switch (net.status) {
    case "online":
      return null;
    case "offline":
      return <Banner>You're offline — paused work resumes automatically.</Banner>;
    case "degraded":
      return <Banner action={net.resume}>Connection trouble — retrying…</Banner>;
  }
}
```

`"offline"` is the browser's own claim (`navigator.onLine` + events) — it
lights up before any request fails. `"degraded"` is the proof side: the
browser claims online, but the transport shell is holding real failures
(captive portals, flaky proxies). The two sources are kept distinct because
adjacency isn't identity — browser connectivity is a cause-side hint,
transport errors are outcomes. The hint never mints or suppresses an error
tag and never touches the cache; it only times resumes and informs the
banner. `net.held`, `net.latest`, and `net.resume` are there for custom UX.

You only ever _write_ shells for what the app itself owns:

```tsx
import { defineShell } from "result-rpc/react";
import { authErrors } from "../shared/errors";

export const AuthShell = defineShell({
  name: "auth",
  from: StaleShell, // hang off the innermost built-in
  claims: authErrors,
  onError: (_error, { signOut }) => signOut(),
  provide: (props: { session: Session; signOut: () => void }) => ({
    user: props.session.user,
    signOut: props.signOut,
  }),
});
```

Mount them as an onion:

```tsx
<ResultRpcProvider runtime={runtime}>
  <BoundaryProvider>
    {" "}
    {/* transport pauses · defects escalate · stale reloads */}
    <ErrorBoundary fallback={<AppBroken />}>
      <AuthShell.Provider session={session} signOut={signOut}>
        <Routes /> {/* components below see ONLY their domain errors */}
      </AuthShell.Provider>
    </ErrorBoundary>
  </BoundaryProvider>
</ResultRpcProvider>
```

Inside `Routes`, an operation resolving ten possible tags presents one:

```tsx
export function DocPage({ id }: { id: string }) {
  const { user } = AuthShell.use(); // User, not User | null
  const doc = AuthShell.useQuery(client.doc.byId, { id });

  switch (doc.state) {
    case "pending":
      return <DocSkeleton />;
    case "success":
      return <DocView doc={doc.value} viewer={user} />;
    case "failure":
      // DocNotFound — and adding a case for anything else is a type error
      return <DocMissing docId={doc.error.data.docId} />;
  }
}
```

And when a query's domain union is _empty_ — a list that declares no domain
errors, rendered under a complete onion — the failure branch becomes a
compile-time certificate that the owners are mounted:

```tsx
switch (issues.state) {
  case "pending":
    return <p>Loading issues…</p>;
  case "success":
    return <IssueRows issues={issues.value} />;
  case "failure":
    // transport, defect, stale, and auth are all claimed above; nothing
    // domain remains. This line compiles ONLY while that is true — remove
    // a provider from the tree and the build fails, right here.
    return issues.error satisfies never;
}
```

No test can make that claim. The type checker makes it on every build.

## How claiming actually works

Claiming is **per observer and tree-positional**. Each hook, at its render
position, uses the failure tag to find a candidate definition in an enclosing
shell, then asks that exact definition to recognize the instance. The
cache is never rewritten: the entry still holds the real `Err`, refetch
bookkeeping continues underneath, and an observer of the same cache entry
rendered _outside_ the shell still sees `state: "failure"`. A shell changes
how a failure presents where it presents — nothing else. The innermost shell
claiming the definition owns it.

The type story has two halves:

- **Shell hooks subtract.** `AuthShell.useQuery` removes the chain's exact
  claimed error signatures from the union — and eagerly asserts, at mount, that every shell in
  the chain is actually mounted above it. The subtraction is only honest if
  the owners exist, so a missing provider throws on _first render_, the same
  contract as any context hook without its provider. You find out on the
  happy path in development, not on the error path in production.
- **Plain hooks over-approximate.** `useResultQuery` keeps the full union.
  Under a mounted shell, the claimed errors in that type are unreachable —
  the shell routes them — exactly the way a `try/catch` inside an error
  boundary lists exceptions the boundary would have caught anyway.
  Unreachable, not untrue; and outside any shell, the same type is exact.

Property 2 of error boundaries is why interception cannot be opt-in per hook:
if a plain hook under `AuthShell` could surface `auth/session-expired` as
component state, the shell's guarantee — and every narrowed union derived from
it — would be a lie. Ownership is positional or it is nothing.

To genuinely own a claimed error yourself, render outside the shell that owns
it. The login page lives outside `AuthShell` and handles
`auth/session-expired` as an ordinary failure, because there is no session to
guarantee there.

## The chain is a value, not an inference

`from:` makes the accumulated claim set a property of the shell value.
`AuthShell` is typed with its own claims plus everything `DefectShell` and
`AppShell` claim, and nobody writes that union by hand. Narrowing never
depends on TypeScript inferring where a component sits in the tree — you
cannot reach `AuthShell.useQuery` without importing the shell that declares
the chain, and the chain proves itself mounted at runtime.

Two invariants are enforced at definition time:

- a tag may be claimed **once** per chain — overlapping shells are a
  `TypeError` at startup, not a precedence puzzle later;
- claims only accumulate inward, so an inner shell can never un-handle
  something an outer shell took responsibility for.

## What a claimed error does to the operation

A subtracted error never produces `state: "failure"` — that would be a lie
about a union it is no longer in.

With `effect: "pause"` (the default):

- **Query** — returns to a non-terminal state with `fetch: "paused"`. If a
  cached success exists it keeps rendering as `state: "success"`, stale, so a
  session blip does not blank the screen. If not, `state: "pending"`.
- **Mutation** — state returns to `"idle"`, and `mutateAsync` rejects with a
  **`claimed` control signal**: the caller's continuation was written against
  the narrowed union, so an outcome owned above it must not run it. `mutate`
  is fire-and-forget and never rejects — there is no continuation to stop. The signal is the same _family_ as cancellation — control flow,
  never part of a recoverable union — but deliberately distinguishable,
  because "you cancelled" and "a shell owns this outcome" are different
  events. `isClaimed(reason)` identifies it and carries the claimed tag and
  the owning shell's name (never the error value), so a form can render "you
  were signed out" instead of silently resetting:

  ```ts
  import { isCancelled, isClaimed } from "result-rpc/client";

  try {
    await rename.mutateAsync({ id, title });
  } catch (reason) {
    if (isClaimed(reason))
      reason.data; // { tag: "auth/session-expired", owner: "auth" }
    else if (isCancelled(reason)) {
    } // user cancelled; nothing happened for sure
    else throw reason;
  }
  ```

- **Subscription** — `connection` becomes `"paused"` and `result` stays
  `undefined`.

With `effect: "escalate"`, the tagged value is thrown to the nearest React
error boundary as the reified `TaggedError` instance, so ordinary `Error`
tooling and `matchError` both work on it. Escalation creates no holding, does
not call the shell's `onError`, and emits no `claimed` breadcrumb: the error
boundary owns that observation.

For a pausing shell, `onError` fires once per newly held error per observer.
One logical event — a revoked session — can arrive on every in-flight
operation at once, so handlers must be idempotent (a redirect, a `signOut()`,
a toast keyed by tag). Calling `resume()` starts a fresh attempt; if it fails
with the same owned error, that new holding may call `onError` again.

## The pause arc ends in resume

Held is not stuck. Every held operation carries a retry handle, and the shell
exposes the whole set:

```tsx
const { latest, affected, resume } = AuthShell.useHeld();
// after re-authenticating:
resume(); // every held query refetches; held subscriptions reconnect
```

Held mutations reset to idle — their failure already reached the caller as the claimed rejection, and replaying a side effect is never the shell's call. Resetting ends the pause arc, so holdings (and the connection banner) drain on resume.

Layer shells (below) close the loop automatically: when the layer's context
procedure re-establishes its value (sign back in, invalidate `client.auth.me`),
every operation the shell was holding resumes without a line of app code.
Mid-session revocation therefore plays out as: refetch fails → shell holds it
→ the stale value keeps rendering → re-auth → held work refetches fresh. The
screen never blanks and no component ever branched on it.

Unmounting a holding shell releases its holdings cleanly — observers release
on their own unmount, `onError` does not re-fire, nothing leaks. A fresh mount
is a fresh world: a cached failure encountered again is claimed again.

## Ambient failures are aggregate, not per-operation

Twelve paused queries are not twelve offline states. The shell holds them
together:

```tsx
function OfflineBanner() {
  const { latest, affected } = AppShell.useHeld();
  if (!latest) return null;
  return <Banner tag={latest._tag} count={affected} />;
}
```

That is the structural reason the per-operation error channel was the wrong
home for connectivity: no single operation owns it.

## Errors accumulate; shells discharge

The application contract, server boundary, and client boundary all contribute
to the operation union. Middleware is one application contributor: it adds an
error while strengthening server context. A shell claims an error while
providing UI context. Those two operations are inverses over the same shared
declaration:

```text
procedure and middleware failures
+ server-boundary failures
+ client-boundary failures
− enclosing shell claims
= component-visible union
```

```ts
// shared/errors.ts
export const authErrors = { Unauthorized, SessionExpired };

// server
const authenticated = server.middleware<{ user: User }>().errors(authErrors).use(/* ... */);

// client
const AuthShell = defineShell({ name: "auth", claims: authErrors /* ... */ });
```

Add an error to `authErrors` and every derived shell absorbs it; no component
union changes and nothing breaks. Remove one and the components that branched
on it stop compiling. The shared map is a value in the shared contract
package, so no server middleware code reaches the browser bundle.

---

# Subscriptions
Source: https://result-rpc.com/concepts/subscriptions

Declare the stream in the shared contract and attach its generator only on the
server:

```ts
import { serverRpc } from "result-rpc/server";

export const docEventsContract = app
  .procedure()
  .input(wire.object({ docId: wire.string }))
  .output(DocEvent)
  .errors({ Unauthorized, DocNotFound })
  .subscription();

const server = serverRpc.context<AppContext>();
export const docEvents = server
  .implement(docEventsContract)
  .use(authenticated)
  .stream(async function* ({ input, errors, context }) {
    const doc = await context.docs.find(input.docId);
    if (!doc) {
      yield err(errors.DocNotFound({ docId: input.docId }));
      return;
    }

    for await (const event of context.docs.events(input.docId)) {
      yield ok(event);
    }
  });
```

The direct client is an async iterable of the same Result union. React
observes connection state independently from the latest event or terminal
failure:

```tsx
const events = useResultSubscription(client.doc.events, { docId });

events.connection; // "connecting" | "open" | "reconnecting" | "paused" | "closed"
events.result; // Ok<DocEvent> | Err<GetDocEventsError> | undefined
```

Subscriptions are the one hook that keeps a `result` envelope. Queries and
mutations flatten to `value`/`error` because `state` discriminates them;
`connection` is deliberately orthogonal to the latest outcome, so here
`Result | undefined` is the honest shape — flat `value`/`error` fields would
be exactly the independently-nullable pair this library exists to avoid.

`AuthShell.useSubscription` narrows the same way: a claimed terminal failure
leaves `connection` at `"paused"` with no `result`, and the owning shell
reacts. A retryable disconnect moves through `reconnecting` and does not
publish a temporary `Err`; if retry policy is exhausted, the final connection
error appears in `events.result`. Every frame is sequence-checked and
independently encoded by the same versioned serializer as unary and batched
responses.

## Resuming an interrupted stream

By default a reconnect reopens the stream from the top: the handler runs again
from its first line, so events emitted during the gap are lost and events
already delivered may arrive twice. `.resumable()` closes that gap.

```ts
const feed = app
  .procedure()
  .input(wire.object({ roomId: wire.string }))
  .output(Message)
  .resumable({ eventId: (message) => message.id })
  .subscription();
```

```ts
server.implement(feed).stream(async function* ({ input, lastEventId }) {
  // undefined on a first connect; the last event this client saw on a reconnect
  for await (const message of room(input.roomId, { after: lastEventId })) {
    yield ok(message);
  }
});
```

`eventId` derives a resume token from an event's **value**. Both sides run the
same declared function, so the client computes the token from the event it just
decoded and sends it back on the next connect — no event id rides the wire
frame, and the procedure's input codec is unchanged. Resuming is automatic:
the subscription runtime already reconnects on a retryable failure, and this
only decides where the new connection starts.

Three rules worth knowing:

**A changed input is a new stream, not a resumed one.** The resume point is
dropped whenever the subscription is created or its input changes; resuming one
room's position into another room would be wrong.

**A procedure that did not declare `.resumable()` never receives a resume
point**, even if a client sends one. Undeclared handlers cannot be handed
client-supplied state they never asked for.

**`.resumable()` is in the contract digest.** A client and server that disagreed
about it would silently re-deliver events after a deploy, which is exactly the
class of bug the digest exists to catch.

Whether a drop reconnects at all is still the declared `RetryPolicy` of the
error that ended the stream — `transient` and `after` reconnect, `never` does
not. Resumability decides _where_ a reconnect resumes, not _whether_ one happens.

## Transports

Subscriptions run over the streaming HTTP transport.
Both `fetchTransport` and `batchFetchTransport` implement this streaming path;
the latter batches unary calls while opening subscriptions as individual
streams. Use the same client instance for both.

---

# The wire
Source: https://result-rpc.com/concepts/wire

Error definitions describe both representations: the validated encoded value
and the `TaggedError` instance reconstructed from it:

```ts
export const SaveConflict = error({
  tag: "doc/save-conflict",
  data: wire.object({
    docId: wire.string,
    theirSavedAt: wire.date, // a real Date on both sides of the wire
    revision: wire.bigint, // a real BigInt, not a stringified one
  }),
  httpStatus: 409,
});
```

result-rpc uses a pinned, protocol-versioned devalue transport. Success values
and tagged error data transparently preserve:

- `undefined`, `NaN`, infinity, and `-0`
- `Date`, `BigInt`, `RegExp`, `URL`, and `URLSearchParams`
- `Map`, `Set`, `ArrayBuffer`, and typed arrays
- cycles and repeated object identity

The error prototype is not serialized as bytes or guessed from a constructor
name. The procedure contract first authorizes `_tag`, decodes `data`, and then
uses that exact definition to create a fresh instance. Thus
`SaveConflict.is(result.error)` and `result.error instanceof Error` work after
the RPC call without claiming that the server and client shared object identity.

Test the property you care about through a real wire-parity client:

```ts
const result = await parityClient.doc.byId({ id: "doc_123" });
if (result.ok) {
  result.value.savedAt instanceof Date; // true after encode + HTTP + decode
}
```

`createParityClient` comes from `result-rpc/testing`; unlike a direct server
client, it exercises the serializer and protocol boundary.

```ts
const RichDoc = wire.object({
  savedAt: wire.date,
  revision: wire.bigint,
  pattern: wire.regexp,
  homepage: wire.url,
});
```

A nullable field is common enough to have a name: `wire.nullable(codec)` is
exactly the union you would otherwise spell by hand.

```ts
const Author = wire.object({
  name: wire.string,
  avatarUrl: wire.nullable(wire.url), // wire.union([wire.url, wire.null])
});
```

It builds that same union, so the encoding — and therefore the contract digest
— is unchanged. It is shorter, and it says "this field may be absent" rather
than making the reader infer it from a two-member union.

For a recursive or otherwise richer application type, supply an actual type
guard. Serializer support alone cannot prove an application shape:

```ts
const Graph = wire.serializable((value): value is DocGraph => isDocGraph(value), {
  id: "doc-graph/v1",
});
```

The stable `id` is the structural contract identity for a guard the library
cannot introspect. Change it whenever the accepted wire shape changes.

Functions, symbols, unsupported application class instances, and arbitrary
`Error` causes are rejected. `TaggedError` is the deliberate exception because
its definition downgrades it before serialization and reifies it after validation.
Tagged error constructors perform a real serializer preflight,
so a custom wire codec cannot smuggle an unsupported runtime value into an
error.

Encoded request, response, hydration, and tagged-error byte limits are
enforced at runtime. Invalid values are never reflected back to the client.
Custom procedure codecs can enforce finer domain-specific collection, string,
and nesting limits.

## Binaries are out of band

result-rpc deliberately does **not** move file bytes over the RPC wire. Every
request is the one JSON-shaped protocol content-type — there is no multipart
path — which keeps the surface small and, not incidentally, keeps the
[CSRF defense](/concepts/client-boundary/) uniform (a browser cannot send that
content-type cross-origin without a preflight).

Modern stacks already handle binaries better out of band. Upload the bytes
straight to object storage (R2, S3, a Hono endpoint you mount yourself),
usually with a presigned URL, and let the RPC contract carry only the
**reference** — a bucket key:

```ts
// 1. A tiny RPC to mint an upload target (or mount a plain POST route for it).
const createUpload = server
  .procedure()
  .input(wire.object({ contentType: wire.string }))
  .output(wire.object({ uploadUrl: wire.url, key: wire.string }))
  .mutation(async ({ input, context }) => ok(await context.storage.presignPut(input.contentType)));

// 2. The client PUTs the file to uploadUrl directly — bytes never touch RPC.
await fetch(uploadUrl, { method: "PUT", body: file });

// 3. The RPC that finishes the job carries only the reference.
const setAvatar = server
  .procedure()
  .input(wire.object({ userId: wire.string, key: wire.string }))
  .output(UserCard)
  .errors({ ImageUnprocessable })
  .mutation(async ({ input, context }) =>
    ok(await context.users.setAvatarFromKey(input.userId, input.key)),
  );
```

The contract stays fully typed and wire-safe, uploads scale on your storage
provider instead of your app server, resumable and multipart-to-storage uploads
work with no library involvement, and the RPC endpoint keeps its single
content-type. A profile picture, a video, an attachment — all the same shape: a
reference on the contract, the bytes handled by infrastructure built for bytes.

---

# Database errors
Source: https://result-rpc.com/guides/database-errors

`result-rpc/db` provides an ORM-independent Result boundary for database
operations. `tryDb` accepts any thenable—or a thunk for drivers that may throw
while preparing a query—and classifies common SQLite and PostgreSQL failures:

```ts
import { tryDb } from "result-rpc/db";

const inserted = await tryDb(db.insert(reviews).values(row).returning());
if (!inserted.ok) {
  return matchError(inserted.error, {
    "db/unique-violation": () => err(errors.alreadyReviewed({ hotelId })),
    "db/foreign-key-violation": () => err(errors.hotelNotFound({ hotelId })),
    "db/not-null-violation": () => err(errors.invalid({})),
    "db/check-violation": () => err(errors.invalid({})),
    "db/query-failure": () => err(errors.unavailable({})),
  });
}
```

Attempting the insert is the uniqueness check. Unlike a SELECT-first check,
the constraint remains correct when two requests race.

## Private composition currency

Every `db/*` error is private. It belongs inside server implementation code,
not in a procedure's declared wire union:

| Tag                        | Meaning                                |
| -------------------------- | -------------------------------------- |
| `db/unique-violation`      | A unique or primary-key constraint hit |
| `db/foreign-key-violation` | A referenced row does not exist        |
| `db/not-null-violation`    | A required value was absent            |
| `db/check-violation`       | A database check rejected the value    |
| `db/query-failure`         | No more specific classification        |

Collapse that vocabulary into the procedure's domain errors at the handler
boundary. An uncollapsed database error is rejected by the contract and
sanitized to `server/internal` rather than leaking driver details.

## Cause retention

The tagged database error retains the original failure locally as its
standard, non-enumerable `Error.cause`. `tryDb` follows ordinary cause chains
and the common payload slots used by Effect Cause, allowing it to see through
ORM and driver wrappers.

The cause is diagnostic context only. SQL text, parameters, driver internals,
and the cause itself are absent from `toJSON()`, encoded Results, and RPC
responses.

---

# Forms and the wire
Source: https://result-rpc.com/guides/forms

Two validations live near each other here, and they are not the same thing.
A form validates a _human_: values arrive as strings, get coerced, deserve
progressive per-field feedback, and usually cover only a slice of the
eventual input — the id comes from the route, the author from the session.
The wire validates an _application boundary_: values arrive typed, complete,
and possibly hostile. Collapsing the two into one schema is tempting and
almost never right — the form wants "looks like an email while you type",
the wire wants "is a string, or 400".

So result-rpc is not a form library and does not pretend the input codec is
your form schema. Use a real one (we like [Formisch](https://formisch.dev) —
schema-first, headless, signal-fast). The contract contributes exactly the
two edges that are its business:

**Your validator can be the wire codec.** If your team's input vocabulary is
Valibot, Zod, or ArkType (the tRPC `.input(z.object(...))` habit),
`wire.standard` adopts any synchronous [Standard Schema](https://standardschema.dev)
as a procedure's input codec — validation on both sides of the wire, plus
the serializer preflight a plain validator can't give you:

```ts
const rename = app
  .procedure()
  .input(wire.standard(RenameInput, { id: "rename-input/v1" }))
  .output(DocCodec)
  .mutation();
```

(Async schemas are rejected — wire validation is synchronous — and the
schema must accept its own output, so one-way transforms don't fit. And when
a form's shape happens to coincide exactly with an input, sharing the schema
is free — but treat that as a coincidence to notice, not an architecture to
force. The stable `id` participates in the contract digest; change it whenever
the schema's accepted wire shape or semantics change.)

**And the form runs the same schema first**, with `validateStandard` — the
form-side companion to `wire.standard`. Per-field feedback before a request
exists, no `~standard` spec plumbing:

```ts
import { validateStandard } from "result-rpc";

const validated = validateStandard(RenameInput, { id, title });
if (!validated.ok) return setFieldErrors(validated.fields); // dot-joined keys
await rename.mutateAsync(validated.value);
```

**Server rejections land on fields.** Whatever validates the form, the
codec still validates the wire — and when a request fails there,
`server/bad-request` carries path-scoped issues that project onto field
keys:

```tsx
const result = await rename.mutateAsync(toInput(form.values));
if (!result.ok && result.error._tag === "server/bad-request") {
  setFieldErrors(fieldIssues(result.error));
  // { "title": ["Expected a string"], "author.email": ["Expected an email"] }
}
```

The paths are shaped like the _input_. When the form edits a projection of
the input — it usually does — map the keys where the shapes diverge, in the
same place you already map values (`toInput` above). The mapping is the
honest artifact: it is where "what the human edits" and "what the wire
carries" meet, and no bridge should hide it.

**When does `server/bad-request` actually happen?** Not from your own
same-version client submitting a bad value — the client encodes input through
the same codec before sending, and input the codec rejects throws a
`TypeError` at the call site (a programmer error; it never reaches the wire).
The wire rejection arc exists for callers whose codec disagrees with the
server's: skewed clients mid-deploy, hand-rolled HTTP callers, other
services. So the division of labor is: **your form validates the human**
(`validateStandard` — see above) before `mutate`
is ever called; `fieldIssues` is the safety net for the wire's own
validation, not your form's primary path.

**Mind the DefectShell.** `boundaryShells()`'s defect ring claims
`server/bad-request` — under the recommended onion it escalates to the error
boundary and leaves the unions components see. A form that branches on it
must mount outside the defect shell's subtree (or catch the `claimed`
rejection with `isClaimed`). If your form validates the human first, this
rarely matters — but it is a positional fact worth knowing before you wonder
where the tag went.

---

# Migrating from tRPC
Source: https://result-rpc.com/guides/migrating-from-trpc

Migration is per-router, not big-bang. result-rpc is a separate endpoint with
a separate client — it shares nothing with tRPC at runtime, so both stacks run
side by side for as long as the migration takes:

```ts
// server: two handlers, two routes
app.all("/api/trpc/*", trpcHandler); // existing routers stay
app.post("/rpc", resultRpcHandler); // migrated routers move here

// client: two clients during the transition
export const trpc = createTRPCReact<LegacyRouter>();
export const client = createBrowserClient({
  contract,
  transport: batchFetchTransport({ url: "/rpc" }),
});
```

One difference to internalize before your first slice: tRPC ships its router to
the client **as a type** (`createTRPCReact<LegacyRouter>`), erased at build.
result-rpc ships a **real client value** built from your `contract` — so _what
you import decides what bundles_. Pass the contract, never the server router, or
handlers and secrets ship to the browser. This is the one migration mistake that
is a security bug; read [The client boundary](/concepts/client-boundary/) first.

The recommended first slice is **the auth layer plus one feature router** —
small enough to finish in days, and it exercises the part tRPC cannot express
(a shell owning session expiry) so the migration proves its value immediately
instead of at the end.

The concept mapping is mechanical:

| tRPC                                         | result-rpc                                                                  |
| -------------------------------------------- | --------------------------------------------------------------------------- |
| `initTRPC.context<Ctx>().create()`           | `serverRpc.context<Ctx>()`                                                  |
| `t.procedure.input(z...).query(fn)`          | `server.procedure().input(wire...).output(wire...).errors({...}).query(fn)` |
| `throw new TRPCError({ code })`              | `return err(errors.SomeError({...}))`                                       |
| `t.middleware` + `ctx` spread                | `server.middleware<Added>().errors({...}).use(...)`                         |
| `protectedProcedure`                         | `server.procedure().use(authenticated)` — same pattern                      |
| `httpBatchLink`                              | `batchFetchTransport`                                                       |
| `@trpc/react-query` hooks                    | `useResultQuery` / shell hooks                                              |
| `errorFormatter`                             | gone — error data is a wire codec, not a formatted shape                    |
| adapter `onError`                            | `onError` + `onInternalError` on `createFetchHandler`                       |
| `createCaller`                               | `createServerClient`                                                        |
| `ctx.resHeaders` / `responseMeta`            | `.headers()` on the procedure, then `context.headers`                       |
| `queryClient.setDefaultOptions({ onError })` | a shell                                                                     |

One row deserves a note, because it is a scar many tRPC codebases carry.
`ctx.resHeaders` works under `httpBatchLink` and silently stops working under
`httpBatchStreamLink` — a streamed response sends its headers before the
procedures resolve, so a cookie set inside a mutation is dropped with no error.
The usual workaround is to move it into `responseMeta`, which runs before the
result exists. Here the capability is declared with `.headers()`, batches do not
stream, and an undeclared procedure has no `context.headers` to write to — so
the failure mode is a type error rather than a missing cookie. See [Setting
response headers](/concepts/context/#setting-response-headers-and-logging-someone-in).

Two things have no tRPC equivalent and are the actual work: every procedure
declares its error union (this is where the two-failure-channel debt gets paid
down, one procedure at a time), and interceptor logic moves into shells. There
is no codemod; each procedure is a five-minute mechanical rewrite.

During coexistence the two stacks keep **separate caches** — a result-rpc
mutation does not invalidate tRPC queries or vice versa. Migrate whole
features, not halves of one screen, and the seam stays invisible.

---

# Observability
Source: https://result-rpc.com/guides/observability

The footgun: a Sentry event that says `TRPCClientError: UNAUTHORIZED` with a
stack that points into library code, and a dashboard you reconstruct from
string codes after the fact. When observability is table stakes, "which
operation, which tag, who owned it, what did the server actually see" cannot
be archaeology.

Every observable moment is already a value at a known choke point, so
observability is one structured stream plus adapters — never an integration
that fights the framework. Four taps, one per tier:

```ts
// 1. Wire: every call, retry, claim — paths, tags, timing; never values.
const client = createBrowserClient({
  contract,
  transport,
  onEvent: (event) =>
    Sentry.addBreadcrumb({
      category: `rpc.${event.type}`,
      message: "path" in event ? event.path : event.type,
      level: event.type === "failure" ? "warning" : "info",
      data: event,
    }),
});
// event: call | success | failure | retry | skew
//      | claimed  ← a pausing shell held it: { path, tag, owner, effect: "pause" }

// 2. Ownership: a shell's reaction is a reporting moment.
const AuthShell = layerShell(AuthLayer, {
  from: DefectShell,
  select: (client: AppClient) => client.auth.me,
  onError: (error) => {
    Sentry.captureMessage(`signed out: ${error._tag}`, "info");
    redirect("/login");
  },
});

// 3. Server, declared errors: policy included, so severity routes the sink.
createFetchHandler({
  router,
  onError: ({ error, policy, procedurePath, httpStatus }) => {
    metrics.increment(error._tag, { status: httpStatus });
    if (policy?.severity === "error") Sentry.captureMessage(error._tag);
  },
  // 4. Server, defects: the only place causes and stacks exist.
  onInternalError: ({ incidentId, cause, procedurePath, phase }) => {
    Sentry.captureException(cause, { tags: { incidentId, procedurePath, phase } });
  },
});
```

The wire stream is redaction-safe by construction: events carry paths, tags,
durations, owners — never inputs or outputs — so forwarding it verbatim to a
third-party tracker is not a data decision.

`onEvent` is a synchronous observation tap, so keep adapters small and move
expensive delivery off the call path. React subscriptions do not open during
render: the stream starts when the observer subscribes after commit, including
under StrictMode.

For inline observation of a single Result, the tap combinators return the
original value unchanged:

```ts
tapError(await client.doc.rename(input), (error) => log.warn(error._tag));
// also: tap(result, fn), tapBoth(result, { ok, error })
```

---

# Bring your own router
Source: https://result-rpc.com/guides/routing

result-rpc deliberately ships no router integration: shells are providers and
hooks, so they compose with any router (TanStack Router, Next, Waku, React
Native navigation) without the library knowing routers exist. The natural
mapping — layout route = shell, route loader = `runtime.prefetch`,
`errorComponent` = escalate target — is roughly sixty lines of app-owned glue;
`examples/05-router-glue/router-glue.tsx` is a complete copy-paste integration
for TanStack Router, including auto-derived loaders that prefetch a layer's
context procedure before its route commits.

---

# React Server Components
Source: https://result-rpc.com/guides/rsc

result-rpc renders on the server the way it renders anywhere: prefetch queries
into a runtime, dehydrate that runtime to a plain serializable value, and let a
client boundary merge it. The payoff is the full one — not just a filled cache,
but **entities that are indexed on hydrate**, so a client mutation patches a
server-rendered row in place with no refetch.

## The shape

Three steps, each a value crossing one boundary:

1. **Server**: a per-request runtime over an in-process server client prefetches
   queries.
2. **Boundary**: `runtime.dehydrate()` returns `{ v, serializer, contract, payload }` — a
   plain object with a string payload, so it crosses the RSC server→client
   boundary as an ordinary prop.
3. **Client**: `<ResultRpcHydrationBoundary state={...}>` merges it into the one
   client runtime, during render, before the first paint reads the cache.

```tsx
// app/rsc.ts — one runtime per request, shared by every server component
import { cache } from "react";
import { createServerClient } from "result-rpc/server";
import { createQueryRuntime } from "result-rpc/query"; // ← react-free entry
import { appRouter } from "@app/server"; // server-only module

export const getServerRpc = cache(() => {
  const client = createServerClient(appRouter, { context: buildContext() });
  return { client, runtime: createQueryRuntime({ client }) };
});
```

> **Two entries: `result-rpc/query` on the server, `result-rpc/react` in
> components.** `result-rpc/react` is marked `"use client"`. Rendering its
> **components** from a server component is fine and expected —
> `<ResultRpcHydrationBoundary>` below is imported straight into a server
> component, and the bundler turns it into a client reference rather than
> executing it on the server. That is the boundary working as designed.
>
> The cache runtime has no React dependency, so it ships as its own entry.
> `createQueryRuntime` is intentionally **not exported** from
> `result-rpc/react`: importing it from a `"use client"` entry can compile yet
> fail when a React server evaluates the call. Import it and its types from
> **`result-rpc/query`** in server code, where the mistake is caught at the
> module boundary instead of on a production request.

`cache()` (React's per-request memo) means every server component in one request
shares a runtime — prefetches accumulate, and you dehydrate once at the boundary.

```tsx
// app/users/[id]/page.tsx — a server component
import { getServerRpc } from "@app/rsc";
import { ResultRpcHydrationBoundary } from "result-rpc/react";
import { UserDetail } from "./user-detail"; // a client component

export default async function Page({ params }: { params: { id: string } }) {
  const { client, runtime } = getServerRpc();
  await runtime.prefetch(client.users.get, { id: params.id });
  return (
    <ResultRpcHydrationBoundary state={runtime.dehydrate()}>
      <UserDetail id={params.id} />
    </ResultRpcHydrationBoundary>
  );
}
```

```tsx
// user-detail.tsx — a client component
"use client";
import { useResultQuery } from "result-rpc/react";
import { client } from "@app/client";

export function UserDetail({ id }: { id: string }) {
  // Already `success` on first paint — the server prefetched it.
  const user = useResultQuery(client.users.get, { id }, { staleTime: 60_000 });
  if (user.state !== "success") return <UserSkeleton />;
  return <h1>{user.value.name}</h1>;
}
```

The `ResultRpcProvider` still wraps your app once (usually in the root layout's
client boundary), owning the client runtime. The hydration boundary feeds it.

## Set a `staleTime` on prefetched queries

Server-prefetched data arrives with the timestamp it was fetched. With the
default `staleTime` of `0` it is immediately stale, so the client revalidates in
the background on mount — correct, but a wasted round-trip when you just rendered
it. Give prefetched queries a `staleTime` so the server data is trusted for a
window and the first mount makes **zero** client requests — no loading flash
and no immediate refetch.

This is browser query freshness, not an HTTP or CDN cache directive. See
[Freshness, fetch state, and backend caching](/concepts/react/#freshness-fetch-state-and-backend-caching)
for the canonical distinction.

## Nested boundaries merge

Unlike the provider's one-shot `hydrate` prop, boundaries are **nestable** — the
App Router idiom. Each route segment's server component prefetches only what it
owns and renders its own boundary; every payload merges into the one client
runtime:

```tsx
<ResultRpcHydrationBoundary state={layoutRuntime.dehydrate()}>
  <Nav />
  <ResultRpcHydrationBoundary state={pageRuntime.dehydrate()}>
    <Content />
  </ResultRpcHydrationBoundary>
</ResultRpcHydrationBoundary>
```

## The entity payoff

Hydrated queries are indexed in the [entity cache](/concepts/entities/) exactly
as fetched ones are — the dehydrated data is re-decoded through each output
codec on hydrate, which re-brands its entities. So a server-rendered user row
and a client mutation that returns that same `user` entity are connected: the
mutation patches the row in place, at one request, with no refetch — even though
no client component ever fetched it. Server rendering does not cost you the
live-update behavior; it seeds it.

## Deploy skew is survived, not crashed

If the server and client bundles briefly disagree on the serializer or contract
version across a deploy, the boundary **skips** hydration (with a dev warning)
and the client fetches fresh, rather than throwing during render and taking down
the tree. A stale server payload never renders as if it were current.

## Calling procedures on the server

`createServerClient` runs procedures in-process. Use it for server rendering,
server actions, and background jobs. It keeps everything that decides whether a
call is _correct_ — the middleware chain and its context, input validation,
output encode/decode (which also brands entities), and the sanitization of
private errors into `server/internal` — and drops only the transport: no
serializer round trip, no HTTP envelope, no contract digest, no retry, no
batching.

Wire-faithful tests use `createParityClient` from `result-rpc/testing` instead.
That client crosses the serializer, protocol envelope, fetch handler, and
browser decoder so tests prove a value survives the trip.

The constructors also expose different error types:

```ts
// createParityClient / createBrowserClient
DocNotFound |
  Unauthorized |
  ServerInternal |
  ServerBadRequest |
  Offline |
  NetworkFailure |
  Timeout |
  HttpFailure |
  ProtocolViolation |
  DecodeFailure |
  Stale;

// createServerClient — what is actually reachable in-process
DocNotFound | Unauthorized | ServerInternal | ServerBadRequest;
```

The client-boundary tags are gone because they are unreachable, not because
they were hidden: there is no socket to drop, no `navigator` to report offline,
and no second build to drift from. That narrowing is what makes an exhaustive
`matchError` in a server component three arms instead of a dozen.

## Shells do not exist on the server

`result-rpc/react` is a client entry, and claiming is React context. A server
component can render `<ResultRpcHydrationBoundary>` as a client reference, but
it cannot _use_ a shell — and what shells do (pause and resume on reconnect,
redirect to login, hold and drain) only means something in a live browser.

So a server component sees the complete union and handles it itself. You have
three honest options:

1. **Ignore the failure.** Legitimate, and usually right. A declared domain
   failure hydrates (see below), so the browser paints it without asking. A
   transport failure does not, so the client mounts that query cold, fetches
   once, and the shells own the failure _there_ — live, and retryable.
2. **Handle the outcomes that belong to the response.** Some failures deserve a
   server answer: `notFound()` on `doc/not-found`, `redirect("/login")` on
   session expiry, a 500 page on `server/internal`. These are framework
   primitives, and they beat a client shell — right status code, no flash, no
   wasted round trip.
3. **Do not try to reproduce shells.** Pause/resume, offline banners, and
   session-expiry-with-return-to need a client.

The rule of thumb: **server components own the failures that change the HTTP
response; shells own the failures that change the UI.**

> **Mutations from server actions lose the cache.** A mutation called through a
> direct caller executes normally and returns its `Result`, but its cache
> declarations are inert — `.affects()`, entity patching, and `touch` are
> client-runtime behaviors, and there is no client cache on a server. The write
> lands; the browser's cache learns nothing about it. Refresh the route, or
> perform the mutation from the client where the machinery lives.

## Declared failures hydrate; transport failures do not

The split follows from the library's first pillar: **a declared domain error is
a value**, and `dehydrate()` carries values.

`doc/not-found` is not a failed prefetch. It is the answer — the same answer the
client would get, arrived at on the server, and it hydrates like any success. A
detail page for a row that does not exist renders "not found" on **first paint,
at zero client requests**. It comes back reified through the procedure's error
registry, so it narrows, matches, and is [claimed by a
shell](/concepts/shells/) exactly as a live failure would be.

`client/network-failure` is the opposite in kind. It describes one attempt on
one machine — the server's — and baking it into the payload would replace a
fetch the browser can retry with a verdict it cannot. So framework and transport
failures are still left out, and that query mounts cold and fetches once.

The rule is the tag: every error _you_ declared on the procedure hydrates; the
built-in `client/*` and `server/*` failures do not.

Two details worth knowing if you inspect a payload. A retry detail about one
attempt (`fetchFailureReason`) is dropped rather than translated — it is
bookkeeping about a machine that is now gone. And the error crosses as its wire
form, the same shape the transport would have sent, because the serializer
rejects class instances by design; it is reconstructed on the way back in.

## Pass values through component props, not Results

The hydration boundary above is a result-rpc boundary: it owns a versioned codec
and knows how to reconstruct supported runtime values. An ordinary RSC prop or
Next server-action/RPC payload does not. Do not pass a `Result` or `TaggedError`
through one and expect its iterator, definition identity, or `Error` prototype to
survive.

Unwrap at the server/client component boundary:

```tsx
const result = await serverClient.users.get({ id });

if (!result.ok) return <MissingUser id={id} />;
return <UserDetail initialUser={result.value} />;
```

When the browser needs the full Result API, let the result-rpc client make the
call or use `runtime.dehydrate()` for successful query data. The library promises
faithful runtime behavior across its own wire, not arbitrary serialization.

## Per-framework mounting

The pattern is identical everywhere; only the mount point and the prefetch site
move. Three worked examples ship in the repo:

| Example             | Framework                | Prefetch happens in    | RPC handler mounts at                |
| ------------------- | ------------------------ | ---------------------- | ------------------------------------ |
| `09-waku`           | Waku (RSC)               | async server component | `src/pages/_api/rpc.ts` → `/rpc`     |
| `10-nextjs`         | Next.js App Router (RSC) | async server component | `app/api/rpc/route.ts` → `/api/rpc`  |
| `11-tanstack-start` | TanStack Start (SSR)     | route **loader**       | `src/routes/api.rpc.ts` → `/api/rpc` |

Three traps worth knowing before you wire your own:

- **Match the endpoint on both ends.** The library defaults to `/rpc`, but
  Next.js and TanStack Start mount route handlers under `/api/`. Set both
  `endpoint` on `createFetchHandler` _and_ `url` on `fetchTransport`, or every
  call 404s silently.
- **TanStack Start reserves `src/server.ts` and `src/client.ts`.** It resolves
  those paths as its own optional entries, so the file names used by every other
  result-rpc example silently hijack them (the symptom is an opaque
  `Cannot read properties of undefined (reading 'fetch')`). Name them
  `rpc-server.ts` / `rpc-client.ts` there.
- **In TanStack Start, loaders are isomorphic — that is a client-boundary
  hazard.** A loader that imports your database module directly typechecks and
  works in dev SSR, then ships your database to the browser on the first client
  navigation. There is no `'use client'` directive to protect you here: put the
  server wall at a `createServerFn`, and re-read
  [The client boundary](/concepts/client-boundary/).

All three exercise the same app end to end — prefetched paginated feeds,
skeleton fallbacks, mutations patching server-rendered rows, and a
`tryDb` constraint surfacing as a domain error — so you can diff them to see
exactly what the framework changes and what it doesn't.

---

# Testing and SSR
Source: https://result-rpc.com/guides/testing

```ts
import { createParityClient } from "result-rpc/testing";
import { appRouter } from "./router";

const client = createParityClient(appRouter, {
  context: testContext,
});

const result = await client.doc.byId({ id: "missing" });

expect(result).toEqual({
  ok: false,
  error: {
    _tag: "doc/not-found",
    data: { docId: "missing" },
  },
});
```

Parity mode runs the same codecs and undeclared-error checks as the remote
protocol. A separate test transport covers malformed envelopes, 5xx responses,
timeouts, offline behavior, and batch failures.

And when a test should cross the real wire — protocol, serializer, HTTP
statuses and all — the fetch handler _is_ the fetch, no server process
required. The examples run their full React trees this way:

```ts
const handler = createFetchHandler({ router, createContext: () => context });

const client = createBrowserClient({
  contract: appContract,
  transport: fetchTransport({
    url: "https://example.test/rpc",
    fetch: (input, init) => handler(new Request(input, init)),
  }),
});

// full round-trip: devalue envelope, HTTP status, rich values intact
const events = await collect(client.doc.events({ id: "doc_1" }));
expect(events[0]).toEqual(ok({ docId: "doc_1", kind: "renamed", at: new Date("2026-01-01") }));
```

Note the `Date` inside the assertion — it crossed the wire as a `Date`.

## Simulating offline

The connectivity source listens on **`globalThis`** (in a browser that _is_
`window`; in Bun and Node it is not — do not stub `window`). Its online
snapshot is seeded from `navigator.onLine` at module import and is
**event-driven afterwards** — flipping `navigator.onLine` does nothing; you
dispatch events. Listeners attach lazily when the first subscriber appears
(creating a runtime or mounting `BoundaryProvider`), so mount first, dispatch
second:

```tsx
const runtime = createQueryRuntime({ client }); // attaches listeners
// ... render under BoundaryProvider ...

await act(async () => {
  globalThis.dispatchEvent(new Event("offline")); // reads pause, banner flips
});
await act(async () => {
  globalThis.dispatchEvent(new Event("online")); // held work resumes
});
```

Always dispatch a final `online` in test teardown — the source is a module
singleton, and a test that leaves it offline starves the next one.

---

# Agent skill
Source: https://result-rpc.com/reference/agent-skill

result-rpc ships an [agent skill](https://code.claude.com/docs/en/skills) so a
coding agent (Codex, Claude Code, and compatible tools) knows the library's rules —
especially the [client-boundary](/concepts/client-boundary/) safety rule — and
knows where to read the rest.

The skill is deliberately thin. It carries stable orientation plus the one
non-negotiable rule inline, then a task→page map into this documentation. The
docs are the single source of truth; the skill routes the agent to them. That
means there is no second copy of the details to keep in sync — update a doc
page, and the skill still points at it.

## These docs are agent-readable

Every page here is also served as raw Markdown — append `.md` to any URL:

- Canonical skill: `https://result-rpc.com/skill.md`
- Page Markdown: `https://result-rpc.com/concepts/pagination.md`
- Index for LLMs: `https://result-rpc.com/llms.txt`
- Full corpus: `https://result-rpc.com/llms-full.txt`
- Agent surface manifest: `https://result-rpc.com/agent-readability.json`
- Hosted docs MCP: `https://result-rpc.com/.well-known/mcp.json`

So an agent with web access can read the whole documentation set directly,
whether or not the skill is installed. The skill just gives it the map and the
guardrails up front.

## Installing for Codex and compatible agents

The skill ships inside the npm package at
`node_modules/result-rpc/skills/result-rpc/SKILL.md`. Make it available to your
agent by linking it into the convention it reads. Codex and other Agents Skills
compatible tools use `.agents/skills`:

```bash
mkdir -p .agents/skills
ln -s ../../node_modules/result-rpc/skills/result-rpc .agents/skills/result-rpc
```

Claude Code uses `.claude/skills`:

```bash
mkdir -p .claude/skills
ln -s ../../node_modules/result-rpc/skills/result-rpc .claude/skills/result-rpc
```

A symlink keeps the skill current: when you upgrade `result-rpc`, the skill
upgrades with it. If your operating system or tool does not follow project
symlinks, use the matching explicit copy form:

```bash
mkdir -p .agents/skills
cp -R node_modules/result-rpc/skills/result-rpc .agents/skills/result-rpc

# Or, for Claude Code:
mkdir -p .claude/skills
cp -R node_modules/result-rpc/skills/result-rpc .claude/skills/result-rpc
```

The copy is a snapshot. Remove and recreate it after upgrading the package.
Verify either installation without depending on agent-specific UI:

```bash
test -f .agents/skills/result-rpc/SKILL.md || \
  test -f .claude/skills/result-rpc/SKILL.md
```

Once linked, an agent working in your repo discovers the skill by its
description and pulls in the client-boundary rule and the page map before it
writes contract, client, or handler code.

## What the skill enforces

The skill front-loads the rules that are easy to get wrong and expensive to get
wrong:

- **Build the browser client from a `contract()`, never the router** — the
  [client boundary](/concepts/client-boundary/) rule, because a value import of
  server code ships handlers and secrets to the browser.
- Errors are declared, closed, and returned — not thrown.
- The contract is the error registry; shells index by tag and claim exact definitions.
- Mutations declare their blast radius in the contract.

Everything else it defers to the page map, fetched as Markdown on demand.

---

# Examples
Source: https://result-rpc.com/reference/examples

The `examples/` directory is an escalation ladder. Every rung is a
self-contained app with runtime tests, every file typechecks under the
repo's strict `pnpm check`, and the main claims are asserted with
**per-procedure request counters** — the examples are the library's DX
regression suite, not demos.

For a persistent browser application, open the [live ticket
demo](https://demo.result-rpc.com) or read its [implementation
notes](/reference/ticket-demo/). It runs on Cloudflare Workers and D1 and makes
optimistic updates, entity patches, cursor pagination, and declared
invalidation visible in a client-event panel.

```bash
bun test examples/01-hello             # any single rung
bun test examples                      # the whole ladder
bun run examples/07-tracker/serve.ts   # 07 also runs in a real browser
```

## Which rung do you want?

| Rung                                     | Start here if you want…                | Headline proof                                                      |
| ---------------------------------------- | -------------------------------------- | ------------------------------------------------------------------- |
| [01-hello](#01-hello)                    | the smallest browser-safe app          | one returned error, one unified failure channel                     |
| [02-todo](#02-todo)                      | mutations + optimistic basics          | rollback on failure, catalog over a narrowed union                  |
| [03-docs](#03-docs)                      | the whole system, minimally            | avatar patch: 1 request, 0 refetches                                |
| [04-router](#04-router)                  | TanStack Router integration            | routes are shells; loaders prefetch layers                          |
| [05-router-glue](#05-router-glue)        | proof you need no router package       | the same app on ~60 lines of app-owned glue                         |
| [06-sentry](#06-sentry)                  | the observability story                | incident-id correlation with zero plumbing                          |
| [07-tracker](#07-tracker)                | a real app, end to end                 | built _blind_ from the docs; its friction log drove library fixes   |
| [08-bookings](#08-bookings)              | entities on a real database            | Drizzle 1.0; one rename patches 4 surfaces across 2 paginated feeds |
| [09-waku](#framework-examples)           | server rendering on Waku (RSC)         | first paint from the server at **zero** client requests             |
| [10-nextjs](#framework-examples)         | server rendering on Next.js App Router | same app, same proof, `app/api/rpc/route.ts`                        |
| [11-tanstack-start](#framework-examples) | server rendering without RSC           | prefetch in a **loader**; the isomorphic-loader hazard, named       |

## 01-hello

One procedure, one domain error, no shells — the
[quickstart](/start/quickstart/), split into contract, server, client, and UI
modules. The handler _returns_ its failure (`err(...)`) against a declared
union, the browser imports the contract rather than the router, and the
component switches over one channel that includes the transport. Read this
first if you're arriving from tRPC.

## 02-todo

Mutations with optimistic updates and rollback, the basic
`boundaryShells()` onion, the three-state connection banner, and an
`errorCatalog` over a shell-narrowed union. The list's failure branch is
`todos.error satisfies never` — the compiler certifying the shells are
mounted.

## 03-docs

The whole system in one small app: a `defineService` dependency graph,
optional→required session/viewer layers, a four-shell onion, entity
models, a rendered subscription, and a defect escalation boundary. The
key test: change the avatar, and the header — a _different query_ —
shows the new image at exactly one request (the mutation itself), zero
refetches. Compile-time probes pin the narrowed unions: a query resolving
a dozen possible failures presents exactly `doc/not-found`.

## 04-router

TanStack Router integration by hand — **routes are shells**. Pathless
layout routes mount the session and viewer layers, a route claims its
feature error, `errorComponent` receives escalated defects, a pausing shell's
`onError` navigates, and layout loaders prefetch each layer's context procedure so
the first committed paint renders session, viewer, and content with no
fallback states.

## 05-router-glue

Rung 04 rebuilt on app-owned glue (`router-glue.tsx`, ~60 lines):
`routeShell` fragments spread into `createRoute`, so one declaration per
layer produces both the provider component and the prefetch loader — proof
the router integration needs no package, which is why routing stays a
deliberate non-goal.

## 06-sentry

The observability pillar end to end: a Sentry-shaped stub receives wire
breadcrumbs, the paused `claimed` trail with its owning shell, severity-routed
server captures, and a defect whose captured server exception carries the
same incident id the client received — correlation across the wire with no
request-id plumbing.

## 07-tracker

A team issue tracker exercising the whole surface as one app — and the
rung with a story: it was built **blind** by an engineer persona working
from the docs alone, adversarially reviewed, then fixed. Its `FRICTION.md`
is the honest log, and it drove three same-day library fixes (inline hook
options, codec-rejected input handling, proxy introspection).

What it exercises: session layer, entity patching with a `touch` cascade,
declared invalidation, optimistic create with client-minted ids (the form
validates the human with `validateStandard` before the wire is involved),
the offline arc — mounted offline → **zero** wire calls → exactly one on
reconnect — `gen`/`tryPromise` composition collapsed at the procedure
boundary, a subscription feed, and the stale-deploy form flow: a
deliberately old-shaped client whose bad request crosses the wire and
comes back as field-projected `server/bad-request` at exactly one call.
`serve.ts` serves it for a real browser.

## 08-bookings

The ground-truth proof on a **real database** — Drizzle ORM 1.0 over
bun:sqlite, real SQL, relations v2, shaped after a census of a
280-procedure production tRPC API. Built to answer "is what entities buy
worth what they cost" with numbers:

- **Cost**: four explicit wire models checked against Drizzle row types with
  [`$satisfies<Source>()`](/concepts/model-sources/) — schema drift is a type error,
  while no database metadata enters the browser graph.
- **Buy**: `users.rename` patches **four surfaces** — review rows on
  cached pages of two different paginated feeds, a top-reviewer card, and
  the booked-by line inside a four-level relational tree — at exactly one
  request.
- The locale trap closed by a composite `["id","locale"]` key; `min()`
  aggregates that stay query-relative while the entity inside them
  patches; derived summaries refreshed by `.affects`; and `tryDb` turning
  a UNIQUE constraint into a domain error — the insert _is_ the
  uniqueness check, no pre-check SELECT anywhere.

Its `NOTES.md` is the model-vs-pick-vs-one-off decision table applied to
every output shape, plus the cost ledger against disciplined tRPC + React
Query and the Drizzle 1.0 migration notes (relations v2, `jsonb_*` under
Bun).

## Framework examples

Rungs 09–11 are the **same app on three frameworks** — a feed of travel spots
on Drizzle 1.0 + SQLite, with cursor pagination, an entity-returning mutation, a
one-off aggregate kept fresh by `.affects()`, a `tryDb` constraint surfacing as
a domain error, and shimmer skeletons. Their contract, models, schema, and
components are byte-identical across all three, so a diff shows you exactly what
each framework changes and what it doesn't. See the [RSC
guide](/guides/rsc/) for the shared pattern.

Each is browser-verified with the same four proofs: rows render server-prefetched
at **zero** client requests on first paint, "Load more" costs exactly one call, a
like patches its row **in place** while the aggregate follows, and a planted
server-only canary is **absent** from the built client bundle.

|             | `09-waku`               | `10-nextjs`             | `11-tanstack-start`     |
| ----------- | ----------------------- | ----------------------- | ----------------------- |
| Model       | RSC                     | RSC                     | SSR + router loaders    |
| Prefetch in | async server component  | async server component  | route `loader`          |
| Handler     | `src/pages/_api/rpc.ts` | `app/api/rpc/route.ts`  | `src/routes/api.rpc.ts` |
| Server wall | `'use client'` boundary | `'use client'` boundary | `createServerFn`        |

The TanStack Start rung is the instructive one: without RSC there is no
`'use client'` directive to protect you, and its **isomorphic loaders** will ship
your database to the browser on the first client navigation if you import it
directly. That hazard is documented in [The client
boundary](/concepts/client-boundary/#isomorphic-loaders-are-a-second-leak-vector).

## The method behind the ladder

Rungs 01–06 grew with the library. 07 and 08 were built by agents — one
blind (docs-only, logging every friction), one spec-driven against the
production-API census — precisely so the examples test the documentation
as hard as they test the code. When a rung fought the library, the library
changed; the friction logs stay in the repo as the record.

Rungs 09–11 continued that: building 09 surfaced two real library defects (a
procedure kind widened away from its contract, and a React entry that could not
load under the react-server condition), both fixed and regression-pinned before
10 and 11 were built. Those two then ran against the shipped API with **no
workarounds** — which is the point of building the same thing three times.

---

# Sharp edges
Source: https://result-rpc.com/reference/sharp-edges

Named here so they are not discovered at 2am:

- **Reference identity under hot reload.** Services, middleware dedup, and the
  error-tag registry all key on module-constant reference identity. HMR that
  re-evaluates a definition module creates new identities; the router build
  will reject a tag re-registered with a different definition rather than
  silently duplicating it, but the reliable dev-mode rule is: keep
  definitions in leaf modules and let edits to them trigger a full reload.
  Two copies of result-rpc in one bundle (monorepo resolution mistakes) break
  identity the same way they break React context — dedupe the package.
- **No React Query devtools.** The cache engine is `@tanstack/query-core`
  used privately, so the React Query devtools, persisters, and ESLint plugin
  do not apply. The current inspection surface is the client `onEvent` stream
  (every call, failure, retry, and claim, with its owning shell); a dedicated
  devtools panel — including "which shell claimed this error and why" — is
  planned but not shipped.
- **Control-flow rejections.** `await mutateAsync(...)` can reject with
  `cancelled` or `claimed`. Call sites that await mutations need the same
  `try/catch` discipline they need for aborts. Fire-and-forget call sites want
  `mutate(...)`, which returns `void` and never rejects.
- **The contract is a value.** Unlike tRPC's type-only client, the browser
  bundle carries the contract's codecs and the devalue serializer. That is
  the price of rich values and client-side validation; it is a real number of
  kilobytes, and worth measuring in your bundle before committing.
- **An inline `wire.object` collects no identity.** Entity updates only see
  outputs composed from model views (`Doc.pick(...)`, `Doc.select({...})`) — a
  hand-rolled shape opts out silently. Model identity is reference identity,
  same rule as services and middleware: one `defineModel` in a module
  constant; two calls are two models.
- **External codecs own their schema identity.** `wire.standard` and
  `wire.serializable` require a stable `id` because validator/guard internals
  are not portably introspectable. Change it whenever accepted wire semantics
  change. Built-in codecs are fingerprinted structurally.
- **Two caches during a tRPC coexistence period** — see the migration section.

---

# Ticket demo
Source: https://result-rpc.com/reference/ticket-demo

The [live ticket demo](https://demo.result-rpc.com) is a small product rather
than an isolated API example. It runs on a Cloudflare Worker with D1 and exposes
the client cache's decisions alongside the interface.

[Open the live demo →](https://demo.result-rpc.com)

The source lives in [`demo/`](https://github.com/jokull/result-rpc/tree/main/demo)
in the result-rpc repository.

## What to try

| Action                                      | What it demonstrates                                                                                                                                                                                                                                                |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Change a ticket's status or edit its title  | The list row and open detail pane update optimistically before the deliberately delayed mutation settles. The returned entity then reconciles every cached projection by identity.                                                                                  |
| Load another page                           | Cursor pagination appends into one stable query without replacing the rows already on screen.                                                                                                                                                                       |
| Move a ticket across a filtered list        | The optimistic entity patch updates known data immediately; the mutation's declared `.affects()` edge then refreshes list membership and aggregate counts.                                                                                                          |
| Watch the proof panel                       | Client events distinguish wire calls, entity patches, optimistic writes, and invalidation-driven refetches. The behavior is inspectable instead of implied by the UI.                                                                                               |
| Take the browser offline                    | The application shell owns `client/offline`, presents one connection-level reaction, and resumes held work when connectivity returns. Components below it do not grow offline branches.                                                                             |
| Open **error stack** and arm the guided run | A real edit returns `auth/login-required`, then `access/write-required`, then `ticket/conflict`. Higher-order shells open the login and access dialogs; the editor sees only its residual domain union. Mutations are retried by the user, never replayed silently. |

Each browser receives an anonymous workspace token in local storage. Tickets are
stored in D1, so refreshing the page or returning later preserves that
workspace. Resetting the demo creates the same seeded dataset again.

## What the source proves

The demo keeps its runtime contract in `shared/`, its D1 implementation in
`server/` and `db/`, and the browser client in `client/`. The browser imports the
contract, not the router. A production-build test scans the emitted client
assets and fails if either the SQL schema or a planted server-only canary enters
the browser graph.

The Worker integration test runs the built artifact under Cloudflare's
production test harness and exercises SSR, pagination, detail reads, and a
mutation through the real result-rpc wire. It also proves that authentication,
write access, and optimistic-concurrency conflict arrive as three distinct
reified tagged failures.

## The error stack in code

The edit contract declares all application failures that can reach the wire:

```ts
errors({
  ...authErrors, // auth/login-required
  ...accessErrors, // access/write-required
  ...ticketErrors, // ticket/not-found | ticket/conflict
});
```

The providers own the app-level affordances. Their chain is a value, so the
hook's residual union is derived rather than asserted:

```tsx
<AuthShell.Provider>
  <WriteAccessShell.Provider>
    <TicketEditor />
  </WriteAccessShell.Provider>
</AuthShell.Provider>;

const edit = WriteAccessShell.useMutation(client.tickets.edit);
// edit failure: TicketNotFound | TicketConflict
```

The server still returns real `Result` values for every branch. No component
observes an HTTP status or matches an error message, and no shell rewrites the
cached failure. Ownership changes only how that failure presents at a position
in the React tree.

## Run it locally

```bash
npm --prefix demo install
npm --prefix demo run dev
```

The Worker configuration is the source of truth. `wrangler types` generates the
binding and runtime declarations from `demo/wrangler.jsonc`; there is no
`@cloudflare/workers-types` dependency.

```bash
npm --prefix demo test
npm --prefix demo run deploy
```

`deploy` builds the vinext application and publishes the generated Worker,
static assets, D1 binding, and `demo.result-rpc.com` Custom Domain directly to
Cloudflare.

---

# Coding-agent start
Source: https://result-rpc.com/start/agents

Use the canonical [`result-rpc` skill](https://result-rpc.com/skill.md) as the entry point for an
unfamiliar codebase. It is generated from the same `SKILL.md` that ships in the
npm package, so the public and installed instructions cannot drift.

## Route before writing

- New integration: `/start/quickstart.md`
- Browser code: `/concepts/client-boundary.md`
- Handler calls fetch, a database, filesystem, or SDK:
  `/concepts/results.md` and `/concepts/errors.md`
- React query state or cache: `/concepts/react.md`
- `Date`, `Map`, `Set`, `BigInt`, or custom values: `/concepts/wire.md`
- Mutation invalidation or optimistic state: `/concepts/mutations.md`
- App-wide auth, access, or offline behavior: `/concepts/shells.md` and
  `/concepts/layers.md`

## Machine-readable surfaces

Blume exposes each page through several equivalent agent-facing interfaces:

- [`/skill.md`](https://result-rpc.com/skill.md) — the canonical task router and guardrails.
- [`/llms.txt`](https://result-rpc.com/llms.txt) — the compact documentation index.
- [`/llms-full.txt`](https://result-rpc.com/llms-full.txt) — the complete agent-oriented corpus.
- Append `.md` to any documentation route for the page's Markdown.
- [`/agent-readability.json`](https://result-rpc.com/agent-readability.json) — discovery metadata
  for every enabled machine-readable surface.
- [`/.well-known/mcp.json`](https://result-rpc.com/.well-known/mcp.json) — the hosted, read-only MCP
  server discovery document.

The page-actions menu also offers **Copy as Markdown**, **Open in chat**, and
**Connect to MCP**. The documentation's source Markdown remains authoritative
across all of them.

## Install the packaged skill

After installing `result-rpc`, link the skill into the convention your coding
agent reads. See [Agent skill](/reference/agent-skill/) for Codex and Claude
Code commands, copy alternatives, and verification.

---

# Installation
Source: https://result-rpc.com/start/installation

Install the single `result-rpc` package with your package manager:

```sh
npm install result-rpc
# or: pnpm add result-rpc
# or: yarn add result-rpc
# or: bun add result-rpc
```

Requirements:

- Node.js 20.19.5 or newer
- TypeScript 5.4 or newer
- React 18.3 or newer when using `result-rpc/react`

The published declaration surface is tested with TypeScript 5.4, 5.9, and 7.0.
The package is ESM-only.

One versioned package, one entry per runtime — the root is everything
isomorphic (the contract language):

```ts
import {
  rpc,
  error,
  errorCatalog,
  err,
  ok,
  wire,
  defineLayer,
  defineService,
  resolveServices,
  type RouterInputs,
  type RouterOutputs,
} from "result-rpc";
import { createFetchHandler, serverRpc } from "result-rpc/server";
import { batchFetchTransport, createBrowserClient } from "result-rpc/client";
import { createQueryRuntime } from "result-rpc/query";
import { defineShell, layerShell, ResultRpcProvider, useResultQuery } from "result-rpc/react";
import { tryDb } from "result-rpc/db";
import { createParityClient } from "result-rpc/testing";
```

| Entry                | Use it for                                                                         |
| -------------------- | ---------------------------------------------------------------------------------- |
| `result-rpc`         | Shared contracts, codecs, Results, error definitions, layers, services, and models |
| `result-rpc/server`  | Procedure implementations, fetch handlers, and direct server clients               |
| `result-rpc/client`  | Browser clients, transports, and client-originated failures                        |
| `result-rpc/query`   | The React-free query runtime, including server-side prefetching                    |
| `result-rpc/react`   | Providers, hooks, shells, and hydration boundaries                                 |
| `result-rpc/db`      | ORM-independent database Result helpers                                            |
| `result-rpc/testing` | Test clients that exercise the real wire boundary                                  |

> **Keep implementations out of browser bundles.** Put the contract in a shared
> module and import that value when creating a browser client. Do not import the
> implemented server router: it retains its handlers and may retain database
> drivers, environment access, and private error classes. See [The client
> boundary](/concepts/client-boundary/).

Continue with the [quickstart](/start/quickstart/) to build one complete query.

---

# Introduction
Source: https://result-rpc.com/start/introduction

result-rpc is an RPC layer for React in the tRPC tradition — contract in
TypeScript, procedures on the server, hooks in components — with one foundational
change: every way an operation can fail is a typed, wire-safe value in that
operation's own closed union, and responsibility for each failure is assigned
to exactly one place in the component tree.

**Expected failures are part of the contract. Unexpected exceptions are not.**
Procedures return anticipated failures as tagged values in their declared
`Result`. Unexpected server exceptions are reported through `onInternalError`
with their private cause and exposed to clients only as a sanitized
`server/internal` failure. Declared failures produce structured Result events;
exceptions remain incident signals.

The problem it addresses shows up once an app is a few years old. Offline
behavior, 5xx handling, session expiry, and observability stop being polish and
become the work, and you end up threading them through every query and
mutation, or bolting them on with `onError` defaults, axios-style interceptors,
and a Sentry integration that guesses at what happened. This library treats
those cases as ordinary values with declared owners, and emits observability as
a structured stream rather than something you reconstruct after the fact.

If you looked at Effect for this and decided it was more than you wanted, the
overlapping parts are here — typed errors, services, layers — with a smaller
API surface and hooks that look like the ones you already write.

If you tried the halfway version — neverthrow or better-result on the server,
procedures returning `Result` as data — you know where it stops: tagged errors
are only shallowly serialized, so their runtime API dies at the serializer, and on the client
`query.error` becomes a different thing from `query.data.error`. This library
starts there: it validates the plain wire form, then reconstructs both the Result
and its real `TaggedError` instance on the client.

```ts
const query = useResultQuery(client.doc.byId, { id: "doc_123" });

if (query.state === "failure") {
  // DocNotFound | Unauthorized | ServerInternal | Offline | NetworkFailure |
  // Timeout | HttpFailure | ProtocolViolation | DecodeFailure | Stale
  query.error;
}
```

Ten tags looks like a lot until you notice they are not new failure modes —
they are the ones your stack already has, mostly unnamed. With tRPC's standard
model, returned domain failures live in procedure data while thrown server,
framework, and transport failures use the query error channel. A custom error
formatter can enrich that shared channel, but it does not combine both halves
into one exact per-procedure Result union. result-rpc's union is the same
reality, admitted, in one place, closed. And no component has to
branch on all of it, because the same union is narrowed by what the tree
already takes responsibility for:

```ts
const query = AuthShell.useQuery(client.doc.byId, { id: "doc_123" });

if (query.state === "failure") {
  // DocNotFound
  query.error;
}
```

Nothing was hidden. `Unauthorized` is gone because an enclosing shell
guarantees a session and redirects when that stops being true. The transport
tags are gone because the app shell owns the offline banner. The protocol tags
are gone because they escalate to an error boundary. Each shell subtracts
exactly what it takes responsibility for, and it does so in the type.

The pieces, in the order this document builds them:

1. **A wire contract** — procedures, codecs, and tagged errors declared once,
   shared by both sides; rich values survive the wire.
2. **Middleware and services** — request context that grows as middleware adds
   guarantees; process-lifetime resources resolved once as a dependency graph.
3. **A direct client** whose every call resolves `Result<T, ExactUnion>` —
   never a thrown transport error on the side. Shell-owned mutation control
   and cancellation remain separate non-failure signals.
4. **A Result-native query cache** — caching, retries, optimistic updates,
   SSR, all speaking Result.
5. **Shells** — error boundaries for values: providers that own classes of
   failure and subtract them from the unions components see.

Routing, SSR frameworks, and bundling are explicitly not on the list — shells
are providers and hooks, so they compose with whatever owns the tree.

> **Status**: `0.2.0` is published with npm provenance. The project is pre-1.0,
> so its API may still change between minor releases. Everything documented here
> is implemented and tested, and the `examples/` directory is runnable.

## The two problems

## Problem one: two failure channels

You have written this component. Domain failures come back as data; transport
failures come back somewhere else:

```ts
const query = useQuery({
  queryFn: () => rpc.doc.byId.query({ id }),
});

query.data;
// Result<Doc, DocNotFound | Unauthorized> | undefined

query.error;
// TRPCClientError | null — a separate, framework-wide error shape
```

Domain failures are _successful query data_. Network and thrown server
failures use the query error channel. Retries, error boundaries, offline
behavior, and exhaustive matching now operate on different halves of the same
operation. A formatter can enrich the framework-wide error shape, but it does
not give each procedure its own closed `E` union.

Every good team patches this, and each patch is a known move:

- **Discipline.** Decree that `query.error` is transport-only and return a
  discriminated union as data. Now the cache's machinery — retries, error
  boundaries, offline pausing — operates on the half your domain errors are
  not in, exhaustive matching operates on the half your transport errors are
  not in, and every component maps every tag by hand, because nothing ever
  narrows.
- **Encoding.** superjson-encode the Result objects across the wire. You get
  Result-_shaped_ JSON, not a contract: no closed union per procedure, no
  exhaustiveness, no retry or status policy attached to the error.
- **Interception.** A global `onError` callback on the client. That is
  problem two.

result-rpc makes the operation the unit of composition:

```ts
type GetDocError =
  | DocNotFound
  | Unauthorized
  | ServerInternal
  | Offline
  | NetworkFailure
  | Timeout
  | HttpFailure
  | ProtocolViolation
  | DecodeFailure
  | Stale;
```

The shared contract declares server and middleware errors. The client boundary
adds transport and protocol errors. The query runtime preserves the full union
while handling caching, retries, pausing, hydration, and cancellation.

## Problem two: the 401 interceptor

A complete union is honest, but exhaustiveness is not relevance. A component
that renders a document has business with `DocNotFound`. It has no business
deciding what happens when the network is down or the session is revoked
mid-render.

`Unauthorized` is the halfway house that exposes this. It is domain-shaped —
declared, typed, expected by every procedure that requires a session — and it
is ambient: it can surface on any call, and no document component should
carry branching logic for what sign-out looks like. The domain bucket taxes
every component with it; the transport bucket makes it stringly. Neither
holds it — and it is not alone: plan limits, org suspension, maintenance
windows, read-only mode all have the same shape, declared like domain errors
but owned like infrastructure. So every app that survives contact with
production grows one of these:

```ts
// somewhere global, in every codebase, in some costume
queryClient.setDefaultOptions({
  queries: {
    onError: (error) => {
      if ((error as any)?.data?.httpStatus === 401) {
        window.location.href = "/login";
      }
    },
  },
});
```

A global, stringly hook, invisible to the type system, that fires once per
in-flight query, races the components' own error branches, and blanks whatever
the user was looking at. The disciplined version — a cache-level handler plus
per-query `meta` flags to suppress it on the login screen — is the same move
with more indirection, and it double-fires and races the same way. Both exist
because the alternative — handling session expiry in every component that
fetches — is worse.

The requirement the interceptor cannot express is that ownership depends on
_where you are_: the app shell should own `Unauthorized` almost everywhere,
while the one login-adjacent screen that wants to render it inline takes it
back. result-rpc keeps the union complete at the contract and replaces the
interceptor with a typed, tree-positional owner: a shell declares, in one
place, which tags it takes responsibility for, and those tags leave the union
every component beneath it sees — while a component rendered outside the
shell (or using the unnarrowed hook) sees the full union again. Handling a
tag or delegating it is a choice made by position, and the type at every call
site shows which choice is in force. That is the [Shells](/concepts/shells/)
section, and it is the reason the rest of the machinery exists.

## What result-rpc owns

| Concern            | result-rpc contract                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| Result composition | Plain Result values, `gen`/`yield*`, `tryPromise`, union-preserving combinators, exhaustive matching |
| Error definitions  | Namespaced tags, wire codecs, HTTP/retry/visibility policy                                           |
| RPC                | Procedures, middleware, routers, server execution, protocol, clients                                 |
| Transport failures | Tagged additions to each procedure's inferred error union                                            |
| Query runtime      | Keys, caching, retries, invalidation, lifecycle, hydration                                           |
| Failure ownership  | Shells that subtract claimed errors and guarantee context                                            |
| React              | Query, mutation, subscription, suspense, and SSR bindings                                            |
| Diagnostics        | Safe incident IDs publicly; full causes only in local observability                                  |
| Observability      | Wire event stream, claim breadcrumbs, policy-aware server taps, Result taps                          |
| Cache coherence    | Entity identities (patch by model+id), declared invalidation, membership via `.affects`              |
| Forms              | Validator-as-wire-codec adoption, plus server-issue → field projection                               |

The query engine uses `@tanstack/query-core` privately. That is an engine
choice, not part of the public API. Applications do not install or compose
better-result, tRPC, or React Query around result-rpc.

---

# Quickstart
Source: https://result-rpc.com/start/quickstart

The smallest browser-safe app: one procedure, one domain error, no shells.
The contract is separate from its server implementation because the browser
needs the codecs and error definitions, not the handler or its dependencies.

Coming from tRPC, watch for two differences. The handler _returns_ its
failure — `err(...)` against a declared union — instead of throwing it. And
the component switches over one channel that includes the transport: there is
no `query.error` on the side, and no `Result` buried inside `query.data`
either.

## Install

```sh
npm install result-rpc
```

This quickstart requires Node.js 20.19.5 or newer, TypeScript 5.4 or newer, and
React 18.3 or newer. See [Installation](/start/installation/) for other package
managers and the package's runtime entry points.

## Declare the error and the procedure

```ts
import { error, rpc, wire } from "result-rpc";

export const GreetingNotFound = error({
  tag: "greeting/not-found",
  data: wire.object({ name: wire.string }),
  httpStatus: 404,
});

export const app = rpc.context<{}>();

export const greetContract = app
  .procedure()
  .input(wire.object({ name: wire.string }))
  .output(wire.string)
  .errors({ GreetingNotFound })
  .query();

export const appContract = app.contract({
  greet: greetContract,
});
```

This shared module contains only the runtime contract: codecs, error
definitions, and policies. It is safe to import from either side of the wire.

Infer application types from the procedure instead of restating the codec or
its error union:

```ts
import type { ProcedureError, ProcedureOutput } from "result-rpc";

type Greeting = ProcedureOutput<typeof greetContract>; // string
type GreetingFailure = ProcedureError<typeof greetContract>; // GreetingNotFound
```

Use `RouterInputs`, `RouterOutputs`, and `RouterErrors` instead when the nested
application shape is more useful than one named procedure.

For rich values, describe the real value on the contract. Do not flatten it to
a JSON-shaped substitute:

```ts
const availabilityContract = app
  .procedure()
  .input(wire.object({ propertyId: wire.string }))
  .output(wire.object({ available: wire.boolean, updatedAt: wire.date }))
  .query();
```

The browser receives `updatedAt` as a `Date`. See [The wire](/concepts/wire/)
for the full codec table.

## Implement and serve it

```ts
import { err, ok } from "result-rpc";
import { createFetchHandler, serverRpc } from "result-rpc/server";
import { greetContract } from "./contract";

const server = serverRpc.context<{}>();
const greet = server
  .implement(greetContract)
  .handler(({ input, errors }) =>
    input.name === "nobody"
      ? err(errors.GreetingNotFound({ name: input.name }))
      : ok(`Hello, ${input.name}!`),
  );

export const router = server.router({ greet });

export const handler = createFetchHandler({
  router,
  createContext: () => ({}),
});
```

`handler` is a `(request: Request) => Promise<Response>` — mount it on any
fetch-native server (Bun, Deno, Cloudflare Workers, Node 20+, Hono, Next
route handlers).

For a concrete Hono + Vite development setup, mount that fetch handler on a
small Node server:

```ts
// server.ts
import { serve } from "@hono/node-server";
import { Hono } from "hono";
import { handler } from "./server/rpc";

const server = new Hono();
server.all("/rpc", (context) => handler(context.req.raw));
serve({ fetch: server.fetch, port: 3001 });
```

and let the browser keep using the relative `/rpc` URL through Vite:

```ts
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  server: { proxy: { "/rpc": "http://127.0.0.1:3001" } },
});
```

Run `tsx watch server.ts` and `vite` as the two development processes. In a
single fetch-native deployment, mount `handler` directly and omit the proxy.

The handler must return the declared Result. Returning an undeclared tag is a
type error; throwing unexpectedly or smuggling a malformed error is treated as
a defect and yields a sanitized `server/internal`. Configure `onInternalError`
on the fetch handler to report the private cause.

## Adopt fallible external I/O

An anticipated failed fetch, database call, or SDK call belongs in a declared
Result branch. Use `tryPromise` at that throwing boundary:

```ts
const response =
  yield *
  (await tryPromise(
    () => fetch(url),
    () => errors.GreetingNotFound({ name: input.name }),
  ));
```

Fold provider-specific detail into the public error the caller can act on;
unexpected programmer defects may still throw and become sanitized
`server/internal`. The complete pattern is in
[Result composition](/concepts/results/) and [Errors](/concepts/errors/).

## Call it

```ts
import { createBrowserClient, fetchTransport } from "result-rpc/client";
import { appContract } from "./contract";

export const client = createBrowserClient({
  contract: appContract,
  transport: fetchTransport({ url: "/rpc" }),
});
```

Do not import the implemented router into browser code. A router retains its
handlers and may retain server-only dependencies; the contract is the public
runtime value intended for the client bundle.

## Render it

```tsx
import { ResultRpcProvider, useResultQuery } from "result-rpc/react";

export function App({ name }: { name: string }) {
  return (
    <ResultRpcProvider client={client}>
      <Greeting name={name} />
    </ResultRpcProvider>
  );
}

function Greeting({ name }: { name: string }) {
  const greeting = useResultQuery(client.greet, { name });

  switch (greeting.state) {
    case "pending":
      return <p>…</p>;
    case "success":
      return <p>{greeting.value}</p>;
    case "failure":
      switch (greeting.error._tag) {
        case "greeting/not-found":
          return <p>No greeting for {greeting.error.data.name}</p>;
        default:
          return <p>Something went wrong</p>;
      }
  }
}
```

That `default:` branch is where this quickstart stops and the library begins:
the failure union also carries transport, protocol, and staleness tags, and
branching on all of them in every component is exactly the burden
[shells](/concepts/shells/) remove. Continue with
[errors](/concepts/errors/) → [the contract](/concepts/contract/) →
[shells](/concepts/shells/), or read the
[examples ladder](/reference/examples/) end to end.