@abide/abide 0.48.0 → 0.50.0

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

@@ -4,10 +4,14 @@ import { createRemoteFunction } from '../../shared/createRemoteFunction.ts'
 import { forwardHeaders } from '../../shared/forwardHeaders.ts'
 import { isReadOnlyMethod } from '../../shared/isReadOnlyMethod.ts'
 import { resolveClientFlags } from '../../shared/resolveClientFlags.ts'
+import type { CachePolicy } from '../../shared/types/CachePolicy.ts'
 import type { ClientFlags } from '../../shared/types/ClientFlags.ts'
+import type { ErrorJsonSchemas } from '../../shared/types/ErrorJsonSchemas.ts'
 import type { HttpMethod } from '../../shared/types/HttpMethod.ts'
+import type { InputCoercion } from '../../shared/types/InputCoercion.ts'
 import type { RemoteFunction } from '../../shared/types/RemoteFunction.ts'
 import type { StandardSchemaV1 } from '../../shared/types/StandardSchemaV1.ts'
+import type { StreamPolicy } from '../../shared/types/StreamPolicy.ts'
 import { requestContext } from '../runtime/requestContext.ts'
 import { parseArgs } from './parseArgs.ts'
 import { registerRpc } from './registerRpc.ts'
@@ -50,38 +54,57 @@ export function defineRpc<Args, Return>(
     url: string,
     handler: RemoteHandler<Args, Return>,
     opts?: {
-        inputSchema?: StandardSchemaV1
-        outputSchema?: StandardSchemaV1
-        filesSchema?: StandardSchemaV1
+        /* Namespaced schemas (ADR-0020): `input` types + validates args, `output` is the
+           success-body schema (OpenAPI/MCP), `files` validates multipart File parts. */
+        schemas?: {
+            input?: StandardSchemaV1
+            output?: StandardSchemaV1
+            files?: StandardSchemaV1
+        }
+        /* Surface-exposure flags (browser/mcp/cli) — which surfaces advertise this rpc. */
         clients?: Partial<ClientFlags>
         crossOrigin?: boolean
         /* Per-rpc cap on actual received body bytes (413 past it); omitted = Bun's server-wide maxRequestBodySize. */
         maxBodySize?: number
         /* 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
-        /* Handler returns jsonl()/sse(): the bare call returns the Subscribable directly (for
+        /* Handler returns jsonl()/sse(): the bare call returns the NamedAsyncIterable directly (for
            isomorphic `for await (… of fn(args))` in server code). Bundler-stamped; the router's
            wire path (.fetch) is unaffected. */
         streaming?: boolean
+        /* Numeric/boolean input fields → parseArgs coerces a string query/form value into the
+           typed value the input schema expects (ADR-0028). Bundler-stamped from the endpoint's
+           `Args` type; absent on the fail-open path (a GET field then stays a string as before). */
+        coerce?: InputCoercion
+        /* The handler's input args projected to JSON Schema (ADR-0030 input side). Bundler-stamped
+           from the endpoint's input-parameter type; feeds the OpenAPI parameters/body / MCP inputSchema
+           / inspector input surface when no `schemas.input` validator is declared (which still
+           overrides it), and makes the endpoint advertisable to MCP/CLI. A SHAPE description only —
+           never runtime-validated, so it can't produce a 422. Absent on the fail-open path — the
+           surface then omits the input schema exactly as before. */
+        inputJsonSchema?: Record<string, unknown>
+        /* The handler's return type projected to JSON Schema (ADR-0030 D2). Bundler-stamped from the
+           endpoint's success-body type; feeds the OpenAPI 200 / MCP outputSchema / inspector surface
+           when no `schemas.output` validator is declared (which still overrides it). Absent on the
+           fail-open path — the surface then omits the response schema exactly as before. */
+        outputJsonSchema?: Record<string, unknown>
+        /* The handler's typed-error branches as a status-keyed JSON-Schema map (ADR-0030). Bundler-
+           stamped from the endpoint's `error.typed(...)` return branches; feeds the OpenAPI
+           `responses[status]` surface so each typed error's status + data payload is documented
+           alongside the 200. Absent on the fail-open path — the surface then omits the error
+           responses exactly as before. */
+        errorJsonSchemas?: ErrorJsonSchemas
+        /* Endpoint cache policy (ADR-0020) — read helpers only; readThrough's bottom layer. */
+        cache?: CachePolicy<Args>
+        /* Endpoint stream policy (ADR-0020) — streaming read helpers only; replay depth `n`. */
+        stream?: StreamPolicy
     },
 ): 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
