@abide/abide 0.42.0 → 0.43.0

package/src/lib/cli/runCli.ts

@@ -67,7 +67,7 @@ a bare word runs a command:
   /disconnect                     → forget the saved connection, exit
   <cmd> [--flags]                 → one-shot RPC against the resumed target
 
-The connection verbs are `/`-prefixed only — no bare aliases — so a bare word is
+The connection rpcs are `/`-prefixed only — no bare aliases — so a bare word is
 always an RPC command and never collides. Env layers ABIDE_APP_URL/ABIDE_APP_TOKEN (shell >
 data-dir > binary-dir) supply the baked default a fresh download resumes against.
 */

package/src/lib/cli/types/CliManifest.ts

@@ -2,7 +2,7 @@ import type { CliManifestEntry } from './CliManifestEntry.ts'
 
 /*
 Map from rpc export-name (e.g. "getReport") to its manifest entry. Built
-by the bundler from the same verbRegistry MCP consumes; entries are
+by the bundler from the same rpcRegistry MCP consumes; entries are
 emitted only for rpcs with `clients.cli: true`. The CLI binary and any
 programmatic createClient caller read this to dispatch calls.
 */

package/src/lib/cli/types/CliManifestEntry.ts

@@ -1,4 +1,4 @@
-import type { HttpVerb } from '../../shared/types/HttpVerb.ts'
+import type { HttpMethod } from '../../shared/types/HttpMethod.ts'
 
 /*
 Per-command manifest entry baked into the standalone CLI binary by the
@@ -9,7 +9,7 @@ both rpcs and socket commands — a socket `tail` is a GET against
 streams it live; a socket `publish` is a POST to the same path.
 */
 export type CliManifestEntry = {
-    method: HttpVerb
+    method: HttpMethod
     url: string
     jsonSchema?: Record<string, unknown>
     // Request Accept header. Socket tail sets text/event-stream to stream live frames.

package/src/lib/mcp/annotationsForMethod.ts

@@ -1,8 +1,8 @@
-import type { HttpVerb } from '../shared/types/HttpVerb.ts'
+import type { HttpMethod } from '../shared/types/HttpMethod.ts'
 
 /*
-Maps an HTTP verb to MCP tool annotations so a model can tell a read from
-a write before calling. Abide derives these from the verb the RPC was
+Maps an HTTP method to MCP tool annotations so a model can tell a read from
+a write before calling. Abide derives these from the rpc the RPC was
 declared with rather than asking the author to repeat the intent:
   - GET / HEAD  → read-only, non-destructive
   - POST        → creates; not idempotent, not (necessarily) destructive
@@ -10,9 +10,9 @@ declared with rather than asking the author to repeat the intent:
   - PATCH       → modifies; destructive, not idempotent
   - DELETE      → removes; idempotent + destructive
 The shape matches MCP's ToolAnnotations (readOnlyHint / destructiveHint /
-idempotentHint); fields a verb doesn't imply are left off.
+idempotentHint); fields a rpc doesn't imply are left off.
 */
-export function annotationsForMethod(method: HttpVerb): Record<string, boolean> {
+export function annotationsForMethod(method: HttpMethod): Record<string, boolean> {
     switch (method) {
         case 'GET':
         case 'HEAD':

package/src/lib/mcp/createMcpServer.ts

@@ -14,10 +14,10 @@ object whose `handle(request)` is the function the bun route at
 default-constructs it; there is no user-authored server module. Server
 name/version default from package.json.
 
-Tools are derived from every verb with `clients.mcp: true` (auto-on for
-read-only verbs that carry a schema; mutating verbs opt in explicitly)
+Tools are derived from every rpc with `clients.mcp: true` (auto-on for
+read-only rpcs that carry a schema; mutating rpcs opt in explicitly)
 and from every socket with `clients.mcp: true` (a `<base>-tail` read tool
-plus a `<base>-publish` tool when clientPublish is set). The HTTP verb
+plus a `<base>-publish` tool when clientPublish is set). The HTTP method
 feeds each rpc tool's annotations. Auth inherits from the inbound request
 — bearer / cookie headers flow into the synthesized Request that hits
 each rpc handler. An optional `authorize` hook in opts can short-circuit

package/src/lib/mcp/mcpSurface.ts

@@ -1,7 +1,7 @@
 import { promptRegistry } from '../server/prompts/promptRegistry.ts'
-import { dispatchVerbInProcess } from '../server/rpc/dispatchVerbInProcess.ts'
-import { findVerbByCommandName } from '../server/rpc/findVerbByCommandName.ts'
-import { verbRegistry } from '../server/rpc/verbRegistry.ts'
+import { dispatchRpcInProcess } from '../server/rpc/dispatchRpcInProcess.ts'
+import { findRpcByCommandName } from '../server/rpc/findRpcByCommandName.ts'
+import { rpcRegistry } from '../server/rpc/rpcRegistry.ts'
 import { socketOperations } from '../server/sockets/socketOperations.ts'
 import { socketRegistry } from '../server/sockets/socketRegistry.ts'
 import { abideLog } from '../shared/abideLog.ts'
@@ -58,12 +58,12 @@ export type McpSurface = {
 /*
 Builds the array of MCP tool descriptors.
 
-RPCs: every verb with clients.mcp=true becomes one tool named after the
-export's URL (folder segments joined with `-`). The HTTP verb feeds the
+RPCs: every rpc with clients.mcp=true becomes one tool named after the
+export's URL (folder segments joined with `-`). The HTTP method feeds the
 tool's annotations (readOnlyHint / destructiveHint / idempotentHint) so
 a model can tell a read from a write; reads auto-expose while mutating
-verbs require an explicit clients.mcp (see resolveClientFlags). When the
-verb declares an `outputSchema` it's advertised as the tool outputSchema.
+rpcs require an explicit clients.mcp (see resolveClientFlags). When the
+rpc declares an `outputSchema` it's advertised as the tool outputSchema.
 
 Sockets: every socket with clients.mcp=true contributes a `<base>-tail`
 read tool (recent buffered messages) and, when clientPublish is set, a
@@ -71,7 +71,7 @@ read tool (recent buffered messages) and, when clientPublish is set, a
 */
 export function buildTools(): ToolDescriptor[] {
     const tools: ToolDescriptor[] = []
-    for (const entry of verbRegistry.values()) {
+    for (const entry of rpcRegistry.values()) {
         if (!entry.clients.mcp) {
             continue
         }
@@ -154,7 +154,7 @@ export function buildPrompts(): PromptDescriptor[] {
 }
 
 /* MCP tool-dispatch spans, opt-in via DEBUG=abide:mcp — a model's tool call,
-   wrapping the underlying verb dispatch in the same trace. */
+   wrapping the underlying rpc dispatch in the same trace. */
 const mcpLog = abideLog.channel('abide:mcp')
 
 function textResult(text: string, isError = false): ToolResult {
@@ -203,7 +203,7 @@ function callSocketTool(
 
 /*
 Tool dispatch. RPC tools synthesize a Request (with forwarded auth
-headers from `inbound`) and pipe it through verb.fetch inside the request
+headers from `inbound`) and pipe it through rpc.fetch inside the request
 scope — the same seam the HTTP router crosses, so validation, the handler,
 and the request-scoped helpers (per-call cache(), cookies(), request())
 behave identically. A handler throw is caught by the scope and framed as
@@ -217,14 +217,14 @@ export async function callTool(
     args: Record<string, unknown> | undefined,
     inbound: Request,
 ): Promise<ToolResult> {
-    const entry = findVerbByCommandName(toolName)
+    const entry = findRpcByCommandName(toolName)
     if (entry) {
-        /* A verb owns this name. If it isn't mcp-exposed it's still unavailable —
+        /* A rpc owns this name. If it isn't mcp-exposed it's still unavailable —
            don't fall through to a socket op that happens to share the name. */
         if (!entry.clients.mcp) {
             throw new Error(`unknown tool: ${toolName}`)
         }
-        const response = await dispatchVerbInProcess({
+        const response = await dispatchRpcInProcess({
             remote: entry.remote,
             args,
             baseUrl: `${new URL(inbound.url).origin}/`,
@@ -264,7 +264,7 @@ export function renderPrompt(
 
 /*
 Projects the app's MCP surface for an in-process consumer bound to `request`
-— tool calls forward that request's auth headers into the verb handler, so
+— tool calls forward that request's auth headers into the rpc handler, so
 the model acts with the caller's identity. Used by `agent()`.
 */
 export function mcpSurface(request: Request): McpSurface {

package/src/lib/mcp/types/McpServerOptions.ts

@@ -7,7 +7,7 @@ package.json by the bundler when MCP is wired into createServer).
   response. Defaults come from the project's package.json.
 - `authorize`: optional boundary check. Runs once per MCP request before
   any tool/resource dispatch. Throw HttpError (or any Error) to reject.
-  Per-tool authorization stays in the underlying verb handler.
+  Per-tool authorization stays in the underlying rpc handler.
 */
 export type McpServerOptions = {
     name?: string

package/src/lib/server/DELETE.ts

@@ -1,10 +1,10 @@
-import type { VerbHelper } from './rpc/types/VerbHelper.ts'
+import type { MutatingRpcHelper } from './rpc/types/RpcHelper.ts'
 import { unprocessed } from './rpc/unprocessed.ts'
 
 /*
-DELETE verb helper. The bundler rewrites every `export const x = DELETE(fn)` inside
-`src/server/rpc/<file>.ts` into a defineVerb call (server target) or a
+DELETE rpc helper. The bundler rewrites every `export const x = DELETE(fn)` inside
+`src/server/rpc/<file>.ts` into a defineRpc call (server target) or a
 remoteProxy stub (client target). Calling this directly throws.
 */
 // @documentation rpc
-export const DELETE: VerbHelper = (_fn: any, _opts?: any) => unprocessed('DELETE')
+export const DELETE: MutatingRpcHelper = (_fn: any, _opts?: any) => unprocessed('DELETE')

package/src/lib/server/GET.ts

@@ -1,10 +1,10 @@
-import type { VerbHelper } from './rpc/types/VerbHelper.ts'
+import type { RpcHelper } from './rpc/types/RpcHelper.ts'
 import { unprocessed } from './rpc/unprocessed.ts'
 
 /*
-GET verb helper. The bundler rewrites every `export const x = GET(fn)` inside
-`src/server/rpc/<file>.ts` into a defineVerb call (server target) or a
+GET rpc helper. The bundler rewrites every `export const x = GET(fn)` inside
+`src/server/rpc/<file>.ts` into a defineRpc call (server target) or a
 remoteProxy stub (client target). Calling this directly throws.
 */
 // @documentation rpc
-export const GET: VerbHelper = (_fn: any, _opts?: any) => unprocessed('GET')
+export const GET: RpcHelper = (_fn: any, _opts?: any) => unprocessed('GET')

package/src/lib/server/HEAD.ts

@@ -1,10 +1,10 @@
-import type { VerbHelper } from './rpc/types/VerbHelper.ts'
+import type { RpcHelper } from './rpc/types/RpcHelper.ts'
 import { unprocessed } from './rpc/unprocessed.ts'
 
 /*
-HEAD verb helper. The bundler rewrites every `export const x = HEAD(fn)` inside
-`src/server/rpc/<file>.ts` into a defineVerb call (server target) or a
+HEAD rpc helper. The bundler rewrites every `export const x = HEAD(fn)` inside
+`src/server/rpc/<file>.ts` into a defineRpc call (server target) or a
 remoteProxy stub (client target). Calling this directly throws.
 */
 // @documentation rpc
-export const HEAD: VerbHelper = (_fn: any, _opts?: any) => unprocessed('HEAD')
+export const HEAD: RpcHelper = (_fn: any, _opts?: any) => unprocessed('HEAD')

package/src/lib/server/PATCH.ts

@@ -1,10 +1,10 @@
-import type { VerbHelper } from './rpc/types/VerbHelper.ts'
+import type { MutatingRpcHelper } from './rpc/types/RpcHelper.ts'
 import { unprocessed } from './rpc/unprocessed.ts'
 
 /*
-PATCH verb helper. The bundler rewrites every `export const x = PATCH(fn)` inside
-`src/server/rpc/<file>.ts` into a defineVerb call (server target) or a
+PATCH rpc helper. The bundler rewrites every `export const x = PATCH(fn)` inside
+`src/server/rpc/<file>.ts` into a defineRpc call (server target) or a
 remoteProxy stub (client target). Calling this directly throws.
 */
 // @documentation rpc
-export const PATCH: VerbHelper = (_fn: any, _opts?: any) => unprocessed('PATCH')
+export const PATCH: MutatingRpcHelper = (_fn: any, _opts?: any) => unprocessed('PATCH')

package/src/lib/server/POST.ts

@@ -1,10 +1,10 @@
-import type { VerbHelper } from './rpc/types/VerbHelper.ts'
+import type { MutatingRpcHelper } from './rpc/types/RpcHelper.ts'
 import { unprocessed } from './rpc/unprocessed.ts'
 
 /*
-POST verb helper. The bundler rewrites every `export const x = POST(fn)` inside
-`src/server/rpc/<file>.ts` into a defineVerb call (server target) or a
+POST rpc helper. The bundler rewrites every `export const x = POST(fn)` inside
+`src/server/rpc/<file>.ts` into a defineRpc call (server target) or a
 remoteProxy stub (client target). Calling this directly throws.
 */
 // @documentation rpc
-export const POST: VerbHelper = (_fn: any, _opts?: any) => unprocessed('POST')
+export const POST: MutatingRpcHelper = (_fn: any, _opts?: any) => unprocessed('POST')

package/src/lib/server/PUT.ts

@@ -1,10 +1,10 @@
-import type { VerbHelper } from './rpc/types/VerbHelper.ts'
+import type { MutatingRpcHelper } from './rpc/types/RpcHelper.ts'
 import { unprocessed } from './rpc/unprocessed.ts'
 
 /*
-PUT verb helper. The bundler rewrites every `export const x = PUT(fn)` inside
-`src/server/rpc/<file>.ts` into a defineVerb call (server target) or a
+PUT rpc helper. The bundler rewrites every `export const x = PUT(fn)` inside
+`src/server/rpc/<file>.ts` into a defineRpc call (server target) or a
 remoteProxy stub (client target). Calling this directly throws.
 */
 // @documentation rpc
-export const PUT: VerbHelper = (_fn: any, _opts?: any) => unprocessed('PUT')
+export const PUT: MutatingRpcHelper = (_fn: any, _opts?: any) => unprocessed('PUT')

package/src/lib/server/agent.ts

@@ -6,7 +6,7 @@ import { request } from './request.ts'
 The in-app agent surface. `agent(engine, messages)` runs a model engine
 against the app's own MCP surface and returns the engine's frame stream —
 it does NOT pick a transport. The handler wraps it in `jsonl()` or `sse()`,
-so consumption is the app's choice, same as any other streaming verb:
+so consumption is the app's choice, same as any other streaming rpc:
 
   // src/server/rpc/chat.ts
   import { agent } from '@abide/abide/server/agent'
@@ -18,10 +18,10 @@ so consumption is the app's choice, same as any other streaming verb:
 
 The engine — provider-specific, lives in a `@abide/<provider>` package —
 only sees the surface in and yields frames out, so swapping providers never
-touches the verb or the UI.
+touches the rpc or the UI.
 
 Permission is decided server-side, not negotiated at runtime: the surface
-is already gated by each verb's `clients.mcp` declaration plus its own
+is already gated by each rpc's `clients.mcp` declaration plus its own
 per-call handler auth, and any provider built-ins (e.g. Claude Code's bash
 tool) are fenced by static rules in the engine's config.
 */
@@ -71,7 +71,7 @@ export type AgentEngine = (input: {
 
 /*
 Runs an engine against the current request's MCP surface and returns its
-AgentFrame stream. Must be called inside a verb's request scope —
+AgentFrame stream. Must be called inside a rpc's request scope —
 mcpSurface() forwards the caller's auth into every tool dispatch. The
 handler chooses the transport: `jsonl(agent(engine, messages))` or
 `sse(agent(engine, messages))`.

package/src/lib/server/env.ts

@@ -14,7 +14,7 @@ deep inside a handler:
 
 Reads `Bun.env` (the process environment plus any `.env` Bun loaded), so any
 Standard Schema library — zod, valibot, arktype — works without an adapter,
-same as the verb helpers. Coercion (e.g. a numeric PORT) lives in the schema.
+same as the rpc helpers. Coercion (e.g. a numeric PORT) lives in the schema.
 
 The schema is registered (envSchemaStore) so the bundle launcher can project
 the first-run setup form from the same declaration. When the launcher imports

package/src/lib/server/error.ts

@@ -1,5 +1,6 @@
 import { NO_STORE } from '../shared/CACHE_CONTROL_VALUES.ts'
 import { TEXT_PLAIN } from '../shared/TEXT_PLAIN.ts'
+import type { ErrorDescriptor } from '../shared/types/ErrorDescriptor.ts'
 import type { TypedResponse } from './rpc/types/TypedResponse.ts'
 import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
 
@@ -57,17 +58,58 @@ branch carries (`TypedResponse<{user}> | TypedResponse<never>` → Return
 = {user}).
 */
 // @documentation response
-export function error(status: number, message?: string, init?: ResponseInit): TypedResponse<never> {
+export function error(descriptor: ErrorDescriptor): TypedResponse<never>
+export function error(status: number, message?: string, init?: ResponseInit): TypedResponse<never>
+export function error(
+    statusOrDescriptor: number | ErrorDescriptor,
+    message?: string,
+    init?: ResponseInit,
+): TypedResponse<never> {
+    /* A typed-error descriptor (`error(errors.invalidCoupon({…}))`) serializes as a
+       JSON `{ $abideError, data }` body at the descriptor's status — the client
+       parses it back onto the thrown HttpError's `.kind` / `.data`. */
+    if (typeof statusOrDescriptor === 'object') {
+        const descriptor = statusOrDescriptor
+        return new Response(
+            JSON.stringify({ $abideError: descriptor.$abideError, data: descriptor.data }),
+            withStatusText(
+                withResponseDefaults(
+                    undefined,
+                    { 'Content-Type': 'application/json', 'Cache-Control': NO_STORE },
+                    descriptor.status,
+                ),
+                descriptor.status,
+            ),
+        ) as TypedResponse<never>
+    }
+    const status = statusOrDescriptor
     const body = message ?? STATUS_TEXT[status] ?? `HTTP ${status}`
     return new Response(
         body,
-        withResponseDefaults(
-            init,
-            {
-                'Content-Type': TEXT_PLAIN,
-                'Cache-Control': NO_STORE,
-            },
+        withStatusText(
+            withResponseDefaults(
+                init,
+                {
+                    'Content-Type': TEXT_PLAIN,
+                    'Cache-Control': NO_STORE,
+                },
+                status,
+            ),
             status,
         ),
     ) as TypedResponse<never>
 }
+
+/*
+Stamps the status's standard reason phrase onto `init.statusText` so the wire
+status line reads `404 Not Found` and the client's `HttpError.statusText` is
+populated — Bun's `Response` never derives statusText from the code. A caller's
+explicit `init.statusText` (preserved through withResponseDefaults) still wins;
+an unlisted code leaves it untouched.
+*/
+function withStatusText(init: ResponseInit, status: number): ResponseInit {
+    if (init.statusText === undefined && STATUS_TEXT[status] !== undefined) {
+        return { ...init, statusText: STATUS_TEXT[status] }
+    }
+    return init
+}

package/src/lib/server/json.ts

@@ -13,7 +13,7 @@ own per-request cache handles in-process dedupe.
       json(await db.getOrder(id)),
   )
 
-The return type carries `T` as a phantom brand so the verb helper can
+The return type carries `T` as a phantom brand so the rpc helper can
 infer the caller-facing `Return` from the handler body — no need to
 annotate `GET<Args, Return>` just to type the response shape.
 

package/src/lib/server/rpc/buildErrorConstructors.ts

@@ -0,0 +1,19 @@
+import type { ErrorConstructors } from '../../shared/types/ErrorConstructors.ts'
+import type { ErrorSpec } from '../../shared/types/ErrorSpec.ts'
+
+/*
+Turns a rpc's declared `ErrorSpec` into the constructor object handed to the
+handler (`(args, { errors })`). Each constructor stamps its name + status onto an
+`ErrorDescriptor` carrying the call's `data`, which `error()` serializes as the
+`{ $abideError, data }` body. Receiver-agnostic on data: a nullary error ignores
+the (absent) argument.
+*/
+export function buildErrorConstructors<Spec extends ErrorSpec>(
+    spec: Spec,
+): ErrorConstructors<Spec> {
+    const entries = Object.entries(spec).map(([name, { status }]) => [
+        name,
+        (data: unknown) => ({ $abideError: name, status, data }),
+    ])
+    return Object.fromEntries(entries) as ErrorConstructors<Spec>
+}

package/src/lib/server/rpc/{defineVerb.ts → defineRpc.ts}

@@ -5,34 +5,36 @@ import { forwardHeaders } from '../../shared/forwardHeaders.ts'
 import { isReadOnlyMethod } from '../../shared/isReadOnlyMethod.ts'
 import { resolveClientFlags } from '../../shared/resolveClientFlags.ts'
 import type { ClientFlags } from '../../shared/types/ClientFlags.ts'
-import type { HttpVerb } from '../../shared/types/HttpVerb.ts'
+import type { ErrorSpec } from '../../shared/types/ErrorSpec.ts'
+import type { HttpMethod } from '../../shared/types/HttpMethod.ts'
 import type { RemoteFunction } from '../../shared/types/RemoteFunction.ts'
 import type { StandardSchemaV1 } from '../../shared/types/StandardSchemaV1.ts'
-import { json } from '../json.ts'
 import { requestContext } from '../runtime/requestContext.ts'
+import { buildErrorConstructors } from './buildErrorConstructors.ts'
 import { parseArgs } from './parseArgs.ts'
-import { registerVerb } from './registerVerb.ts'
-import { runWithVerbTimeout } from './runWithVerbTimeout.ts'
+import { registerRpc } from './registerRpc.ts'
+import { runWithRpcTimeout } from './runWithRpcTimeout.ts'
 import type { RemoteHandler } from './types/RemoteHandler.ts'
+import { validationError } from './validationError.ts'
 
 /*
-Stash for the per-request AbortController a timed verb composes into the
+Stash for the per-request AbortController a timed rpc composes into the
 inbound signal — read back in invoke's deadline callback to fire it. Lives on
-the scope's Request (one verb per .fetch — network or in-process dispatch) so
+the scope's Request (one rpc per .fetch — network or in-process dispatch) so
 an SSR pass's many in-process cache reads, which call invoke() directly and
 never reach parseArgsForFetch, can't cross-cancel.
 */
-const VERB_TIMEOUT_ABORT = Symbol('abideVerbTimeoutAbort')
+const RPC_TIMEOUT_ABORT = Symbol('abideRpcTimeoutAbort')
 
-/* Verb dispatch + validation spans, opt-in via DEBUG=abide:rpc. Reveals an
+/* Rpc dispatch + validation spans, opt-in via DEBUG=abide:rpc. Reveals an
    in-process RPC→RPC call (same request scope, same trace) as a nested span. */
 const rpcLog = abideLog.channel('abide:rpc')
 
 /*
-Builds a RemoteFunction from an HTTP verb + RPC URL + handler. The bundler
-rewrites every `export const VERB = handler(fn)` inside an `$rpc/**` module
-so the verb (from the export name) and the URL (from the file path under
-`src/server/rpc/`, with `/rpc/` prefix) are threaded into defineVerb.
+Builds a RemoteFunction from an HTTP method + RPC URL + handler. The bundler
+rewrites every `export const METHOD = handler(fn)` inside an `$rpc/**` module
+so the rpc (from the export name) and the URL (from the file path under
+`src/server/rpc/`, with `/rpc/` prefix) are threaded into defineRpc.
 
 The plain call (`fn(args)`) resolves to the Content-Type-decoded body;
 non-2xx responses throw HttpError. `.raw(args)` returns the underlying
@@ -45,32 +47,48 @@ Every raw invocation records the synthesized Request against the returned
 promise so cache() can stash it on the entry without re-building.
 */
 // @documentation plumbing
-export function defineVerb<Args, Return>(
-    method: HttpVerb,
+export function defineRpc<Args, Return>(
+    method: HttpMethod,
     url: string,
     handler: RemoteHandler<Args, Return>,
     opts?: {
         inputSchema?: StandardSchemaV1
         outputSchema?: StandardSchemaV1
         filesSchema?: StandardSchemaV1
+        errors?: ErrorSpec
         clients?: Partial<ClientFlags>
         crossOrigin?: boolean
-        /* Per-verb cap on actual received body bytes (413 past it); omitted = Bun's server-wide maxRequestBodySize. */
+        /* Per-rpc cap on actual received body bytes (413 past it); omitted = Bun's server-wide maxRequestBodySize. */
         maxBodySize?: number
-        /* Per-verb handler deadline (ms): a 504 once exceeded, on every surface (SSR/MCP/CLI/network). */
+        /* Per-rpc handler deadline (ms): a 504 once exceeded, on every surface (SSR/MCP/CLI/network). */
         timeout?: number
+        /* Durable delivery: on an unreachable server (transport failure / 502/503/504/52x)
+           the client proxy parks the request for replay instead of just throwing. The
+           parked write drains on `rpc.outbox.retry()` (no auto-drain). Mutating methods
+           only. */
+        outbox?: boolean
     },
 ): RemoteFunction<Args, Return> {
+    /* `outbox: true` is a mutation contract — a read RPC has nothing to durably deliver,
+       so reject it at declaration rather than silently ignore. The server handler itself
+       is unaffected; durability is a client-proxy concern. */
+    if (opts?.outbox === true && isReadOnlyMethod(method)) {
+        throw new Error(
+            `[abide] outbox: true is only valid on mutating RPCs (POST/PUT/PATCH/DELETE), not ${method}`,
+        )
+    }
     const timeout = opts?.timeout
     const inputSchema = opts?.inputSchema
     const outputSchema = opts?.outputSchema
     const filesSchema = opts?.filesSchema
+    /* The declared error constructors handed to the handler as its `{ errors }` ctx. */
+    const errors = buildErrorConstructors(opts?.errors ?? {})
     /*
     An input schema makes the handler safe to advertise to non-browser
-    surfaces. CLI flips on for any verb with one (a human/script invokes it
-    deliberately). MCP only auto-exposes read-only verbs (GET/HEAD) — a
+    surfaces. CLI flips on for any rpc with one (a human/script invokes it
+    deliberately). MCP only auto-exposes read-only rpcs (GET/HEAD) — a
     model shouldn't be able to mutate/delete just because the handler
-    carries a schema, so mutating verbs require an explicit clients.mcp.
+    carries a schema, so mutating rpcs require an explicit clients.mcp.
     Explicit `clients` always wins.
     */
     const hasSchema = inputSchema !== undefined
@@ -97,13 +115,13 @@ export function defineVerb<Args, Return>(
     async function runHandler(args: Args | undefined): Promise<Response> {
         return rpcLog.trace(
             `rpc ${method} ${url}`,
-            () => handler(args as Args) as unknown as Response,
+            () => handler(args as Args, { errors }) as unknown as Response,
         )
     }
 
     /*
     Validates the parsed args against inputSchema (text fields), then — when the
-    verb declares filesSchema — validates the File parts parseArgs split onto
+    rpc declares filesSchema — validates the File parts parseArgs split onto
     the request store and merges them into the args bag the handler receives.
     Either schema's issues become a 422. Files stay out of inputSchema so its
     JSON-Schema projection (OpenAPI/MCP/CLI) never has to model a binary.
@@ -115,7 +133,7 @@ export function defineVerb<Args, Return>(
                 inputSchema['~standard'].validate(value),
             )
             if (result.issues) {
-                return json({ issues: result.issues }, { status: 422 })
+                return validationError(result.issues)
             }
             value = result.value
         }
@@ -123,7 +141,7 @@ export function defineVerb<Args, Return>(
             const files = requestContext.getStore()?.files ?? {}
             const result = await filesSchema['~standard'].validate(files)
             if (result.issues) {
-                return json({ issues: result.issues }, { status: 422 })
+                return validationError(result.issues)
             }
             value = { ...(value as object), ...(result.value as object) }
         }
@@ -138,11 +156,11 @@ export function defineVerb<Args, Return>(
     SSR call.
     */
     /* Abort the controller parseArgsForFetch stashed on store.req; a no-op when none was stashed (SSR cache reads). */
-    function abortVerbTimeout(): void {
+    function abortRpcTimeout(): void {
         const req = requestContext.getStore()?.req as
-            | (Request & { [VERB_TIMEOUT_ABORT]?: AbortController })
+            | (Request & { [RPC_TIMEOUT_ABORT]?: AbortController })
             | undefined
-        req?.[VERB_TIMEOUT_ABORT]?.abort(new DOMException('handler timeout', 'TimeoutError'))
+        req?.[RPC_TIMEOUT_ABORT]?.abort(new DOMException('handler timeout', 'TimeoutError'))
     }
 
     function invoke(args: Args | undefined): Promise<Response> {
@@ -153,9 +171,9 @@ export function defineVerb<Args, Return>(
         /*
         On the deadline, fire the controller parseArgsForFetch composed into
         request().signal (absent on the SSR cache-read path, so a sibling
-        verb's outbound fetch is never cancelled) — then 504.
+        rpc's outbound fetch is never cancelled) — then 504.
         */
-        return runWithVerbTimeout(work, timeout, abortVerbTimeout)
+        return runWithRpcTimeout(work, timeout, abortRpcTimeout)
     }
 
     const remote = createRemoteFunction<Args, Return>({
@@ -168,17 +186,17 @@ export function defineVerb<Args, Return>(
         parseArgsForFetch: async (request) => {
             const args = await parseArgs(method, request, opts?.maxBodySize)
             /*
-            Compose this verb's deadline into request().signal so a handler's
+            Compose this rpc's deadline into request().signal so a handler's
             fetch(ext, { signal: request().signal }) is cancelled when the
             timeout fires — not just abandoned. Applied after parseArgs onto the
-            scope's *final* request: a maxBodySize verb swaps store.req for a
+            scope's *final* request: a maxBodySize rpc swaps store.req for a
             buffered copy (readBodyWithinLimit) and an app.handle hook may
             rewrite it, so composing onto the inbound `request` would leave
-            request() — and abortVerbTimeout, which reads store.req — pointed at
+            request() — and abortRpcTimeout, which reads store.req — pointed at
             an un-cancellable signal. Only the signal is shadowed; the body
             stays readable. The store always exists here (network + in-process
             dispatch both run inside runWithRequestScope); SSR cache reads call
-            invoke() directly, never this path, so a sibling verb is never
+            invoke() directly, never this path, so a sibling rpc is never
             cross-cancelled.
             */
             if (timeout !== undefined) {
@@ -187,7 +205,7 @@ export function defineVerb<Args, Return>(
                     const controller = new AbortController()
                     const composed = AbortSignal.any([req.signal, controller.signal])
                     Object.defineProperty(req, 'signal', { value: composed, configurable: true })
-                    Object.defineProperty(req, VERB_TIMEOUT_ABORT, {
+                    Object.defineProperty(req, RPC_TIMEOUT_ABORT, {
                         value: controller,
                         configurable: true,
                     })
@@ -196,7 +214,7 @@ export function defineVerb<Args, Return>(
             return args as Args | undefined
         },
     })
-    registerVerb({
+    registerRpc({
         remote: remote as RemoteFunction<unknown, unknown>,
         inputSchema,
         outputSchema,

package/src/lib/server/rpc/{dispatchVerbInProcess.ts → dispatchRpcInProcess.ts}

@@ -4,11 +4,11 @@ import type { AppModule } from '../AppModule.ts'
 import { runWithRequestScope } from '../runtime/runWithRequestScope.ts'
 
 /*
-Runs a verb in-process: synthesizes the rpc Request from the remote's own
+Runs a rpc in-process: synthesizes the rpc Request from the remote's own
 method + url and pipes it through remote.fetch — the same handler/validation/
 error path the HTTP router uses, no network hop. The single in-process
 dispatch every consumer surface (the CLI client, the MCP tool dispatcher, and
-the test client) routes through, so they can't drift on how a verb is invoked.
+the test client) routes through, so they can't drift on how a rpc is invoked.
 Takes the RemoteFunction directly — invocation never reads the registry
 entry's schemas/clients (validation is closed over inside the remote), so the
 entry is not a dependency here. `baseUrl` gives the synthetic Request its
@@ -22,7 +22,7 @@ resolution, and the app's handleError (or the 500 fallback) on a throw. The
 synthesized Request is shared between the scope store and the handler fetch so
 request() returns the same Request parseArgs read from.
 */
-export function dispatchVerbInProcess({
+export function dispatchRpcInProcess({
     remote,
     args,
     baseUrl,