@abide/abide 0.41.1 → 0.43.0

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,

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

@@ -0,0 +1,23 @@
+import type { StandardSchemaV1 } from '../../shared/types/StandardSchemaV1.ts'
+
+/*
+Flattens Standard Schema issues into a top-level-field → first-message map, the
+form-friendly companion to the raw `issues` on a 422. A path segment is either a
+bare `PropertyKey` or a `{ key }` wrapper (the spec allows both), so normalize
+before reading. First message wins per field (a form shows one per input); the
+raw `issues` keep every message and the full path. Issues with no string field
+(root-level refinements) are omitted — they live only in `issues`.
+*/
+export function fieldErrorsFromIssues(
+    issues: readonly StandardSchemaV1.Issue[],
+): Record<string, string> {
+    const fields: Record<string, string> = {}
+    for (const issue of issues) {
+        const segment = issue.path?.[0]
+        const key = typeof segment === 'object' ? segment.key : segment
+        if (typeof key === 'string' && !(key in fields)) {
+            fields[key] = issue.message
+        }
+    }
+    return fields
+}

package/src/lib/server/rpc/{findVerbByCommandName.ts → findRpcByCommandName.ts}

@@ -1,15 +1,15 @@
 import { commandNameForUrl } from '../../shared/commandNameForUrl.ts'
-import type { VerbRegistryEntry } from './types/VerbRegistryEntry.ts'
-import { verbRegistry } from './verbRegistry.ts'
+import { rpcRegistry } from './rpcRegistry.ts'
+import type { RpcRegistryEntry } from './types/RpcRegistryEntry.ts'
 
 /*
-Finds the registered verb whose URL maps to a given command name (folder
+Finds the registered rpc whose URL maps to a given command name (folder
 segments joined with `-`, per commandNameForUrl). The CLI client proxy and
 the MCP tool dispatcher both key off this name, so the scan lives here once
 rather than being re-implemented — and reused — at each call site.
 */
