service: ZodSmartCoercionPlugin imported from @orpc/zod (Zod 3) while scaffolds use Zod 4 — coercion silently no-ops, every numeric query param 400s

[rickylabs]

The scaffolded API docs page sends query parameters as strings, but the generated contract validates them as numbers — so the documented GET request fails with a 400 straight out of the box, using the docs page's own default value.

Reported by the maintainer on a fresh clone, following the docs.

Reproduction

Open the scaffolded API docs (/api/docs), select GET /issues/board, leave the pre-filled cycleId=1, press Send.

GET http://localhost:60746/api/issues/board?cycleId=1
30ms  230 B  400 Bad Request

{
  "defined": false,
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "Input validation failed",
  "data": { "issues": [ {
    "expected": "number",
    "code": "invalid_type",
    "path": ["cycleId"],
    "message": "Invalid input: expected number, received string"
  } ] }
}

Why this matters more than a cosmetic bug

The API docs page is the first interactive surface a developer touches — it is how you confirm the backend you just scaffolded actually works. Right now the first request you can possibly make fails, and the error blames your input for a value the page itself supplied.

It also undermines the surface agents are being pointed at: #1204 added OpenAPI introspection read tools precisely so agents stop hand-rolling curl. If the documented request shape produces a 400, an agent that follows it concludes the endpoint is broken and goes back to curl — which is the behaviour we are trying to eliminate.

Cause

Query parameters arrive as strings over HTTP. The contract schema declares cycleId as a number and validation runs without coercion, so a numeric path parameter can never be satisfied through the docs client.

Either the generated schema should coerce query params, or the docs client should send typed values — but the two must agree, because today the scaffold ships them disagreeing.

Acceptance

• The scaffolded API docs page's default request for every generated GET endpoint no longer fails on parameter coercion (scope clarified 2026-08-04 during composed verification: list+health 200 with numeric defaults; by-id reaches the handler — its 500 on a missing row is service: generated by-id handler returns 500 {defined:false} for a missing row instead of a defined 404 #1263, and the empty "seeded" table is scaffold: db seed is a placebo — SELECT 1 plus a success banner, no rows seeded #1262, both outside this fix)
• Numeric query parameters are coerced (or the docs client sends them correctly) so the documented shape validates — RED→GREEN HTTP evidence in PR #1256
• The same request shape works through the OpenAPI introspection tools added in feat(mcp): add OpenAPI introspection read tools #1204
• A test covers a numeric query parameter end to end through the docs surface, not just through a typed client — handlers_test.ts evidence in PR #1256

[rickylabs]

Root cause found — the coercion plugin is already installed, from the wrong subpath

Both my original framing and the follow-up research concluded that defineService() constructs the OpenAPI handler without smart coercion and exposes no plugin seam. That is not what the source says. The plugin is already wired:

// packages/service/src/primitives/handlers.ts:171
const plugins = [...createRPCPlugins(config ?? {}), new ZodSmartCoercionPlugin()];
return new OpenAPIHandler(router, { plugins });

and the intent is documented on the function itself:

"Creates an oRPC OpenAPI handler for REST-style API access. Includes ZodSmartCoercionPlugin for automatic query string type coercion."

So no new configuration seam is needed. The defect is one import line.

The actual bug: Zod 3 plugin against Zod 4 schemas

Two files in the same package disagree about which oRPC Zod entrypoint to use:

// packages/service/src/primitives/handlers.ts:25
import { ZodSmartCoercionPlugin } from '@orpc/zod';          // ← Zod 3 path

// packages/service/src/primitives/openapi.ts:21
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4';   // ← Zod 4 path

Scaffolded projects are on Zod 4 (npm:zod@^4.3.6), and the JSON-schema converter in the very same package already targets @orpc/zod/zod4. Only the coercion plugin is imported from the Zod 3 surface.

oRPC's documented Zod 4 form is:

import { experimental_ZodSmartCoercionPlugin as ZodSmartCoercionPlugin } from '@orpc/zod/zod4';

The Zod 3 plugin cannot recognise Zod 4 schema internals, so it installs, runs, coerces nothing, and validation then rejects "1" against z.number(). Silent no-op — which is why the handler looks correctly configured and every numeric query parameter still 400s.

Why this reading is better supported

• It explains why the scaffold intends coercion (docblock + wiring) yet does not get it
• It explains why ZodToJsonSchemaConverter — the Zod 4 import — works fine while coercion does not
• It requires no new public API, which the "expose a plugin seam" proposal did

Revised fix

Change the import (and the plugin construction if the experimental alias differs):

- import { ZodSmartCoercionPlugin } from '@orpc/zod';
+ import { experimental_ZodSmartCoercionPlugin as ZodSmartCoercionPlugin } from '@orpc/zod/zod4';

Then audit for any other @orpc/zod import that should be @orpc/zod/zod4.

Application-level workaround, still valid meanwhile

Coerce only at the transport boundary, preserving database derivation:

cycleId: z.coerce.number().pipe(DatabaseCycleSchema.shape.id.positive()).optional()

JSON body fields stay strict numbers — JSON carries numbers natively, so only query and path parameters need this. Verified against the running Aspire service: GET /api/issues/board?cycleId=1 → 200 OK, contracts and issues service type-check clean.

Revised acceptance

• ZodSmartCoercionPlugin is imported from @orpc/zod/zod4, matching the Zod version the scaffold ships
• No other @orpc/zod import in the codebase targets the wrong major
• Coercion is installed on the OpenAPI handler only, never on the RPC handler
• Regression tests: numeric query param · numeric path param · optional numeric query omitted · abc rejected · 0 and -1 rejected under a positive constraint · JSON body number still strict · RPC handler asserted free of coercion
• A test would fail if the import reverted to the Zod 3 path — a plugin that silently no-ops must not pass as installed

[rickylabs]

Workaround committed — rickylabs/pulseboard

Branch agent/derive-contracts-from-db-schema, commit 77c92c7 — "Coerce OpenAPI numeric route parameters". One file, 5 insertions:

-  id: DatabaseIssueSchema.shape.id.positive(),
+  id: z.coerce.number().pipe(DatabaseIssueSchema.shape.id.positive()),

-  issueId: DatabaseCommentSchema.shape.issueId.positive(),
+  issueId: z.coerce.number().pipe(DatabaseCommentSchema.shape.issueId.positive()),

-      cycleId: DatabaseCycleSchema.shape.id.positive().optional(),
+      cycleId: z.coerce.number().pipe(DatabaseCycleSchema.shape.id.positive()).optional(),

Three parameters — one path, one path, one query — each needing an explicit transport-boundary coercion in front of a database-derived schema that was already correct.

This is the cost of the one-line import bug, measured in userland. Every numeric path or query parameter, in every contract, in every scaffolded service, needs this wrapper — and it must be applied by hand each time, with nothing to catch the omission except a 400 at runtime. It also partially undoes the derive-don't-restate work from d606fe5 on the same branch: the schema is still derived, but every route parameter now carries transport plumbing around it.

The workaround is correct and should stay until the import is fixed. It is worth keeping in mind as the measure of the fix's value: one import line upstream removes this wrapper from every contract in every project.

Note the fix's blast radius is narrower than the workaround suggests — JSON body fields never needed it, because JSON carries numbers natively. Only the OpenAPI transport boundary is affected, which is exactly where ZodSmartCoercionPlugin was meant to be operating all along.