+    const inputSchema = opts?.schemas?.input
+    const inputJsonSchema = opts?.inputJsonSchema
+    const outputSchema = opts?.schemas?.output
+    const filesSchema = opts?.schemas?.files
     /*
     An input schema makes the handler safe to advertise to non-browser
     surfaces. CLI flips on for any rpc with one (a human/script invokes it
@@ -89,8 +112,16 @@ export function defineRpc<Args, Return>(
     model shouldn't be able to mutate/delete just because the handler
     carries a schema, so mutating rpcs require an explicit clients.mcp.
     Explicit `clients` always wins.
+
+    A build-projected `inputJsonSchema` (ADR-0030 input side — the handler's
+    input parameter type projected to JSON Schema, present only when the type
+    resolved cleanly) counts as a machine-advertisable contract too, so a
+    plainly-typed handler auto-exposes without a hand-written `schemas.input`.
+    This is SHAPE-only: the projection describes the input, it is NEVER run as
+    runtime validation (no 422) — declaring `schemas.input` is still what adds
+    the runtime narrowing.
     */
-    const hasSchema = inputSchema !== undefined
+    const hasSchema = inputSchema !== undefined || inputJsonSchema !== undefined
     const clients = resolveClientFlags(opts?.clients, {
         mcp: hasSchema && isReadOnlyMethod(method),
         cli: hasSchema,
@@ -189,10 +220,12 @@ export function defineRpc<Args, Return>(
         clients,
         streaming: opts?.streaming ?? false,
         crossOrigin: opts?.crossOrigin,
+        cache: opts?.cache,
+        stream: opts?.stream,
         buildRequest,
         invoke,
         parseArgsForFetch: async (request) => {
-            const args = await parseArgs(method, request, opts?.maxBodySize)
+            const args = await parseArgs(method, request, opts?.maxBodySize, opts?.coerce)
             /*
             Compose this rpc's deadline into request().signal so a handler's
             fetch(ext, { signal: request().signal }) is cancelled when the
@@ -225,12 +258,13 @@ export function defineRpc<Args, Return>(
     registerRpc({
         remote: remote as RemoteFunction<unknown, unknown>,
         inputSchema,
+        inputJsonSchema,
         outputSchema,
+        outputJsonSchema: opts?.outputJsonSchema,
+        errorJsonSchemas: opts?.errorJsonSchemas,
         filesSchema,
-        clients,
         timeout,
         maxBodySize: opts?.maxBodySize,
-        crossOrigin: opts?.crossOrigin,
     })
     return remote
 }

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

@@ -1,9 +1,12 @@
 import { carriesBodyArgs } from '../../shared/carriesBodyArgs.ts'
 import { contentTypeOf } from '../../shared/contentTypeOf.ts'
-import { decodeRefJson } from '../../shared/decodeRefJson.ts'
+import { decodeWireBody } from '../../shared/decodeWireBody.ts'
 import { HttpError } from '../../shared/HttpError.ts'
 import { REF_JSON_HEADER } from '../../shared/REF_JSON_HEADER.ts'
+import { reviveWireField } from '../../shared/reviveWireField.ts'
 import type { HttpMethod } from '../../shared/types/HttpMethod.ts'
+import type { InputCoercion } from '../../shared/types/InputCoercion.ts'
+import type { WireKind } from '../../shared/types/WireKind.ts'
 import { error } from '../error.ts'
 import { requestContext } from '../runtime/requestContext.ts'
 import { readBodyWithinLimit } from './readBodyWithinLimit.ts'
@@ -62,6 +65,7 @@ export async function parseArgs(
     method: HttpMethod,
     request: Request,
     maxBodySize?: number,
+    coerce?: InputCoercion,
 ): Promise<unknown> {
     /*
     Skip the URL parse entirely when the raw request URL has no query —
@@ -99,9 +103,7 @@ export async function parseArgs(
                        OpenAPI SDK) omits it and sends ordinary JSON — read with plain
                        JSON.parse, since the ref-json envelope is ambiguous with a 2-element
                        array body. */
-                    body = bounded.headers.has(REF_JSON_HEADER)
-                        ? decodeRefJson(text)
-                        : JSON.parse(text)
+                    body = decodeWireBody(text, bounded.headers.has(REF_JSON_HEADER))
                 }
             } else if (
                 contentType.includes('application/x-www-form-urlencoded') ||
@@ -122,24 +124,121 @@ export async function parseArgs(
     }
 
     if (!url) {
-        /* `body` is undefined or a plain object here — return it as-is. */
+        /* `body` is undefined or a plain object here. A form-encoded body arrives stringly, so
+           coerce its numeric/boolean fields (a JSON body's values are already typed — non-strings
+           the coercion leaves untouched). */
+        if (body !== undefined && coerce !== undefined) {
+            applyCoercion(body as Record<string, unknown>, coerce)
+        }
         return body
     }
 
     /*
-    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 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 rpc).
+    Query params (and form-encoded body fields) arrive as strings, so a numeric/boolean field
+    would reach schema validation as `'2'`/`'true'`. `coerce` (ADR-0028) is the build-time plan
+    of exactly which fields are numeric/boolean in the endpoint's `Args` type — resolved through
+    the warm server program, so a string-typed field that merely looks numeric (an id, a zip code,
+    `'1.0'`) is never listed and stays a string. Applied to the merged bag below; a JSON body's
+    already-typed values are non-strings the coercion skips.
     */
     const bodyObject = (body ?? {}) as Record<string, unknown>
-    const merged = { ...Object.fromEntries(url.searchParams), ...bodyObject }
+    /* Collect the query into an object, arraying repeated keys (`?tag=a&tag=b` → `['a','b']`)
+       rather than letting `Object.fromEntries` silently keep only the last — mirrors
+       splitFormData, so a repeated field reaches the schema as an array, not a dropped value. */
+    const queryObject: Record<string, unknown> = {}
+    for (const [key, value] of url.searchParams) {
+        const existing = queryObject[key]
+        if (!(key in queryObject)) {
+            queryObject[key] = value
+        } else if (Array.isArray(existing)) {
+            existing.push(value)
+        } else {
+            queryObject[key] = [existing, value]
+        }
+    }
+    const merged = { ...queryObject, ...bodyObject }
     if (Object.keys(merged).length === 0) {
         return undefined
     }
+    if (coerce !== undefined) {
+        applyCoercion(merged, coerce)
+    }
     return merged
 }
+
+/*
+Revives the plain-JSON wire values in `args` into the runtime types the plan declares, in place
+(ADR-0028 scalars, ADR-0029 structured). The scalar kinds (number/boolean/date/bigint) touch
+strings only — a value the merge layered in from a typed JSON body is already the right type and
+left alone; a repeated key (`?tag=1&tag=2`) is an array whose string members revive per element.
+The container kinds (set/map) build from a JSON array (or object) but pass an already-typed value
+(from the abide client's ref-json body) through untouched. Every branch is fail-open: an
+unrevivable value stays its JSON form so the schema surfaces an honest issue rather than a throw.
+*/
+function applyCoercion(args: Record<string, unknown>, coerce: InputCoercion): void {
+    for (const key in coerce) {
+        const kind = coerce[key]
+        if (kind === undefined || !(key in args)) {
+            continue
+        }
+        args[key] = reviveValue(args[key], kind)
+    }
+}
+
+/* One field's wire value → its runtime type per `kind`, fail-open. The container kinds wrap a JSON
+   array/object; the scalar kinds revive a string (or each string in a repeated-key array). An
+   already-typed value (Set/Map/Date/bigint from the abide ref-json body) passes through. */
+function reviveValue(value: unknown, kind: WireKind): unknown {
+    /* Container kinds (set/map) decode through the shared wire codec; the input side additionally
+       accepts a plain object as Map entries — a query/form body can't send a JSON entries array
+       (ADR-0029 defers descending into array MEMBERS). */
+    if (kind === 'set' || kind === 'map') {
+        if (
+            kind === 'map' &&
+            !(value instanceof Map) &&
+            !Array.isArray(value) &&
+            value !== null &&
+            typeof value === 'object'
+        ) {
+            return new Map(Object.entries(value))
+        }
+        return reviveWireField(value, kind)
+    }
+    /* Scalar kinds (number/boolean/date/bigint): query/form values arrive as strings — a lone
+       value, or each string in a repeated-key array. */
+    if (typeof value === 'string') {
+        return reviveScalar(value, kind)
+    }
+    if (Array.isArray(value)) {
+        return value.map((element) =>
+            typeof element === 'string' ? reviveScalar(element, kind) : element,
+        )
+    }
+    return value
+}
+
+/* One string → its number/boolean/date/bigint value, or the original string when it doesn't parse
+   cleanly (empty/whitespace, `NaN`, a non-`true`/`false` boolean, an unparseable date, a
+   non-integer bigint), so a bad value fails validation with the field intact instead of coercing
+   to `0`/`NaN`/`Invalid Date`. */
+function reviveScalar(value: string, kind: WireKind): unknown {
+    if (kind === 'number') {
+        if (value.trim() === '') {
+            return value
+        }
+        const parsed = Number(value)
+        return Number.isNaN(parsed) ? value : parsed
+    }
+    if (kind === 'boolean') {
+        if (value === 'true') {
+            return true
+        }
+        if (value === 'false') {
+            return false
+        }
+        return value
+    }
+    /* date/bigint from a query/form string decode identically to the shared wire codec (ISO
+       string → Date, digit string → bigint), fail-open. */
+    return reviveWireField(value, kind)
+}

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

@@ -0,0 +1,28 @@
+import { jsonSchemaForSchema } from '../../shared/jsonSchemaForSchema.ts'
+import type { RpcRegistryEntry } from './types/RpcRegistryEntry.ts'
+
+/*
+The ONE resolution every surface (MCP tools, OpenAPI, the inspector catalog, and the
+standalone CLI manifest) uses for an rpc's advertised INPUT shape: a declared
+`inputSchema` VALIDATOR overrides the build-projected `inputJsonSchema` (ADR-0030 input
+side); with neither, `undefined`. Callers that need a non-empty schema apply the opaque
+`?? jsonSchemaForSchema(undefined)` fallback themselves (MCP/OpenAPI/CLI want it; the
+inspector leaves it undefined). One origin so the surfaces can't drift — the CLI manifest
+emitter previously read only `inputSchema` and silently dropped every plainly-typed
+handler's projected shape (no typed flags, no `--help`, array flags overwriting).
+*/
+export function resolveInputJsonSchema(
+    entry: RpcRegistryEntry,
+): Record<string, unknown> | undefined {
+    return entry.inputSchema ? jsonSchemaForSchema(entry.inputSchema) : entry.inputJsonSchema
+}
+
+/*
+The output analog: an `outputSchema` VALIDATOR overrides the projected `outputJsonSchema`;
+with neither, `undefined` (no output shape advertised — every surface leaves it off).
+*/
+export function resolveOutputJsonSchema(
+    entry: RpcRegistryEntry,
+): Record<string, unknown> | undefined {
+    return entry.outputSchema ? jsonSchemaForSchema(entry.outputSchema) : entry.outputJsonSchema
+}

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

@@ -1,3 +1,4 @@
+import { abideLog } from '../../shared/abideLog.ts'
 import { error } from '../error.ts'
 
 /*
@@ -39,7 +40,17 @@ export function runWithRpcTimeout(
                     (late) => {
                         void late.body?.cancel()
                     },
-                    () => {},
+                    (rejection) => {
+                        /* The handler outlived its timeout and then rejected. A cooperative
+                           abort (it honoured the composed signal) is expected and stays quiet;
+                           any other error is a genuine handler bug and would otherwise leave
+                           zero server-side trace behind the client's 504 — log it. */
+                        const aborted =
+                            (rejection as { name?: string } | undefined)?.name === 'AbortError'
+                        if (!aborted) {
+                            abideLog.error(rejection)
+                        }
+                    },
                 )
             }
         }

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

