@mandujs/core 0.53.3 → 0.54.1

package/src/contract/rpc.ts

@@ -1,443 +1,443 @@
-/**
- * Mandu Typed RPC — Server Side
- *
- * tRPC-like end-to-end typed RPC built on Mandu's existing contract +
- * client layer. No external tRPC dependency. Zod contracts on the
- * server flow through to auto-typed client proxies.
- *
- * Phase 18.κ — see `docs/architect/typed-rpc.md` for the comparison
- * against tRPC / SvelteKit form actions / Next.js server actions plus
- * the migration recipe.
- *
- * @module
- */
-
-import type { z } from "zod";
-
-// ========== Types ==========
-
-/**
- * Per-procedure call context.
- *
- * `input` is the Zod-parsed, validated request body (or `undefined`
- * when the procedure declares no `input` schema). `request` is the
- * raw Fetch `Request` so procedures can read cookies / headers. `ctx`
- * is a free-form object threaded from the dispatcher — Phase 18.κ
- * ships an empty object by default; session / DB / user wiring is
- * layered on via `ManduConfig.rpc.context` in a future patch.
- */
-export interface RpcContext<TInput = unknown, TCtx = Record<string, unknown>> {
-  /** Validated input (parsed by the procedure's `input` Zod schema). */
-  input: TInput;
-  /** Raw Fetch Request — cookies / headers / auth state. */
-  request: Request;
-  /** Per-request context (session, db, user, …). */
-  ctx: TCtx;
-}
-
-/**
- * A single RPC procedure definition.
- *
- * Each procedure pairs an `input` schema (optional — allow
- * parameter-less RPCs), an `output` schema (required — the contract
- * guarantee), and a `handler` function. `handler` receives the
- * validated input + the raw Request + a shared context object and
- * returns the output shape; the dispatcher validates the return
- * value against `output` before shipping.
- */
-export interface RpcProcedure<
-  TInputSchema extends z.ZodTypeAny | undefined = z.ZodTypeAny | undefined,
-  TOutputSchema extends z.ZodTypeAny = z.ZodTypeAny,
-  TCtx extends Record<string, unknown> = Record<string, unknown>,
-> {
-  /** Zod schema for procedure input. `undefined` for no-arg procedures. */
-  input?: TInputSchema;
-  /** Zod schema for the return value (response body). */
-  output: TOutputSchema;
-  /** Procedure body. Receives validated input + request + shared ctx. */
-  handler: (
-    args: RpcContext<
-      TInputSchema extends z.ZodTypeAny ? z.infer<TInputSchema> : undefined,
-      TCtx
-    >
-  ) => Promise<z.infer<TOutputSchema>> | z.infer<TOutputSchema>;
-}
-
-/** Record of procedures — the raw user input to {@link defineRpc}. */
-export type RpcProcedureRecord = Record<
-  string,
-  RpcProcedure<z.ZodTypeAny | undefined, z.ZodTypeAny>
->;
-
-/**
- * Tagged RPC definition — the return value of {@link defineRpc}.
- *
- * The `__rpc` brand lets the client proxy and the route dispatcher
- * distinguish RPC definitions from plain contract objects without
- * reaching for `instanceof`.
- */
-export interface RpcDefinition<TProcedures extends RpcProcedureRecord = RpcProcedureRecord> {
-  /** The raw procedure record (used by both server dispatch and client proxy). */
-  procedures: TProcedures;
-  /** Brand — distinguishes RPC defs from contract objects. */
-  readonly __rpc: true;
-}
-
-/**
- * Client-facing type derived from a {@link RpcDefinition}.
- *
- * Maps each procedure key to a function whose argument is the Zod
- * input type (or `undefined`/no-arg for procedures without input)
- * and whose return is `Promise<Output>`. Used by
- * `createRpcClient<typeof postsRpc>()`.
- */
-export type RpcClient<TDef extends RpcDefinition<RpcProcedureRecord>> = {
-  [K in keyof TDef["procedures"]]: TDef["procedures"][K]["input"] extends z.ZodTypeAny
-    ? (input: z.infer<TDef["procedures"][K]["input"]>) => Promise<z.infer<TDef["procedures"][K]["output"]>>
-    : (input?: undefined) => Promise<z.infer<TDef["procedures"][K]["output"]>>;
-};
-
-// ========== Core API ==========
-
-/**
- * Define a tRPC-style typed RPC module.
- *
- * @example
- * ```ts
- * import { z } from "zod";
- * import { defineRpc } from "@mandujs/core/contract/rpc";
- *
- * export const postsRpc = defineRpc({
- *   list: {
- *     input: z.object({ limit: z.number().optional() }).optional(),
- *     output: z.array(z.object({ id: z.string(), title: z.string() })),
- *     handler: async ({ input }) => db.posts.findMany({ limit: input?.limit ?? 10 }),
- *   },
- *   get: {
- *     input: z.object({ id: z.string() }),
- *     output: z.object({ id: z.string(), title: z.string(), body: z.string() }),
- *     handler: async ({ input }) => db.posts.findUnique({ where: { id: input.id } }),
- *   },
- * });
- * ```
- *
- * Wire to a server by passing to {@link registerRpc} (or via
- * `ManduConfig.rpc.endpoints`). Requests resolve to
- * `POST /api/rpc/<name>/<method>` where `<name>` is the endpoint key.
- */
-export function defineRpc<TProcedures extends RpcProcedureRecord>(
-  procedures: TProcedures
-): RpcDefinition<TProcedures> {
-  // Validate each procedure shape at define-time so a missing `output`
-  // or `handler` fails fast with a readable message instead of a
-  // runtime NPE inside the dispatcher.
-  for (const [key, proc] of Object.entries(procedures)) {
-    if (!proc || typeof proc !== "object") {
-      throw new Error(
-        `[Mandu RPC] Procedure "${key}" is not an object. Each procedure must be { input?, output, handler }.`
-      );
-    }
-    if (typeof proc.handler !== "function") {
-      throw new Error(
-        `[Mandu RPC] Procedure "${key}" is missing a handler function.`
-      );
-    }
-    if (!proc.output || typeof (proc.output as z.ZodTypeAny).safeParse !== "function") {
-      throw new Error(
-        `[Mandu RPC] Procedure "${key}" is missing an output Zod schema.`
-      );
-    }
-    if (proc.input !== undefined && typeof (proc.input as z.ZodTypeAny).safeParse !== "function") {
-      throw new Error(
-        `[Mandu RPC] Procedure "${key}" has an invalid input schema (not a Zod type).`
-      );
-    }
-  }
-
-  return {
-    procedures,
-    __rpc: true,
-  };
-}
-
-// ========== Registry ==========
-
-/**
- * Global RPC endpoint registry.
- *
- * Keyed by endpoint name (the `<name>` in `/api/rpc/<name>/<method>`).
- * Populated by {@link registerRpc} (typically at boot via
- * `ManduConfig.rpc.endpoints`) and consumed by the dispatcher in
- * `runtime/server.ts`.
- */
-const rpcRegistry = new Map<string, RpcDefinition<RpcProcedureRecord>>();
-
-/**
- * Register an RPC endpoint under `name`.
- *
- * Same name twice overwrites (HMR-friendly). Pass `null` / `undefined`
- * to clear a registration. Typically called automatically from
- * `startServer` when `ManduConfig.rpc.endpoints` is set, but public
- * so user code can register additional endpoints at runtime.
- */
-export function registerRpc(
-  name: string,
-  definition: RpcDefinition<RpcProcedureRecord>
-): void {
-  if (!definition?.__rpc) {
-    throw new Error(
-      `[Mandu RPC] registerRpc("${name}", …) expected a defineRpc() result, got ${typeof definition}.`
-    );
-  }
-  rpcRegistry.set(name, definition);
-}
-
-/** Look up an RPC endpoint by name. Returns `undefined` on miss. */
-export function getRpc(name: string): RpcDefinition<RpcProcedureRecord> | undefined {
-  return rpcRegistry.get(name);
-}
-
-/** Clear all RPC registrations (test helper). */
-export function clearRpcRegistry(): void {
-  rpcRegistry.clear();
-}
-
-/** Enumerate registered endpoint names. */
-export function listRpcEndpoints(): string[] {
-  return Array.from(rpcRegistry.keys());
-}
-
-// ========== Dispatch ==========
-
-/**
- * Shape of the JSON envelope that flows over the wire.
- *
- * Mirrors {@link RpcWireError} for the failure case — the client
- * proxy inspects `ok` and unwraps `data` or throws {@link RpcCallError}.
- */
-export type RpcWireEnvelope<T = unknown> =
-  | { ok: true; data: T }
-  | { ok: false; error: RpcWireError };
-
-export interface RpcWireError {
-  /** Machine-readable code: `INPUT_INVALID` | `OUTPUT_INVALID` | `NOT_FOUND` | `HANDLER_ERROR` | `METHOD_NOT_ALLOWED` | `BAD_JSON`. */
-  code: string;
-  /** Human-readable message (generic in prod, full in dev). */
-  message: string;
-  /** Optional field-level issues for `INPUT_INVALID` / `OUTPUT_INVALID`. */
-  issues?: Array<{ path: (string | number)[]; message: string; code?: string }>;
-}
-
-/**
- * Match `/api/rpc/<name>/<method>` — the canonical RPC URL shape.
- * Returns `null` for any path that is not an RPC call, so the
- * dispatcher can fall through to the normal route matcher.
- *
- * `<name>` and `<method>` are restricted to `[A-Za-z0-9_-]+` to
- * prevent path-traversal style abuse of the lookup key.
- */
-export function matchRpcPath(
-  pathname: string
-): { endpoint: string; method: string } | null {
-  if (!pathname.startsWith("/api/rpc/")) return null;
-  const rest = pathname.slice("/api/rpc/".length);
-  // Only two non-empty segments; reject nested paths.
-  const parts = rest.split("/");
-  if (parts.length !== 2) return null;
-  const [endpoint, method] = parts;
-  if (!endpoint || !method) return null;
-  if (!/^[A-Za-z0-9_-]+$/.test(endpoint)) return null;
-  if (!/^[A-Za-z0-9_-]+$/.test(method)) return null;
-  return { endpoint, method };
-}
-
-/**
- * Serialize a Zod error to the wire-level `issues` array.
- */
-function zodIssues(err: z.ZodError): RpcWireError["issues"] {
-  return err.errors.map((iss) => ({
-    path: iss.path,
-    message: iss.message,
-    code: iss.code,
-  }));
-}
-
-function jsonResponse(envelope: RpcWireEnvelope, status: number): Response {
-  return new Response(JSON.stringify(envelope), {
-    status,
-    headers: { "Content-Type": "application/json; charset=utf-8" },
-  });
-}
-
-/**
- * Dispatch an RPC call.
- *
- * Handles (in order): method gate (POST only), endpoint lookup,
- * procedure lookup, input parse + validate, handler invocation,
- * output validate, response shaping. Every failure path returns a
- * structured {@link RpcWireEnvelope} — callers do not throw.
- *
- * `isDev` toggles whether handler errors include the raw message +
- * stack. In prod (`isDev === false`) we return a generic
- * `"Internal RPC error"` to avoid leaking stack frames.
- */
-export async function dispatchRpc(
-  req: Request,
-  endpoint: string,
-  method: string,
-  options: { isDev?: boolean; ctx?: Record<string, unknown> } = {}
-): Promise<Response> {
-  const isDev = options.isDev ?? false;
-  const sharedCtx = options.ctx ?? {};
-
-  if (req.method !== "POST") {
-    return jsonResponse(
-      {
-        ok: false,
-        error: {
-          code: "METHOD_NOT_ALLOWED",
-          message: `RPC endpoints accept POST only (got ${req.method}).`,
-        },
-      },
-      405
-    );
-  }
-
-  const definition = rpcRegistry.get(endpoint);
-  if (!definition) {
-    return jsonResponse(
-      {
-        ok: false,
-        error: {
-          code: "NOT_FOUND",
-          message: `Unknown RPC endpoint "${endpoint}".`,
-        },
-      },
-      404
-    );
-  }
-
-  const procedure = definition.procedures[method];
-  if (!procedure) {
-    return jsonResponse(
-      {
-        ok: false,
-        error: {
-          code: "NOT_FOUND",
-          message: `RPC endpoint "${endpoint}" has no procedure "${method}".`,
-        },
-      },
-      404
-    );
-  }
-
-  // ---- Parse body ----
-  let rawBody: unknown = undefined;
-  const contentLength = req.headers.get("content-length");
-  const hasBody = contentLength !== "0" && req.headers.get("content-type")?.includes("application/json");
-  if (hasBody) {
-    try {
-      const text = await req.text();
-      if (text.length > 0) {
-        rawBody = JSON.parse(text);
-      }
-    } catch (err) {
-      return jsonResponse(
-        {
-          ok: false,
-          error: {
-            code: "BAD_JSON",
-            message: `Request body is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
-          },
-        },
-        400
-      );
-    }
-  }
-
-  // Wire envelope: { input: <value> } — matches createRpcClient output.
-  const rawInput = rawBody && typeof rawBody === "object" && rawBody !== null && "input" in rawBody
-    ? (rawBody as { input: unknown }).input
-    : rawBody;
-
-  // ---- Validate input ----
-  let parsedInput: unknown = undefined;
-  if (procedure.input) {
-    const result = procedure.input.safeParse(rawInput);
-    if (!result.success) {
-      return jsonResponse(
-        {
-          ok: false,
-          error: {
-            code: "INPUT_INVALID",
-            message: "Input failed schema validation.",
-            issues: zodIssues(result.error),
-          },
-        },
-        400
-      );
-    }
-    parsedInput = result.data;
-  }
-
-  // ---- Invoke handler ----
-  let handlerResult: unknown;
-  try {
-    handlerResult = await procedure.handler({
-      input: parsedInput as never,
-      request: req,
-      ctx: sharedCtx,
-    });
-  } catch (err) {
-    const message =
-      isDev && err instanceof Error
-        ? err.message
-        : "Internal RPC error";
-    if (isDev) {
-      // Dev mode: surface the stack on the server console so the
-      // user can debug without peering at network tab payloads.
-      console.error(
-        `[Mandu RPC] handler error in ${endpoint}.${method}:`,
-        err
-      );
-    }
-    return jsonResponse(
-      {
-        ok: false,
-        error: {
-          code: "HANDLER_ERROR",
-          message,
-        },
-      },
-      500
-    );
-  }
-
-  // ---- Validate output ----
-  const outResult = procedure.output.safeParse(handlerResult);
-  if (!outResult.success) {
-    // Output-schema mismatch is a programmer bug (server returned
-    // wrong shape). Log loud in dev; return a generic 500 in prod.
-    if (isDev) {
-      console.error(
-        `[Mandu RPC] output validation failed in ${endpoint}.${method}:`,
-        outResult.error.errors
-      );
-    }
-    return jsonResponse(
-      {
-        ok: false,
-        error: {
-          code: "OUTPUT_INVALID",
-          message: isDev
-            ? "Handler returned a value that does not match the output schema."
-            : "Internal RPC error",
-          issues: isDev ? zodIssues(outResult.error) : undefined,
-        },
-      },
-      500
-    );
-  }
-
-  return jsonResponse({ ok: true, data: outResult.data }, 200);
-}
+/**
+ * Mandu Typed RPC — Server Side
+ *
+ * tRPC-like end-to-end typed RPC built on Mandu's existing contract +
+ * client layer. No external tRPC dependency. Zod contracts on the
+ * server flow through to auto-typed client proxies.
+ *
+ * Phase 18.κ — see `docs/architect/typed-rpc.md` for the comparison
+ * against tRPC / SvelteKit form actions / Next.js server actions plus
+ * the migration recipe.
+ *
+ * @module
+ */
+
+import type { z } from "zod";
+
+// ========== Types ==========
+
+/**
+ * Per-procedure call context.
+ *
+ * `input` is the Zod-parsed, validated request body (or `undefined`
+ * when the procedure declares no `input` schema). `request` is the
+ * raw Fetch `Request` so procedures can read cookies / headers. `ctx`
+ * is a free-form object threaded from the dispatcher — Phase 18.κ
+ * ships an empty object by default; session / DB / user wiring is
+ * layered on via `ManduConfig.rpc.context` in a future patch.
+ */
+export interface RpcContext<TInput = unknown, TCtx = Record<string, unknown>> {
+  /** Validated input (parsed by the procedure's `input` Zod schema). */
+  input: TInput;
+  /** Raw Fetch Request — cookies / headers / auth state. */
+  request: Request;
+  /** Per-request context (session, db, user, …). */
+  ctx: TCtx;
+}
+
+/**
+ * A single RPC procedure definition.
+ *
+ * Each procedure pairs an `input` schema (optional — allow
+ * parameter-less RPCs), an `output` schema (required — the contract
+ * guarantee), and a `handler` function. `handler` receives the
+ * validated input + the raw Request + a shared context object and
+ * returns the output shape; the dispatcher validates the return
+ * value against `output` before shipping.
+ */
+export interface RpcProcedure<
+  TInputSchema extends z.ZodTypeAny | undefined = z.ZodTypeAny | undefined,
+  TOutputSchema extends z.ZodTypeAny = z.ZodTypeAny,
+  TCtx extends Record<string, unknown> = Record<string, unknown>,
+> {
+  /** Zod schema for procedure input. `undefined` for no-arg procedures. */
+  input?: TInputSchema;
+  /** Zod schema for the return value (response body). */
+  output: TOutputSchema;
+  /** Procedure body. Receives validated input + request + shared ctx. */
+  handler: (
+    args: RpcContext<
+      TInputSchema extends z.ZodTypeAny ? z.infer<TInputSchema> : undefined,
+      TCtx
+    >
+  ) => Promise<z.infer<TOutputSchema>> | z.infer<TOutputSchema>;
+}
+
+/** Record of procedures — the raw user input to {@link defineRpc}. */
+export type RpcProcedureRecord = Record<
+  string,
+  RpcProcedure<z.ZodTypeAny | undefined, z.ZodTypeAny>
+>;
+
+/**
+ * Tagged RPC definition — the return value of {@link defineRpc}.
+ *
+ * The `__rpc` brand lets the client proxy and the route dispatcher
+ * distinguish RPC definitions from plain contract objects without
+ * reaching for `instanceof`.
+ */
+export interface RpcDefinition<TProcedures extends RpcProcedureRecord = RpcProcedureRecord> {
+  /** The raw procedure record (used by both server dispatch and client proxy). */
+  procedures: TProcedures;
+  /** Brand — distinguishes RPC defs from contract objects. */
+  readonly __rpc: true;
+}
+
+/**
+ * Client-facing type derived from a {@link RpcDefinition}.
+ *
+ * Maps each procedure key to a function whose argument is the Zod
+ * input type (or `undefined`/no-arg for procedures without input)
+ * and whose return is `Promise<Output>`. Used by
+ * `createRpcClient<typeof postsRpc>()`.
+ */
+export type RpcClient<TDef extends RpcDefinition<RpcProcedureRecord>> = {
+  [K in keyof TDef["procedures"]]: TDef["procedures"][K]["input"] extends z.ZodTypeAny
+    ? (input: z.infer<TDef["procedures"][K]["input"]>) => Promise<z.infer<TDef["procedures"][K]["output"]>>
+    : (input?: undefined) => Promise<z.infer<TDef["procedures"][K]["output"]>>;
+};
+
+// ========== Core API ==========
+
+/**
+ * Define a tRPC-style typed RPC module.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { defineRpc } from "@mandujs/core/contract/rpc";
+ *
+ * export const postsRpc = defineRpc({
+ *   list: {
+ *     input: z.object({ limit: z.number().optional() }).optional(),
+ *     output: z.array(z.object({ id: z.string(), title: z.string() })),
+ *     handler: async ({ input }) => db.posts.findMany({ limit: input?.limit ?? 10 }),
+ *   },
+ *   get: {
+ *     input: z.object({ id: z.string() }),
+ *     output: z.object({ id: z.string(), title: z.string(), body: z.string() }),
+ *     handler: async ({ input }) => db.posts.findUnique({ where: { id: input.id } }),
+ *   },
+ * });
+ * ```
+ *
+ * Wire to a server by passing to {@link registerRpc} (or via
+ * `ManduConfig.rpc.endpoints`). Requests resolve to
+ * `POST /api/rpc/<name>/<method>` where `<name>` is the endpoint key.
+ */
+export function defineRpc<TProcedures extends RpcProcedureRecord>(
+  procedures: TProcedures
+): RpcDefinition<TProcedures> {
+  // Validate each procedure shape at define-time so a missing `output`
+  // or `handler` fails fast with a readable message instead of a
+  // runtime NPE inside the dispatcher.
+  for (const [key, proc] of Object.entries(procedures)) {
+    if (!proc || typeof proc !== "object") {
+      throw new Error(
+        `[Mandu RPC] Procedure "${key}" is not an object. Each procedure must be { input?, output, handler }.`
+      );
+    }
+    if (typeof proc.handler !== "function") {
+      throw new Error(
+        `[Mandu RPC] Procedure "${key}" is missing a handler function.`
+      );
+    }
+    if (!proc.output || typeof (proc.output as z.ZodTypeAny).safeParse !== "function") {
+      throw new Error(
+        `[Mandu RPC] Procedure "${key}" is missing an output Zod schema.`
+      );
+    }
+    if (proc.input !== undefined && typeof (proc.input as z.ZodTypeAny).safeParse !== "function") {
+      throw new Error(
+        `[Mandu RPC] Procedure "${key}" has an invalid input schema (not a Zod type).`
+      );
+    }
+  }
+
+  return {
+    procedures,
+    __rpc: true,
+  };
+}
+
+// ========== Registry ==========
+
+/**
+ * Global RPC endpoint registry.
+ *
+ * Keyed by endpoint name (the `<name>` in `/api/rpc/<name>/<method>`).
+ * Populated by {@link registerRpc} (typically at boot via
+ * `ManduConfig.rpc.endpoints`) and consumed by the dispatcher in
+ * `runtime/server.ts`.
+ */
+const rpcRegistry = new Map<string, RpcDefinition<RpcProcedureRecord>>();
+
+/**
+ * Register an RPC endpoint under `name`.
+ *
+ * Same name twice overwrites (HMR-friendly). Pass `null` / `undefined`
+ * to clear a registration. Typically called automatically from
+ * `startServer` when `ManduConfig.rpc.endpoints` is set, but public
+ * so user code can register additional endpoints at runtime.
+ */
+export function registerRpc(
+  name: string,
+  definition: RpcDefinition<RpcProcedureRecord>
+): void {
+  if (!definition?.__rpc) {
+    throw new Error(
+      `[Mandu RPC] registerRpc("${name}", …) expected a defineRpc() result, got ${typeof definition}.`
+    );
+  }
+  rpcRegistry.set(name, definition);
+}
+
+/** Look up an RPC endpoint by name. Returns `undefined` on miss. */
+export function getRpc(name: string): RpcDefinition<RpcProcedureRecord> | undefined {
+  return rpcRegistry.get(name);
+}
+
+/** Clear all RPC registrations (test helper). */
+export function clearRpcRegistry(): void {
+  rpcRegistry.clear();
+}
+
+/** Enumerate registered endpoint names. */
+export function listRpcEndpoints(): string[] {
+  return Array.from(rpcRegistry.keys());
+}
+
+// ========== Dispatch ==========
+
+/**
+ * Shape of the JSON envelope that flows over the wire.
+ *
+ * Mirrors {@link RpcWireError} for the failure case — the client
+ * proxy inspects `ok` and unwraps `data` or throws {@link RpcCallError}.
+ */
+export type RpcWireEnvelope<T = unknown> =
+  | { ok: true; data: T }
+  | { ok: false; error: RpcWireError };
+
+export interface RpcWireError {
+  /** Machine-readable code: `INPUT_INVALID` | `OUTPUT_INVALID` | `NOT_FOUND` | `HANDLER_ERROR` | `METHOD_NOT_ALLOWED` | `BAD_JSON`. */
+  code: string;
+  /** Human-readable message (generic in prod, full in dev). */
+  message: string;
+  /** Optional field-level issues for `INPUT_INVALID` / `OUTPUT_INVALID`. */
+  issues?: Array<{ path: (string | number)[]; message: string; code?: string }>;
+}
+
+/**
+ * Match `/api/rpc/<name>/<method>` — the canonical RPC URL shape.
+ * Returns `null` for any path that is not an RPC call, so the
+ * dispatcher can fall through to the normal route matcher.
+ *
+ * `<name>` and `<method>` are restricted to `[A-Za-z0-9_-]+` to
+ * prevent path-traversal style abuse of the lookup key.
+ */
+export function matchRpcPath(
+  pathname: string
+): { endpoint: string; method: string } | null {
+  if (!pathname.startsWith("/api/rpc/")) return null;
+  const rest = pathname.slice("/api/rpc/".length);
+  // Only two non-empty segments; reject nested paths.
+  const parts = rest.split("/");
+  if (parts.length !== 2) return null;
+  const [endpoint, method] = parts;
+  if (!endpoint || !method) return null;
+  if (!/^[A-Za-z0-9_-]+$/.test(endpoint)) return null;
+  if (!/^[A-Za-z0-9_-]+$/.test(method)) return null;
+  return { endpoint, method };
+}
+
+/**
+ * Serialize a Zod error to the wire-level `issues` array.
+ */
+function zodIssues(err: z.ZodError): RpcWireError["issues"] {
+  return err.errors.map((iss) => ({
+    path: iss.path,
+    message: iss.message,
+    code: iss.code,
+  }));
+}
+
+function jsonResponse(envelope: RpcWireEnvelope, status: number): Response {
+  return new Response(JSON.stringify(envelope), {
+    status,
+    headers: { "Content-Type": "application/json; charset=utf-8" },
+  });
+}
+
+/**
+ * Dispatch an RPC call.
+ *
+ * Handles (in order): method gate (POST only), endpoint lookup,
+ * procedure lookup, input parse + validate, handler invocation,
+ * output validate, response shaping. Every failure path returns a
+ * structured {@link RpcWireEnvelope} — callers do not throw.
+ *
+ * `isDev` toggles whether handler errors include the raw message +
+ * stack. In prod (`isDev === false`) we return a generic
+ * `"Internal RPC error"` to avoid leaking stack frames.
+ */
+export async function dispatchRpc(
+  req: Request,
+  endpoint: string,
+  method: string,
+  options: { isDev?: boolean; ctx?: Record<string, unknown> } = {}
+): Promise<Response> {
+  const isDev = options.isDev ?? false;
+  const sharedCtx = options.ctx ?? {};
+
+  if (req.method !== "POST") {
+    return jsonResponse(
+      {
+        ok: false,
+        error: {
+          code: "METHOD_NOT_ALLOWED",
+          message: `RPC endpoints accept POST only (got ${req.method}).`,
+        },
+      },
+      405
+    );
+  }
+
+  const definition = rpcRegistry.get(endpoint);
+  if (!definition) {
+    return jsonResponse(
+      {
+        ok: false,
+        error: {
+          code: "NOT_FOUND",
+          message: `Unknown RPC endpoint "${endpoint}".`,
+        },
+      },
+      404
+    );
+  }
+
+  const procedure = definition.procedures[method];
+  if (!procedure) {
+    return jsonResponse(
+      {
+        ok: false,
+        error: {
+          code: "NOT_FOUND",
+          message: `RPC endpoint "${endpoint}" has no procedure "${method}".`,
+        },
+      },
+      404
+    );
+  }
+
+  // ---- Parse body ----
+  let rawBody: unknown = undefined;
+  const contentLength = req.headers.get("content-length");
+  const hasBody = contentLength !== "0" && req.headers.get("content-type")?.includes("application/json");
+  if (hasBody) {
+    try {
+      const text = await req.text();
+      if (text.length > 0) {
+        rawBody = JSON.parse(text);
+      }
+    } catch (err) {
+      return jsonResponse(
+        {
+          ok: false,
+          error: {
+            code: "BAD_JSON",
+            message: `Request body is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+          },
+        },
+        400
+      );
+    }
+  }
+
+  // Wire envelope: { input: <value> } — matches createRpcClient output.
+  const rawInput = rawBody && typeof rawBody === "object" && rawBody !== null && "input" in rawBody
+    ? (rawBody as { input: unknown }).input
+    : rawBody;
+
+  // ---- Validate input ----
+  let parsedInput: unknown = undefined;
+  if (procedure.input) {
+    const result = procedure.input.safeParse(rawInput);
+    if (!result.success) {
+      return jsonResponse(
+        {
+          ok: false,
+          error: {
+            code: "INPUT_INVALID",
+            message: "Input failed schema validation.",
+            issues: zodIssues(result.error),
+          },
+        },
+        400
+      );
+    }
+    parsedInput = result.data;
+  }
+
+  // ---- Invoke handler ----
+  let handlerResult: unknown;
+  try {
+    handlerResult = await procedure.handler({
+      input: parsedInput as never,
+      request: req,
+      ctx: sharedCtx,
+    });
+  } catch (err) {
+    const message =
+      isDev && err instanceof Error
+        ? err.message
+        : "Internal RPC error";
+    if (isDev) {
+      // Dev mode: surface the stack on the server console so the
+      // user can debug without peering at network tab payloads.
+      console.error(
+        `[Mandu RPC] handler error in ${endpoint}.${method}:`,
+        err
+      );
+    }
+    return jsonResponse(
+      {
+        ok: false,
+        error: {
+          code: "HANDLER_ERROR",
+          message,
+        },
+      },
+      500
+    );
+  }
+
+  // ---- Validate output ----
+  const outResult = procedure.output.safeParse(handlerResult);
+  if (!outResult.success) {
+    // Output-schema mismatch is a programmer bug (server returned
+    // wrong shape). Log loud in dev; return a generic 500 in prod.
+    if (isDev) {
+      console.error(
+        `[Mandu RPC] output validation failed in ${endpoint}.${method}:`,
+        outResult.error.errors
+      );
+    }
+    return jsonResponse(
+      {
+        ok: false,
+        error: {
+          code: "OUTPUT_INVALID",
+          message: isDev
+            ? "Handler returned a value that does not match the output schema."
+            : "Internal RPC error",
+          issues: isDev ? zodIssues(outResult.error) : undefined,
+        },
+      },
+      500
+    );
+  }
+
+  return jsonResponse({ ok: true, data: outResult.data }, 200);
+}