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/rpc/test/http.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { RPC_ERROR_CODES } from "../src/errors.ts";
+import { RPC_IDENTITY_HEADER } from "../src/identity.ts";
+import { httpTransport, rpcPath } from "../src/http.ts";
+
+const target = { app: "billing", service: "billing", procedure: "createInvoice" };
+
+function transportWith(handler: (request: Request) => Response | Promise<Response>) {
+  return httpTransport({
+    resolveOrigin: () => "http://billing.test",
+    fetch: (async (input: RequestInfo | URL, init?: RequestInit) =>
+      handler(new Request(input, init))) as typeof fetch,
+  });
+}
+
+describe("httpTransport", () => {
+  test("posts to the private endpoint with identity", async () => {
+    const transport = transportWith(async (request) => {
+      expect(request.url).toBe("http://billing.test/__wrnexus/rpc/billing/createInvoice");
+      expect(request.headers.get(RPC_IDENTITY_HEADER)).toBe("token");
+      expect(request.headers.get("x-wrnexus-internal")).toBe("1");
+      expect(await request.json()).toEqual({ amountCents: 5 });
+      return Response.json({ ok: true, value: { invoiceId: "inv_1" } });
+    });
+    expect(await transport.call(target, { amountCents: 5 }, { identity: "token" })).toEqual({
+      ok: true,
+      value: { invoiceId: "inv_1" },
+    });
+  });
+
+  test("classifies unavailable and malformed responses safely", async () => {
+    const unavailable = transportWith(() => new Response("busy", { status: 503 }));
+    const failed = await unavailable.call(target, {}, {});
+    expect(failed).toMatchObject({ code: RPC_ERROR_CODES.transport, retryable: true });
+    const malformed = transportWith(() => Response.json({ hello: "world" }));
+    expect(await malformed.call(target, {}, {})).toMatchObject({
+      code: RPC_ERROR_CODES.malformed,
+      retryable: false,
+    });
+  });
+
+  test("uses the stable reserved path", () => {
+    expect(rpcPath("billing", "createInvoice")).toBe("/__wrnexus/rpc/billing/createInvoice");
+  });
+});

packages/rpc/test/integration.test.ts

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import type { Context } from "@wrnexus/core";
+import { v } from "@wrnexus/validation";
+import { serviceClient } from "../src/client.ts";
+import { defineService, procedure } from "../src/contract.ts";
+import { RPC_ERROR_CODES } from "../src/errors.ts";
+import { implement } from "../src/server.ts";
+import { inProcessTransport } from "../src/transport.ts";
+
+const originalRpcSecret = process.env.WRNEXUS_RPC_SECRET;
+const originalAppName = process.env.WRNEXUS_APP_NAME;
+afterEach(() => {
+  if (originalRpcSecret === undefined) delete process.env.WRNEXUS_RPC_SECRET;
+  else process.env.WRNEXUS_RPC_SECRET = originalRpcSecret;
+  if (originalAppName === undefined) delete process.env.WRNEXUS_APP_NAME;
+  else process.env.WRNEXUS_APP_NAME = originalAppName;
+});
+
+const billing = defineService({
+  name: "billing",
+  procedures: {
+    createInvoice: procedure
+      .input(v.object({ amountCents: v.number() }))
+      .output<{ invoiceId: string; forSubject: string }>()
+      .permission("invoice:create")
+      .build(),
+  },
+});
+
+function wire(allowed: boolean) {
+  const service = implement(
+    billing,
+    {
+      createInvoice: async ({ amountCents }, ctx) => ({
+        invoiceId: `inv_${amountCents}`,
+        forSubject: ctx.subject?.subjectId ?? "anon",
+      }),
+    },
+    { selfApp: "billing", checkPermission: async () => allowed },
+  );
+  return inProcessTransport({
+    "billing/createInvoice": (payload, identity) =>
+      service.invoke("createInvoice", payload, identity),
+  });
+}
+
+describe("RPC integration", () => {
+  test("propagates identity and validates the callee permission", async () => {
+    process.env.WRNEXUS_RPC_SECRET = "test-rpc-secret-at-least-32-chars-long";
+    process.env.WRNEXUS_APP_NAME = "web";
+    const client = serviceClient(billing, {
+      app: "billing",
+      as: { user: { id: "u1" }, tenant: { id: "acme" }, locals: {} } as unknown as Context,
+      transport: wire(true),
+    });
+    expect(await client.createInvoice({ amountCents: 250 })).toEqual({
+      invoiceId: "inv_250",
+      forSubject: "u1",
+    });
+  });
+
+  test("denies when the callee permission check refuses", async () => {
+    process.env.WRNEXUS_RPC_SECRET = "test-rpc-secret-at-least-32-chars-long";
+    process.env.WRNEXUS_APP_NAME = "web";
+    const client = serviceClient(billing, {
+      app: "billing",
+      as: { user: { id: "u1" }, locals: {} } as unknown as Context,
+      transport: wire(false),
+    });
+    await expect(client.createInvoice({ amountCents: 1 })).rejects.toMatchObject({
+      code: RPC_ERROR_CODES.denied,
+    });
+  });
+});