@@ -1,7 +1,9 @@
+import type { CachePolicy } from '../../../shared/types/CachePolicy.ts'
 import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
 import type { ErrorSpec } from '../../../shared/types/ErrorSpec.ts'
 import type { RemoteFunction } from '../../../shared/types/RemoteFunction.ts'
 import type { StandardSchemaV1 } from '../../../shared/types/StandardSchemaV1.ts'
+import type { StreamPolicy } from '../../../shared/types/StreamPolicy.ts'
 import type { TypedError } from './TypedError.ts'
 import type { TypedResponse } from './TypedResponse.ts'
 
@@ -49,25 +51,39 @@ type RpcArgs<F extends RpcFn> = Parameters<F> extends [infer Args, ...unknown[]]
 The RemoteFunction a bare overload produces from handler `F`. `SuccessBody`/`InferredErrors`
 run over `Awaited<ReturnType<F>>` INLINE (not via an intermediate `extends RpcFn`-constrained
 alias) — such an alias resolves `ReturnType` against the constraint bound and degrades the
-body to `any`. `Durable` threads the outbox bit through for the durable overloads.
+body to `any`.
 */
-type RpcOf<F extends RpcFn, Durable extends boolean = false> = RemoteFunction<
+type RpcOf<F extends RpcFn> = RemoteFunction<
     RpcArgs<F>,
     SuccessBody<Awaited<ReturnType<F>>>,