-export function findVerbByCommandName(name: string): VerbRegistryEntry | undefined {
-    for (const entry of verbRegistry.values()) {
+export function findRpcByCommandName(name: string): RpcRegistryEntry | undefined {
+    for (const entry of rpcRegistry.values()) {
         if (commandNameForUrl(entry.remote.url) === name) {
             return entry
         }

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

@@ -3,7 +3,7 @@ import { contentTypeOf } from '../../shared/contentTypeOf.ts'
 import { decodeRefJson } from '../../shared/decodeRefJson.ts'
 import { HttpError } from '../../shared/HttpError.ts'
 import { REF_JSON_HEADER } from '../../shared/REF_JSON_HEADER.ts'
-import type { HttpVerb } from '../../shared/types/HttpVerb.ts'
+import type { HttpMethod } from '../../shared/types/HttpMethod.ts'
 import { error } from '../error.ts'
 import { requestContext } from '../runtime/requestContext.ts'
 import { readBodyWithinLimit } from './readBodyWithinLimit.ts'
@@ -41,7 +41,7 @@ function splitFormData(form: FormData): Record<string, unknown> {
 }
 
 /*
-Parses + merges every source of args available for a verb-defined handler:
+Parses + merges every source of args available for a rpc-defined handler:
 - body (json or form-encoded, ignored for GET/DELETE/HEAD)
 - url query string
 
@@ -54,12 +54,12 @@ to layer the query into, and the framework's args type is a single bag rather
 than a `{body, query}` envelope. Returns undefined when no source contributes
 any key.
 
-`maxBodySize` (per-verb, opt-in) bounds the body's actual received bytes
+`maxBodySize` (per-rpc, opt-in) bounds the body's actual received bytes
 before any parse — see readBodyWithinLimit. Omitted = no abide-level check;
 Bun.serve's server-wide maxRequestBodySize is the ceiling.
 */
 export async function parseArgs(
-    method: HttpVerb,
+    method: HttpMethod,
     request: Request,
     maxBodySize?: number,
 ): Promise<unknown> {
@@ -129,12 +129,12 @@ export async function parseArgs(
     /*
     TODO(query-coercion): query params arrive as strings, so a numeric/boolean
     field reaches schema validation as `'2'`/`'true'`. Deferred deliberately:
-    parseArgs has no access to the verb's inputSchema (it lives in defineVerb),
+    parseArgs has no access to the rpc's inputSchema (it lives in defineRpc),
     and Standard Schema exposes no type structure to drive type-aware coercion.
     Blind value-shape coercion is unsafe — it would corrupt legitimately
     string-typed fields whose value looks numeric/boolean (ids, zip codes,
     version strings like '1.0'), silently breaking GET validation. A correct fix
-    needs the schema threaded in here (or a coercing schema adapter at the verb).
+    needs the schema threaded in here (or a coercing schema adapter at the rpc).
     */
     const bodyObject = (body ?? {}) as Record<string, unknown>
     const merged = { ...Object.fromEntries(url.searchParams), ...bodyObject }

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

@@ -2,14 +2,14 @@ import { HttpError } from '../../shared/HttpError.ts'
 import { error } from '../error.ts'
 
 /*
-Enforces a verb's maxBodySize on the actual received bytes, not the
+Enforces a rpc's maxBodySize on the actual received bytes, not the
 Content-Length header (absent on chunked bodies, trivially spoofed). A
 declared Content-Length over the limit rejects before reading anything;
 otherwise the body streams into a buffer that throws 413 the moment the
 limit is crossed — aborting the read, so the remaining bytes are never
 consumed. Returns a reassembled Request carrying the buffered body and the
 original headers, so the parse path's .text()/.formData() work unchanged.
-Only called when the verb declares maxBodySize; the default ceiling is
+Only called when the rpc declares maxBodySize; the default ceiling is
 Bun.serve's server-wide maxRequestBodySize, which Bun enforces natively.
 */
 export async function readBodyWithinLimit(request: Request, maxBytes: number): Promise<Request> {

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

@@ -0,0 +1,6 @@
+import { rpcRegistry } from './rpcRegistry.ts'
+import type { RpcRegistryEntry } from './types/RpcRegistryEntry.ts'
+
+export function registerRpc(entry: RpcRegistryEntry): void {
+    rpcRegistry.set(entry.remote.url, entry)
+}

package/src/lib/server/rpc/{verbRegistry.ts → rpcRegistry.ts}

@@ -1,11 +1,11 @@
-import type { VerbRegistryEntry } from './types/VerbRegistryEntry.ts'
+import type { RpcRegistryEntry } from './types/RpcRegistryEntry.ts'
 
 /*
-Process-wide registry of every verb-bound RPC declared in the app.
-defineVerb inserts on first construction (which happens at module-load
+Process-wide registry of every rpc-bound RPC declared in the app.
+defineRpc inserts on first construction (which happens at module-load
 time inside the rpc dispatcher cache or eagerly when MCP / CLI walks the
 rpc manifest). MCP server reads this to build its tools list; the CLI
 binary reads it to generate subcommands. The browser path never touches
 this — the client stub has no schema or clients metadata to register.
 */
-export const verbRegistry = new Map<string, VerbRegistryEntry>()
+export const rpcRegistry = new Map<string, RpcRegistryEntry>()

package/src/lib/server/rpc/{runWithVerbTimeout.ts → runWithRpcTimeout.ts}

@@ -1,12 +1,12 @@
 import { error } from '../error.ts'
 
 /*
-Bounds a verb handler's execution: races the in-flight `work` against `ms`.
+Bounds a rpc handler's execution: races the in-flight `work` against `ms`.
 On the deadline it resolves a 504 — so the caller (an SSR cache read, an
 MCP/CLI invocation, or the network response) is unblocked in time with an
 honest status — and calls `onTimeout` to cancel any
-cooperating outbound work (the network path composes the verb's deadline into
-request().signal; see defineVerb).
+cooperating outbound work (the network path composes the rpc's deadline into
+request().signal; see defineRpc).
 
 `work` keeps running after the deadline — JS can't cancel a running async
 function, only stop awaiting it — so its eventual settlement is swallowed to
@@ -14,7 +14,7 @@ avoid an unhandled rejection, and a late-resolved streaming Response has its
 body cancelled to release the underlying source. A handler that wants its own
 outbound I/O torn down should pass request().signal to it.
 */
-export function runWithVerbTimeout(
+export function runWithRpcTimeout(
     work: Promise<Response>,
     ms: number,
     onTimeout: () => void,

package/src/lib/server/rpc/types/RemoteHandler.ts

@@ -1,7 +1,9 @@
+import type { ErrorConstructors } from '../../../shared/types/ErrorConstructors.ts'
+import type { ErrorSpec } from '../../../shared/types/ErrorSpec.ts'
 import type { TypedResponse } from './TypedResponse.ts'
 
 /*
-Handler signature for verb-defined remote functions. Args is `undefined` for
+Handler signature for rpc-defined remote functions. Args is `undefined` for
 GETs/DELETEs with no query, JSON-shaped objects for json bodies, and
 form-shaped objects for form-encoded bodies. For a multipart upload it's the
 text fields (`inputSchema`) intersected with the validated File parts
@@ -13,7 +15,7 @@ decoding (a parsed object for JSON, a string for text/*, a Blob otherwise,
 `undefined` for 204). The handler must return a Response at runtime; the
 `TypedResponse<Return>` brand on `json`/`error`/`redirect`/`jsonl`/`sse`
 carries the body shape through the function's inferred return type so the
-verb helper can infer `Return` automatically — no need to annotate
+rpc helper can infer `Return` automatically — no need to annotate
 `GET<Args, Return>` when the handler returns one of the respond helpers.
 A bare `new Response(...)` is still acceptable: the brand is optional, so
 untagged Responses fall back to `Return = unknown`.
@@ -22,6 +24,10 @@ Handlers that need the inbound Request (headers, `request.signal`, …) read
 it via `request()` from `abide/server` rather than a handler parameter, so
 the signature stays a single parsed-`args` bag.
 */
-export type RemoteHandler<Args, Return> = (
+export type RemoteHandler<Args, Return, Errors extends ErrorSpec = Record<never, never>> = (
     args: Args,
+    /* The rpc's declared error constructors (`error(errors.invalidCoupon({…}))`), typed
+       from its `errors` opt; an empty object when none declared. A handler that takes only
+       `args` is still assignable here (fewer params is assignable to more). */
+    ctx: { errors: ErrorConstructors<Errors> },
 ) => TypedResponse<Return> | Promise<TypedResponse<Return>>