Story-1479 pramaan-admin BFF proxy

Generated firms browser calls now land on a server-owned proxy.

This walkthrough is for reviewers checking the smallest post-#1478 BFF slice: generated /admin/firms calls resolve to /api/internal/firms, validate generated schemas, and keep upstream credentials server-side.

What Changed

src/app/api/internal/firms/route.ts now handles generated browser GET and POST traffic for the firms list and create surface.
GET query params are parsed with adminListFirmsQueryParamsSchema; POST bodies are parsed with adminCreateFirmMutationRequestSchema.
src/lib/firms/gateway.ts delegates to the existing src/lib/gateway.ts, fetches as unknown, then asserts firmListResponseSchema or firmCreateResponseSchema through @/gen/_assert.
GatewayError responses are mapped back into the generated ErrorResponse envelope so generated clients receive contract-shaped failures.

Browser-To-Server Proof

The Kubb browser adapter from #1478 was reused as-is. A focused unit test calls the generated firms client with /admin/firms and proves the request is sent to /api/internal/firms?page=1&pageSize=25&sort=created_at_desc with a successful response, not a 404.

No adapter rewrite: src/lib/kubb-client.ts already performs the generic /admin/* to /api/internal/* swap, so this Story does not modify or recreate it.

Trust And Observability

The browser never receives GATEWAY_SERVICE_KEY or the Clerk bearer token. Those remain inside src/lib/gateway.ts, which is also where pramaan-docs ADR-104 traceparent forwarding lives.

No tracer, OTel wrapper, exporter, or route-local instrumentation was added. Per pramaan-docs ADR-124 and the admin ADR-104 bridge, the route participates by forwarding every upstream call through src/lib/gateway.ts.

Explicit Boundaries

Left for #1480

TanStack Query provider mounting and runtime invalidation are not introduced here.

Left for #1481

The existing firms page remains on server actions and is not migrated to generated hooks.

Not in Scope

No staff, support-access, firm detail, billing, or roster BFF routes are added in this Story.

Reviewer Checks

Run pnpm exec vitest run tests/unit/firms-bff-gateway.test.ts tests/unit/firms-bff-route.test.ts.
Confirm git status src/gen is clean; this Story imports generated contracts only.
Confirm git diff -- src/lib/kubb-client.ts is empty; the #1478 adapter is reused.
Confirm pnpm check:story-walkthrough passes with Closes pramaan-io/pramaan-spec#1479 in the PR body.