-    InferredErrors<Awaited<ReturnType<F>>>,
-    Durable
+    InferredErrors<Awaited<ReturnType<F>>>
 >
 
 /*
-Options every rpc overload accepts: the OpenAPI 200 `outputSchema`, the
-`clients` surface flags, the same-origin CSRF exemption (`crossOrigin`), the
-pre-parse body-byte ceiling (`maxBodySize`), and the per-surface handler
-`timeout` (ms). The schema-bearing overloads intersect this with their own
-`inputSchema`/`filesSchema` members. Mutating helpers widen it with `outbox`
-(see MutatingRpcOpts) — a read RPC never accepts it.
+The schema namespace (ADR-0020): `schemas: { input?, output?, files? }` replaces the
+flat `inputSchema`/`outputSchema`/`filesSchema`. `input` drives the handler's arg type,
+`output` is the success-body schema (OpenAPI 200 / MCP outputSchema — never drives arg
+inference), `files` validates multipart File parts. The schema-bearing helper overloads
+tighten specific members to required.
 */
-type RpcBaseOpts = {
-    outputSchema?: StandardSchemaV1
+type RpcSchemas = {
+    input?: StandardSchemaV1
+    output?: StandardSchemaV1
+    files?: StandardSchemaV1
+}
+
+/*
+Options every rpc overload accepts: the `schemas` namespace, the `clients` surface
+flags (browser/mcp/cli), the same-origin
+CSRF exemption (`crossOrigin`), the pre-parse body-byte ceiling
+(`maxBodySize`), and the per-surface handler `timeout` (ms). Read helpers add the
+endpoint `cache`/`stream` policy (ADR-0020); mutating helpers add neither — a write has
+no replayable value to retain or stream. The kind-scoping is what makes `POST(fn, { cache })`
+a compile error rather than a silent no-op. The single canonical source both `defineRpc`
+and `RpcRegistryEntry` project from.
+*/
+type RpcSharedOpts = {
+    schemas?: RpcSchemas
     clients?: Partial<ClientFlags>
     crossOrigin?: boolean
     maxBodySize?: number
@@ -75,63 +91,38 @@ type RpcBaseOpts = {
 }
 
 /*
-Mutating-helper options: the shared base plus durable delivery. `outbox` lives
-here, not on RpcBaseOpts, because a read RPC has nothing to durably deliver —
-so `GET(fn, { outbox: true })` is a compile error, not the runtime throw it used
-to be. Keeps the type surface honest with the defineRpc guard.
+Read-helper (GET/HEAD) options: the shared base plus the endpoint `cache` policy
+(`ttl`/`tags`/`throttle`/`debounce`/`shared`) and `stream` policy (`n`, replay depth).
+Generic over `Args` so `cache.tags`'s `(args) => string[]` form is typed against the
+rpc's own argument shape.
 */
-type MutatingRpcOpts = RpcBaseOpts & {
-    /* Durable delivery: on an unreachable server the call still throws, and the request is
-       parked for replay. Drains on `rpc.outbox.retry()` — no auto-drain. The call shape is
-       unchanged — `rpc.outbox` exposes the queue. */
-    outbox?: boolean
+type RpcReadOpts<Args> = RpcSharedOpts & {
+    cache?: CachePolicy<Args>
+    stream?: StreamPolicy
 }
 
 /*
-Shared signature for every rpc helper (GET / POST / …). The handler's return
-type is inferred whole (`Awaited<ReturnType<F>>`), then split: `SuccessBody`
-becomes the caller's `Return`, `InferredErrors` becomes the rpc's `Errors`
-(driving `isError`). Typed errors are raised by returning an
-`error.typed(name, status, schema?)` constructor — there is no `errors:` opt.
-Four overloads by argument source:
+The read helpers (GET/HEAD). The handler's return type is inferred whole
+(`Awaited<ReturnType<F>>`), then split: `SuccessBody` becomes the caller's `Return`,
+`InferredErrors` becomes the rpc's `Errors` (driving `isError`). Typed errors are raised
+by returning an `error.typed(name, status, schema?)` constructor — there is no `errors:`
+opt. Four overloads by argument source (most-specific first):
 
-  - `Rpc(fn, { inputSchema, outputSchema?, clients? })` — `Args` infers
-    from `InferInput<InputSchema>`, the handler receives
-    `InferOutput<InputSchema>`. `outputSchema` is an optional Standard Schema
-    for the success body — it feeds the OpenAPI 200 response and the MCP tool
-    `outputSchema`. JSON Schema is projected from each schema's own
-    `toJSONSchema()` (wrap with withJsonSchema if the library lacks one).
-    `clients` controls which surfaces (browser / mcp / cli) expose this rpc.
-    `crossOrigin: true` exempts a mutating rpc from the router's same-origin
-    CSRF gate — by default a browser request whose Origin doesn't match the
-    app's own host is refused with 403 on every non-GET/HEAD rpc.
-    `maxBodySize` caps the body's actual received bytes (413 past it),
-    enforced before parsing; omitted, the only ceiling is Bun.serve's
-    server-wide maxRequestBodySize. `timeout` (ms) bounds the handler's
-    execution on every surface (SSR / MCP / CLI / network) — a 504 once
-    exceeded; on the network path it also aborts request().signal so a
-    handler's `fetch(ext, { signal: request().signal })` is cancelled, not
-    just abandoned.
-  - `Rpc(fn, { clients })` — schemaless but with explicit client
-    targeting (e.g. server-internal RPC with `clients: { browser: false }`).
-  - `Rpc(fn)` — bare handler, a single `F extends RpcFn` generic. Everything
-    is read off the handler: `Args` from its parameter (annotate it —
-    `POST((a: { id: string }) => …)` — or leave it nullary for `undefined`),
-    `Return` from the `TypedResponse<T>` brand on
-    `json`/`error`/`redirect`/`jsonl`/`sse`, `Errors` from any
-    `error.typed(...)` branches. You never pass `<Args, Return>` generics; a
-    stray one is a loud constraint error, not a silent `unknown` body.
+  - `GET(fn, { schemas: { input, files, output? }, cache?, … })` — multipart upload.
+    The handler receives the text fields (`InferOutput<input>`) intersected with the
+    validated File parts (`InferOutput<files>`); the call site sends a FormData. `files`
+    stays off the JSON-Schema projection (a File has no honest conversion) — only `input`
+    feeds MCP/CLI/OpenAPI. `Args` (the RemoteFunction's call type) is `InferInput<input>`.
+  - `GET(fn, { schemas: { input, output? }, cache?, … })` — `Args` = `InferInput<input>`,
+    the handler receives `InferOutput<input>`. `output` feeds the OpenAPI 200 / MCP tool
+    outputSchema and never drives arg inference.
+  - `GET(fn, opts)` — schemaless-with-opts (includes `schemas: { output }`-only): args
+    read off the handler `F`. `cache`/`clients`/`timeout`/… live here.
+  - `GET(fn)` — bare handler; everything reads off `F`: `Args` from its parameter, `Return`
+    from the `TypedResponse<T>` brand, `Errors` from any `error.typed(...)` branches. You
+    never pass `<Args, Return>` generics; a stray one is a loud constraint error.
 */
-type RpcHelperOf<Opts> = {
-    /*
-    `Rpc(fn, { inputSchema, filesSchema, … })` — multipart upload. The
-    handler receives the text fields (`InferOutput<InputSchema>`) intersected
-    with the validated File parts (`InferOutput<FilesSchema>`); both are merged
-    into one args bag. The call site sends a FormData (RemoteFunction's call
-    accepts it), since a File can't ride a JSON body. filesSchema stays off the
-    JSON-Schema projection — a File has no honest conversion (see
-    jsonSchemaForSchema) — so only inputSchema feeds MCP/CLI/OpenAPI.
-    */
+export type RpcHelper = {
     <
         R extends Response,
         InputSchema extends StandardSchemaV1 = StandardSchemaV1,
@@ -141,30 +132,28 @@ type RpcHelperOf<Opts> = {
             args: StandardSchemaV1.InferOutput<InputSchema> &
                 StandardSchemaV1.InferOutput<FilesSchema>,
         ) => R | Promise<R>,
-        opts: Opts & {
-            inputSchema: InputSchema
-            filesSchema: FilesSchema
+        opts: RpcReadOpts<StandardSchemaV1.InferInput<InputSchema>> & {
+            schemas: { input: InputSchema; files: FilesSchema; output?: StandardSchemaV1 }
         },
     ): RemoteFunction<StandardSchemaV1.InferInput<InputSchema>, SuccessBody<R>, InferredErrors<R>>
     <R extends Response, InputSchema extends StandardSchemaV1 = StandardSchemaV1>(
         fn: (args: StandardSchemaV1.InferOutput<InputSchema>) => R | Promise<R>,
-        opts: Opts & { inputSchema: InputSchema },
+        opts: RpcReadOpts<StandardSchemaV1.InferInput<InputSchema>> & {
+            schemas: { input: InputSchema; output?: StandardSchemaV1 }
+        },
     ): RemoteFunction<StandardSchemaV1.InferInput<InputSchema>, SuccessBody<R>, InferredErrors<R>>
-    <F extends RpcFn>(fn: F, opts: Opts): RpcOf<F>
+    <F extends RpcFn>(fn: F, opts: RpcReadOpts<RpcArgs<F>>): RpcOf<F>
     <F extends RpcFn>(fn: F): RpcOf<F>
 }
 
-/* The read helpers (GET/HEAD): no `outbox` — a read has nothing to durably deliver. */
-export type RpcHelper = RpcHelperOf<RpcBaseOpts>
-
 /*
-Durable-call overloads: an `outbox: true` opt returns a RemoteFunction whose `Durable` bit
-is set, so `rpc.outbox` is the queue face rather than optionally-undefined. Mirrors the
-opts-bearing base overloads (multipart-upload, schema'd, schemaless); the bare `Rpc(fn)`
-form has no opts to carry `outbox`, so it stays non-durable. Intersected AHEAD of the base
-set in MutatingRpcHelper so an `outbox: true` literal resolves here first.
+The mutating helpers (POST/PUT/PATCH/DELETE). The base opts is the shared `RpcSharedOpts`
+(no `cache`/`stream`) — coalesce-only is the method default and a write has no replayable
+value to retain or stream — which is what makes `cache`/`stream` a compile error here while
+they stay legal on the read helpers (`RpcReadOpts`) — the kind-scoping. Overloads mirror the read helpers by argument source
+(multipart-upload, schema'd, schemaless-with-opts, bare).
 */
-type DurableMutatingRpcHelper = {
+export type MutatingRpcHelper = {
     <
         R extends Response,
         InputSchema extends StandardSchemaV1 = StandardSchemaV1,
@@ -174,35 +163,16 @@ type DurableMutatingRpcHelper = {
             args: StandardSchemaV1.InferOutput<InputSchema> &
                 StandardSchemaV1.InferOutput<FilesSchema>,
         ) => R | Promise<R>,
-        opts: MutatingRpcOpts & {
-            inputSchema: InputSchema
-            filesSchema: FilesSchema
-            outbox: true
+        opts: RpcSharedOpts & {
+            schemas: { input: InputSchema; files: FilesSchema; output?: StandardSchemaV1 }
         },
-    ): RemoteFunction<
-        StandardSchemaV1.InferInput<InputSchema>,
-        SuccessBody<R>,
-        InferredErrors<R>,
-        true
-    >
+    ): RemoteFunction<StandardSchemaV1.InferInput<InputSchema>, SuccessBody<R>, InferredErrors<R>>
     <R extends Response, InputSchema extends StandardSchemaV1 = StandardSchemaV1>(
         fn: (args: StandardSchemaV1.InferOutput<InputSchema>) => R | Promise<R>,
-        opts: MutatingRpcOpts & { inputSchema: InputSchema; outbox: true },
-    ): RemoteFunction<
-        StandardSchemaV1.InferInput<InputSchema>,
-        SuccessBody<R>,
-        InferredErrors<R>,
-        true
-    >
-    <F extends RpcFn>(fn: F, opts: MutatingRpcOpts & { outbox: true }): RpcOf<F, true>
+        opts: RpcSharedOpts & {
+            schemas: { input: InputSchema; output?: StandardSchemaV1 }
+        },
+    ): RemoteFunction<StandardSchemaV1.InferInput<InputSchema>, SuccessBody<R>, InferredErrors<R>>
+    <F extends RpcFn>(fn: F, opts: RpcSharedOpts): RpcOf<F>
+    <F extends RpcFn>(fn: F): RpcOf<F>
 }
-
-/*
-The mutating helpers (POST/PUT/PATCH/DELETE). A durable (`outbox`) call is a normal
-RemoteFunction — it throws exactly like a non-durable one and only parks the request as a
-side-effect on an unreachable server — so there is no separate return shape; `outbox` rides
-MutatingRpcOpts and `rpc.outbox` exposes the queue. The distinct opts base is what makes
-`outbox` legal here and a compile error on the read helpers; the durable overloads then set
-the return type's `Durable` bit so `rpc.outbox` is present without an optional chain.
-*/
-export type MutatingRpcHelper = DurableMutatingRpcHelper & RpcHelperOf<MutatingRpcOpts>