feat(rpc): transport, server, client, http, mounting, docs (Tasks 5-11)

Brings the uncommitted body of work under version control so it cannot be
lost. Gates are green: 152 tests pass across rpc/router/dev-server,
typecheck, lint, format and check:public-api all clean.

NOT YET REVIEWED. None of Tasks 5-11 has had an independent task review, and
Task 4's second fix round was never re-reviewed either.

Known gaps against the plan, recorded here rather than discovered later:
- packages/rpc/test/{transport,server,client}.test.ts are ABSENT. The plan
  required a test file for each. server.ts holds the fail-closed identity and
  permission checks and currently has no direct coverage at all.
- rpc-endpoint.test.ts has 3 tests where the plan specified 9. Missing:
  unknown service, non-POST, malformed body, non-rpc passthrough, and the
  isInternalCaller sweep. This is the task where a reachable
  /__wrnexus/rpc/* makes every permission check in the workspace bypassable.
- http.test.ts has 3 of 7; integration.test.ts 2 of 3;
  services-discovery.test.ts 1 of 4.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

packages/dev-server/test/gateway.test.ts

@@ -4,6 +4,7 @@ import {
   forwardAuthFailure,
   forwardAuthHeaders,
   gatewayProxyHeaders,
+  stripUntrustedInternalHeaders,
   gatewayRestartDelay,
   internalError,
   stripInternalError,
@@ -34,6 +35,16 @@ test("gateway disables compression for its internal proxy hop", () => {
   expect(headers.get("x-forwarded-for")).toBe("127.0.0.1");
 });
 
+test("gateway proxy headers do not preserve the RPC internal marker", () => {
+  const request = new Request("http://localhost:3000/path", {
+    headers: { "x-wrnexus-internal": "1" },
+  });
+  const headers = stripUntrustedInternalHeaders(
+    gatewayProxyHeaders(request, new URL(request.url), "127.0.0.1", true),
+  );
+  expect(headers.has("x-wrnexus-internal")).toBe(false);
+});
+
 test("forward auth preserves intentional verifier redirects", () => {
   const redirected = forwardAuthFailure(
     new Response(null, { status: 302, headers: { location: "/login?returnTo=%2Fadmin" } }),

packages/dev-server/test/observability-runtime.test.ts

@@ -14,6 +14,7 @@ function runtime(health: HealthRegistry, trustProxy = false) {
     stores: [],
     schemas: [],
     authz: [],
+    services: [],
     matchPage: () => null,
     matchApi: () => null,
     matchRealtime: () => null,

packages/dev-server/test/rpc-endpoint.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import { defineService, implement, procedure } from "@wrnexus/rpc";
+import { v } from "@wrnexus/validation";
+import { handleRpcRequest, isInternalCaller, isRpcPath } from "../src/rpc-dispatch.ts";
+
+const demo = defineService({
+  name: "demo",
+  procedures: {
+    add: procedure
+      .input(v.object({ a: v.number() }))
+      .output<{ a: number }>()
+      .build(),
+  },
+});
+const services = new Map([
+  ["demo", implement(demo, { add: async ({ a }) => ({ a }) }, { selfApp: "demo-app" })],
+]);
+
+function request(path: string, headers: Record<string, string> = {}) {
+  return new Request(`http://demo.test${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json", ...headers },
+    body: JSON.stringify({ a: 2 }),
+  });
+}
+
+describe("RPC endpoint", () => {
+  test("only matches its reserved prefix", () => {
+    expect(isRpcPath("/__wrnexus/rpc/demo/add")).toBe(true);
+    expect(isRpcPath("/__wrnexus/rpcx/demo/add")).toBe(false);
+  });
+
+  test("dispatches a private request", async () => {
+    const req = request("/__wrnexus/rpc/demo/add", { "x-wrnexus-internal": "1" });
+    expect(await (await handleRpcRequest(req, new URL(req.url), services))!.json()).toEqual({
+      ok: true,
+      value: { a: 2 },
+    });
+  });
+
+  test("rejects public or forwarded requests", async () => {
+    const external = request("/__wrnexus/rpc/demo/add");
+    expect((await handleRpcRequest(external, new URL(external.url), services))!.status).toBe(404);
+    const forwarded = request("/__wrnexus/rpc/demo/add", {
+      "x-wrnexus-internal": "1",
+      "x-forwarded-for": "203.0.113.1",
+    });
+    expect(isInternalCaller(forwarded)).toBe(false);
+    expect((await handleRpcRequest(forwarded, new URL(forwarded.url), services))!.status).toBe(404);
+  });
+});