typespec-hono 0.19.1 → 0.21.0

package/README.md

@@ -175,6 +175,8 @@ and exists only for the duration of a request.
   request bodies, streaming, observability
 - [Cloudflare Workers](docs/cloudflare-workers.md): which router to pick, and what the bundle costs
 - [Reference](docs/reference.md): every option, every diagnostic, and the known limits
+- [Releasing](docs/releasing.md): rehearsing a two-package release against a local registry,
+  because the server resolves the library through npm and CI cannot verify a change spanning both
 
 ## Licence
 

package/dist/src/app.js

@@ -160,6 +160,222 @@ function bodyValidationFor(contentTypes) {
     }
     return { byType, unparseable };
 }
+/**
+ * The request-body middleware, emitted INTO the generated file rather than imported from the runtime
+ * module.
+ *
+ * **Because the runtime module is a contract too, and it is the one that breaks quietly.** An
+ * application may point `runtime-module` at a module of its own, and everything the generated file
+ * imports from there is something that application has to supply. A required, single-media-type body
+ * used to be mounted by `zValidator`, which throws `HTTPException` on a body it cannot read - a
+ * `text/plain` 400 raised before `deps.invalid` is called, so an API whose document declares a JSON
+ * error envelope answered a shape its own contract forbids. Routing those through the runtime's
+ * `byContentType` fixes it in one line and makes that export mandatory for every substituting app:
+ * measured, 15 arms red, every one an app whose module has no such export.
+ *
+ * Emitting the middleware removes the choice. The runtime contract does not grow to close the gap -
+ * it SHRINKS by the two names that used to serve it, and the mechanism now lives in the file that
+ * uses it, where a reader can see what their route is mounted with.
+ *
+ * **One reader, one rejection, three positions.** Required, optional and dispatched bodies differ in
+ * exactly two ways - whether an absent body is permitted, and how many media types may be declared -
+ * and nothing else. `validateBody` covers required and dispatched, which are the same function with
+ * one branch or several. `validateOptionalBody` is separate only because its `Input` type differs:
+ * what it publishes may be `undefined`, and that cannot be a runtime argument.
+ *
+ * **`z.input` on the way in, `z.output` on the way out.** A `.default(...)` makes a property optional
+ * to a caller and guaranteed to a handler, and Hono's chain types those two positions separately, so
+ * saying `z.output` on both would require callers to send what the document says they may omit.
+ *
+ * Every rejection goes through `deps.invalid` first, and falls back to `zValidator`'s own answer when
+ * the hook declines - kept identical so a route that changed shape does not change how it refuses.
+ */
+/**
+ * **Parameter validators parse SYNCHRONOUSLY, through `zValidator`'s own typed extension point.**
+ *
+ * `zValidator` calls `safeParseAsync` by default, and nothing this emitter writes is asynchronous:
+ * `vocabulary.test.ts` refuses every construct that could be - no `.transform()`, no `.pipe()`, and
+ * the single permitted `.refine()` is a synchronous predicate on a multipart file part. So the async
+ * path was buying nothing and costing on every request.
+ *
+ * Measured on an emitted five-property model, zod 4.5.2, 200k iterations:
+ *
+ * | call | ns/parse |
+ * | --- | --- |
+ * | `safeParseAsync` | 958 |
+ * | `safeParse` | 371 |
+ *
+ * **2.6x, on every parameter group of every request**, for a promise nothing awaited a result from.
+ * It also unblocks `z.compile()`, whose fast path is bypassed for any async parse - measured from
+ * `zod/compile`'s own shim, which returns the uncompiled run for `ctx.async`, and confirmed on the
+ * same fixture: compiled `safeParse` is 51 ns and compiled `safeParseAsync` is 923 ns.
+ *
+ * `validationFunction` is `@hono/zod-validator`'s published option and its return type admits a
+ * synchronous result, so this is the package's own seam rather than a way around it.
+ *
+ * `test/sync.test.ts` asserts that every schema emitted across the whole corpus really does parse
+ * synchronously, because `safeParse` THROWS on a schema that cannot - a claim about output this file
+ * does not produce is exactly the kind that needs an arm rather than a comment.
+ */
+const SYNC_PARSE = `/** Parse synchronously: nothing emitted here is async, and the async path costs 2.6x. */
+const SYNC = { validationFunction: (schema: z.ZodType, value: unknown) => schema.safeParse(value) };
+
+`;
+const BODY_READER = `/** The two ways Hono can read a request body: \`c.req.json()\` and \`c.req.parseBody()\`. */
+type BodyTarget = "json" | "form";
+
+/**
+ * A body that is not what its content type claims.
+ *
+ * **BOTH readers can fail.** Hono's own validator catches in both branches and throws
+ * \`HTTPException\` - which is what escapes the app's envelope. Catching here is what lets the failure
+ * be reported like any other. Measured: an unreadable multipart body answered 500 while the JSON case
+ * answered 400, from the same missing \`try\`.
+ */
+const UNREADABLE = Symbol("a body that is not what its content type claims");
+
+async function readBody(c: Context, target: BodyTarget): Promise<unknown> {
+	try {
+		return target === "form" ? await c.req.parseBody({ all: true }) : await c.req.json();
+	} catch {
+		return UNREADABLE;
+	}
+}
+
+/**
+ * The failure an unreadable body produces, in the shape every other rejection has.
+ *
+ * Parsing \`undefined\` against the body's own schema is what makes a real Zod failure, so
+ * \`deps.invalid\` receives what it receives for a failed parse rather than a special case it has to
+ * know about. A schema that somehow accepts \`undefined\` still fails: a body that could not be read
+ * is not a body that validated.
+ */
+function unreadableResult(schema: z.ZodType): { readonly success: boolean } {
+	const parsed = schema.safeParse(undefined);
+	return parsed.success ? { success: false } : parsed;
+}
+
+/**
+ * Which reader parses the media type the request actually carries.
+ *
+ * A route may declare several request media types needing different parsers, and which one applies is
+ * decided by the caller's \`Content-Type\` when the request arrives - not when this file was
+ * generated. Parameters (\`; charset=utf-8\`, \`; boundary=...\`) are not part of the match, which
+ * matters because a multipart request always carries a boundary.
+ *
+ * A \`Content-Type\` matching nothing declared falls through to the first branch, so the body simply
+ * fails to parse and the app answers. No status is invented that the document does not describe.
+ */
+function bodyTarget(c: Context, branches: readonly (readonly [string, BodyTarget])[]): BodyTarget {
+	const declared = (c.req.header("content-type") ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
+	const matched = branches.find(([mediaType]) => mediaType.toLowerCase() === declared);
+	return matched?.[1] ?? branches[0]?.[1] ?? "json";
+}
+
+/** The app's rejection hook, as this file needs to name it. */
+type BodyInvalid<E extends Env> = <P extends string, I extends Input>(
+	result: { readonly success: boolean },
+	c: Context<E, P, I>,
+) => Response | undefined;
+
+`;
+/**
+ * The required-body half, emitted only where a route declares one.
+ *
+ * **Split from the optional half because `noUnusedLocals` makes an unused declaration an error**, and
+ * a generated file has to pass the lint of whatever project it lands in. Three declarations have
+ * shipped that way already - `zValidator` and `z` imported unconditionally, and `Simplify<T>` written
+ * into a contracts file with nothing to flatten. Emitting both functions whenever any body exists
+ * made it four, in eight fixtures at once.
+ */
+const REQUIRED_BODY_MIDDLEWARE = `/**
+ * Validate a REQUIRED request body, whatever media type it arrives as.
+ *
+ * The validated value is published under \`"json"\` whichever reader produced it: \`ValidationTargets\`
+ * is a closed union in Hono, so there is no name to coin for "the body", and using one slot is what
+ * makes every route the same shape downstream.
+ */
+function validateBody<E extends Env, S extends z.ZodType>(
+	schema: S,
+	invalid: BodyInvalid<E>,
+	branches: readonly (readonly [string, BodyTarget])[],
+): MiddlewareHandler<E, string, { in: { json: z.input<S> }; out: { json: z.output<S> } }> {
+	return async (c, next) => {
+		/**
+		 * Annotated rather than inlined, and that is what removes a CAST from this file. \`Context\` is
+		 * invariant in its environment and in its \`Input\`, so passing the outer \`c\` to a hook typed
+		 * against the route's own input needs either an annotation here or an \`as never\` there.
+		 */
+		const parse: MiddlewareHandler<
+			E,
+			string,
+			{ in: { json: z.input<S> }; out: { json: z.output<S> } }
+		> = async (ctx, proceed) => {
+			const raw = await readBody(ctx, bodyTarget(ctx, branches));
+			const result =
+				raw === UNREADABLE ? unreadableResult(schema) : schema.safeParse(raw);
+			const response = invalid(result, ctx);
+			if (response !== undefined) return response;
+			if (!result.success) return ctx.json(result, 400);
+			ctx.req.addValidatedData("json", ("data" in result ? result.data : undefined) ?? {});
+			await proceed();
+			return undefined;
+		};
+		return parse(c, next);
+	};
+}
+
+`;
+/** The optional-body half. Emitted only where the document publishes `requestBody.required: false`. */
+const OPTIONAL_BODY_MIDDLEWARE = `/**
+ * Validate a body the document says is OPTIONAL, and let a request carrying none through.
+ *
+ * \`requestBody.required: false\` means a request with no body is one the contract permits. Nothing is
+ * published when the body is absent, so \`c.req.valid("json")\` reads \`undefined\` and the handler is
+ * told the truth - which is why an optional body is a NAMED property on the input rather than merged
+ * into it. A body that is present but unreadable still fails, through the same hook.
+ */
+function validateOptionalBody<E extends Env, S extends z.ZodType>(
+	schema: S,
+	invalid: BodyInvalid<E>,
+	branches: readonly (readonly [string, BodyTarget])[],
+): MiddlewareHandler<
+	E,
+	string,
+	{ in: { json: z.input<S> | undefined }; out: { json: z.output<S> | undefined } }
+> {
+	return async (c, next) => {
+		const parse: MiddlewareHandler<
+			E,
+			string,
+			{ in: { json: z.input<S> | undefined }; out: { json: z.output<S> | undefined } }
+		> = async (ctx, proceed) => {
+			/**
+			 * Both halves are load-bearing. The platform reports \`null\` for a request sent without a
+			 * body, and a caller may instead send \`content-length: 0\`, which is a body of no bytes and
+			 * reads the same way to anything downstream. Neither alone covers what arrives.
+			 */
+			const absent =
+				ctx.req.raw.body === null || (ctx.req.header("content-length") ?? "").trim() === "0";
+			if (absent) {
+				await proceed();
+				return undefined;
+			}
+			const raw = await readBody(ctx, bodyTarget(ctx, branches));
+			const result =
+				raw === UNREADABLE ? unreadableResult(schema) : schema.safeParse(raw);
+			const response = invalid(result, ctx);
+			if (response !== undefined) return response;
+			if (!result.success) return ctx.json(result, 400);
+			ctx.req.addValidatedData("json", ("data" in result ? result.data : undefined) ?? {});
+			await proceed();
+			return undefined;
+		};
+		return parse(c, next);
+	};
+}
+
+`;
 /**
  * How an unparsed body reaches the handler, and as what.
  *
@@ -291,10 +507,6 @@ function inputTypeOf(entry) {
 function capitaliseId(operationId) {
     return `${operationId.charAt(0).toUpperCase()}${operationId.slice(1)}`;
 }
-/** The schema identifier a dispatched body validates against. */
-function identifierOf(entry) {
-    return entry.dispatched?.identifier ?? "";
-}
 /**
  * The resource a route belongs to (its first path segment) or `undefined` when it has none.
  *
@@ -357,14 +569,13 @@ basePaths = [],
  */
 securityFor) {
     const mounted = emitted.routes.flatMap((route) => {
-        let dispatched;
         const names = emitted.schemaNames.get(route.operationId);
         // The library declares a `Responses` const for every operation, so a missing entry is a bug in
         // this package's pairing rather than a spec the emitter chose not to serve.
         if (names === undefined)
             return [];
         const validators = [];
-        let optional;
+        let body;
         for (const location of ["path", "query", "header", "body"]) {
             const identifier = names[location];
             if (identifier === undefined)
@@ -374,60 +585,29 @@ securityFor) {
                 continue;
             }
             /**
-             * The body is the one location whose parser the document does not fix at generation time.
-             * Where it declares a single parseable media type this is one `zValidator`, unchanged. Where
-             * it declares several, the choice belongs to the caller's `Content-Type` and is made then.
+             * **The body is the one location whose parser the document does not fix at generation
+             * time**, and it is the one whose rejection used to depend on which of three mountings it
+             * got. All three are now one emitted middleware; what the document decides is only the
+             * branches it is given and whether an absent body is permitted.
              */
-            const body = bodyValidationFor(route.requestContentTypes);
-            if (body.unparseable.length > 0)
-                refuse.unvalidatableMediaType(route, body.unparseable);
-            if (body.byType.length === 0)
-                continue;
-            const targets = [...new Set(body.byType.map(([, target]) => target))];
-            if (targets.length === 1) {
-                /**
-                 * **An optional body is mounted by `optionalBody`, not `zValidator`**, so a request
-                 * carrying none is let through instead of refused - see the runtime's docblock for the
-                 * 400 that produced. It publishes under the canonical body slot whichever parser read
-                 * it, exactly as `byContentType` does, so the handler reads it the same way everywhere.
-                 */
-                if (route.optionalBody) {
-                    validators.push([VALIDATOR_TARGET.body, identifier]);
-                    optional = { target: targets[0], identifier };
-                    continue;
-                }
-                /**
-                 * **A required body keeps `zValidator`, and unifying it was tried and reverted.**
-                 *
-                 * `zValidator` raises `HTTPException` on a body that is not the JSON its content type
-                 * claims, BEFORE `deps.invalid` runs, so that 400 is `text/plain` and escapes the app's
-                 * error envelope. Routing every body through `byContentType` fixes it and is the obvious
-                 * move - one code path, one place the rejection is decided.
-                 *
-                 * **It is a breaking change to the RUNTIME CONTRACT, not just to emitted output.** An app
-                 * that points `runtime-module` at its own module would have to export `byContentType`,
-                 * which today it needs only if some operation declares several request media types - rare
-                 * enough that no consumer exports it. Measured: 15 arms red, every one of them an app
-                 * whose substituted module has no such export.
-                 *
-                 * The envelope gap is real and stays open for a required single-media-type body. Closing
-                 * it wants a form that adds no export to the runtime contract - most likely emitting the
-                 * middleware into `app.gen.ts` itself - and that is its own change, not a line here.
-                 */
-                validators.push([targets[0], identifier]);
-                continue;
+            const validation = bodyValidationFor(route.requestContentTypes);
+            if (validation.unparseable.length > 0) {
+                refuse.unvalidatableMediaType(route, validation.unparseable);
             }
+            if (validation.byType.length === 0)
+                continue;
             /**
-             * **Recorded as an ordinary body validator as well**, because `byContentType` publishes what
-             * it validated under the body target whichever parser produced it. So a dispatched route is
-             * the same shape as every other one downstream: the handler's input type includes the body,
-             * and the handler reads it with one `c.req.valid` like anywhere else. What differs is only
-             * which middleware is emitted, below.
+             * **Recorded under the canonical body slot whatever media type arrives.** The middleware
+             * publishes what it validated under one target, so the handler reads it with a single
+             * `c.req.valid("json")` whether the body was JSON, a form, or chosen from the request's
+             * `Content-Type`. A required form body used to be published under `"form"` instead, which
+             * made it the one route shape that read differently downstream for no reason the document
+             * states.
              */
             validators.push([VALIDATOR_TARGET.body, identifier]);
-            dispatched = { byType: body.byType, identifier };
+            body = { branches: validation.byType, identifier, optional: route.optionalBody === true };
         }
-        return [{ route, names, validators, dispatched, optional }];
+        return [{ route, names, validators, body }];
     });
     const entries = mounted;
     /**
@@ -483,6 +663,28 @@ type Fields<T> = string extends keyof T ? ([T[string]] extends [never] ? unknown
 
 `
         : "";
+    /**
+     * **Which halves of the body middleware this file needs**, decided from the routes rather than from
+     * the rendered text - the rule the import block below states, and once broke by matching a
+     * substring that a new argument had moved.
+     *
+     * Each half is emitted only where something mounts it: `noUnusedLocals` makes an unused declaration
+     * an error, and a generated file has to pass the lint of whatever project it lands in.
+     */
+    const mountsRequiredBody = entries.some((entry) => entry.body?.optional === false);
+    const mountsOptionalBody = entries.some((entry) => entry.body?.optional === true);
+    const mountsBody = mountsRequiredBody || mountsOptionalBody;
+    const bodyHelper = mountsBody
+        ? `${BODY_READER}${mountsRequiredBody ? REQUIRED_BODY_MIDDLEWARE : ""}${mountsOptionalBody ? OPTIONAL_BODY_MIDDLEWARE : ""}`
+        : "";
+    /**
+     * **Whether any `zValidator` is actually emitted**, which is the same question the import block
+     * below asks - stated once, because `SYNC` is passed to every one of those calls and a second
+     * spelling of the rule is a second thing that can drift. A body's target is filtered out: it is
+     * mounted by the emitted middleware instead, so a route with only a body mounts no `zValidator`.
+     */
+    const validates = entries.some((entry) => entry.validators.filter(([target]) => entry.body === undefined || target !== VALIDATOR_TARGET.body).length > 0);
+    const syncHelper = validates ? SYNC_PARSE : "";
     const methods = entries.map((entry) => {
         const { route, names } = entry;
         /**
@@ -512,7 +714,49 @@ type Fields<T> = string extends keyof T ? ([T[string]] extends [never] ? unknown
          * here on its own, because this signature is derived from `z.infer` rather than from those
          * types - which is exactly the half-fix `test/openmodel/` exists to catch.
          */
-        const output = names.response === undefined ? "void" : `Produced<z.infer<typeof ${names.response}>>`;
+        /**
+         * **The ENVELOPE a handler has to be able to say, beside the body it returns.**
+         *
+         * `@statusCode` and `@header` properties are stripped from the body schema - correctly, they
+         * are not body - so a return type derived from that schema alone could not carry them. The arms
+         * name them anyway: `{ headers: [{ property: "correlationId" }] }` tells `respond` to read a
+         * property off the returned value, and `when: { property: "statusCode" }` tells it which arm
+         * the handler meant. Measured before this existed, on `payload__head`:
+         * `Awaitable<Result<void>>` against an arm naming two header properties, so the emitter
+         * published an envelope contract nothing could satisfy.
+         *
+         * Only the SUCCESS statuses count. `responseHeaders` covers error responses too, and a header
+         * declared on a 404 is the error body's business rather than something a handler returns.
+         */
+        const successStatuses = route.statusSelector?.statuses ?? [route.statusCode];
+        const envelope = [];
+        if (route.statusSelector !== undefined) {
+            envelope.push(`${objectKey(route.statusSelector.property)}: ${route.statusSelector.statuses.join(" | ")}`);
+        }
+        const headerEntries = route.responseHeaders.filter((entry) => successStatuses.includes(entry.status));
+        const declaredOn = new Map();
+        for (const entry of headerEntries) {
+            for (const header of entry.headers) {
+                const seen = declaredOn.get(header.property);
+                declaredOn.set(header.property, {
+                    count: (seen?.count ?? 0) + 1,
+                    type: header.type,
+                });
+            }
+        }
+        for (const [property, { count, type }] of declaredOn) {
+            // Required only where EVERY success status declares it; otherwise the handler cannot know
+            // which status it is answering with until it has chosen one.
+            const optional = count === headerEntries.length && headerEntries.length === successStatuses.length;
+            envelope.push(`${objectKey(property)}${optional ? "" : "?"}: ${type}`);
+        }
+        const envelopeType = envelope.length === 0 ? undefined : `{ ${envelope.join("; ")} }`;
+        const body = names.response === undefined ? undefined : `Produced<z.infer<typeof ${names.response}>>`;
+        const output = body === undefined
+            ? (envelopeType ?? "void")
+            : envelopeType === undefined
+                ? body
+                : `${body} & ${envelopeType}`;
         const signature = `ctx: Ctx, input: ${input ?? EMPTY_INPUT}`;
         const doc = route.summary === undefined ? "" : `\t/** ${route.summary} */\n`;
         return `${doc}\t${route.operationId}(${signature}): Awaitable<Result<${output}>>;`;
@@ -526,7 +770,6 @@ type Fields<T> = string extends keyof T ? ([T[string]] extends [never] ? unknown
      * mentions a name is how this package lost the `byContentType` import: the call gained an argument
      * and the substring stopped matching, so a module referenced a function it no longer imported.
      */
-    const mountsOptionalBody = entries.some((entry) => entry.optional !== undefined);
     const returnsAnything = entries.some((entry) => entry.names.response !== undefined);
     const declaredHelper = returnsAnything
         ? `/**
@@ -684,41 +927,36 @@ type Produced<T> = T extends (...args: never[]) => unknown
          * from that type -- measured, `hc<typeof app>` resolved the wrapped route's body to `unknown`.
          */
         /**
-         * Where the document declares request media types needing different parsers, the parser is
-         * chosen from the request's `Content-Type`. `byContentType` takes the body's schema and
-         * `deps.invalid` and validates with them, so it stands in for that target's `zValidator`
-         * rather than wrapping one, and publishes under the body target either way.
+         * The body's own middleware, emitted into this file rather than imported - see
+         * `BODY_MIDDLEWARE` for why the runtime module is the wrong place for it.
          *
-         * **It used to wrap pre-built `zValidator`s and publish under whichever one ran, and that
-         * emitted code a consumer could not compile.** A plain `MiddlewareHandler` contributes no
-         * `Input` to Hono's chain, so `c.req.valid("json")` in the handler below was
+         * It stands IN FOR the body's `zValidator` rather than wrapping one, which is what lets it
+         * decide the rejection. A plain `MiddlewareHandler` contributes no `Input` to Hono's chain,
+         * so a wrapper made `c.req.valid("json")` in the handler below
          * `TS2345: Argument of type '"json"' is not assignable to parameter of type '"header"'`, and
-         * the handler's declared input type omitted the body entirely because the body was not among
-         * the route's validators. One published slot removes both.
+         * dropped the body from the handler's declared input type entirely. Publishing to one known
+         * slot removes both.
+         *
+         * The branches are always emitted, even the single one: a route declaring one media type is
+         * the same question with one answer, and a special case there is what let three mountings
+         * drift apart in the first place.
          */
-        const dispatch = entry.dispatched === undefined
+        const bodyMiddleware = entry.body === undefined
             ? []
             : [
-                `\t\tbyContentType(${identifierOf(entry)}, deps.invalid, [`,
-                ...entry.dispatched.byType.map(([type, target]) => `\t\t\t[${JSON.stringify(type)}, ${JSON.stringify(target)}],`),
+                `\t\t${entry.body.optional ? "validateOptionalBody" : "validateBody"}(${entry.body.identifier}, deps.invalid, [`,
+                ...entry.body.branches.map(([type, target]) => `\t\t\t[${JSON.stringify(type)}, ${JSON.stringify(target)}],`),
                 "\t\t]),",
             ];
         const middleware = [
             ...(headOnly ? ["\t\theadOnly,"] : []),
             ...gate,
             ...validators
-                // The dispatched body's own `zValidator` is `byContentType`; emitting both would parse
-                // the body twice and reject every media type but one. An optional body is the same
-                // story with `optionalBody`, which additionally lets a bodyless request through.
-                .filter(([target]) => (entry.dispatched === undefined && entry.optional === undefined) ||
-                target !== VALIDATOR_TARGET.body)
-                .map(([target, name]) => `\t\tzValidator(${JSON.stringify(target)}, ${name}, deps.invalid),`),
-            ...dispatch,
-            ...(entry.optional === undefined
-                ? []
-                : [
-                    `\t\toptionalBody(${entry.optional.identifier}, deps.invalid, ${JSON.stringify(entry.optional.target)}),`,
-                ]),
+                // The body's validator IS the middleware above; emitting a `zValidator` beside it would
+                // parse the body twice and reject every media type but one.
+                .filter(([target]) => entry.body === undefined || target !== VALIDATOR_TARGET.body)
+                .map(([target, name]) => `\t\tzValidator(${JSON.stringify(target)}, ${name}, deps.invalid, SYNC),`),
+            ...bodyMiddleware,
         ];
         /**
          * Whether the operation requires a caller, and NOTHING else about the caller.
@@ -979,7 +1217,6 @@ type Produced<T> = T extends (...args: never[]) => unknown
      * safe in a way these are not: an identifier absent from the text is genuinely not needed, so the
      * check cannot be wrong in the direction that breaks a build.
      */
-    const dispatchesBody = entries.some((entry) => entry.dispatched !== undefined);
     /**
      * **Imported only where a route actually validates something, like every other value import here.**
      *
@@ -990,7 +1227,7 @@ type Produced<T> = T extends (...args: never[]) => unknown
      * `TS6133: 'zValidator' is declared but its value is never read`.
      *
      * Counted from the same filtered list the middleware is rendered from, so it cannot disagree with
-     * what was emitted: a dispatched body's validator is `byContentType`, not a `zValidator`.
+     * what was emitted: a body's validator is the middleware this file declares, not a `zValidator`.
      */
     /**
      * **`z` is only ever reached through `z.infer`**, which appears where an operation has an input
@@ -998,9 +1235,14 @@ type Produced<T> = T extends (...args: never[]) => unknown
      * neither, so the import was written and never used:
      * `TS6133: 'z' is declared but its value is never read`. Same shape as the `zValidator` one above,
      * one step further along.
+     *
+     * The emitted body middleware names `z.input` and `z.output` as well, so a service whose only use
+     * of Zod is a request body still needs it.
      */
-    const usesZod = entries.some((entry) => inputTypeOf(entry) !== undefined || entry.names.response !== undefined);
-    const validates = entries.some((entry) => entry.validators.filter(([target]) => entry.dispatched === undefined || target !== VALIDATOR_TARGET.body).length > 0);
+    const usesZod = mountsBody ||
+        // `SYNC` annotates its schema parameter `z.ZodType`, so the value import is load-bearing.
+        validates ||
+        entries.some((entry) => inputTypeOf(entry) !== undefined || entry.names.response !== undefined);
     const runtimeModule = JSON.stringify(emitted.options.runtimeModule);
     /**
      * **One base sub-app, mounted with `app.route()`. Hono's own nesting, not a rewritten path on
@@ -1012,8 +1254,8 @@ type Produced<T> = T extends (...args: never[]) => unknown
     const usesBasePath = basePaths.length > 0;
     const needsHonoValue = subApps.size > 0 || usesBasePath;
     return `${generatedBanner(emitted.options.regenerateHint)}
-${validates ? 'import { zValidator } from "@hono/zod-validator";\n' : ""}${needsHonoValue ? 'import { Hono } from "hono";\nimport type { Context, Input } from "hono";' : 'import type { Context, Hono, Input } from "hono";'}
-${usesZod ? 'import { z } from "zod";\n' : ""}import type { AppEnv, Awaitable, Ctx, Result, RouteDeps } from ${runtimeModule};${negotiates ? `\nimport { selectContentType } from ${runtimeModule};` : ""}${guardsHead ? `\nimport { headOnly } from ${runtimeModule};` : ""}${dispatchesBody ? `\nimport { byContentType } from ${runtimeModule};` : ""}${mountsOptionalBody ? `\nimport { optionalBody } from ${runtimeModule};` : ""}
+${validates ? 'import { zValidator } from "@hono/zod-validator";\n' : ""}${needsHonoValue ? 'import { Hono } from "hono";\nimport type { Context, Input } from "hono";' : 'import type { Context, Hono, Input } from "hono";'}${mountsBody ? '\nimport type { Env, MiddlewareHandler } from "hono";' : ""}
+${usesZod ? 'import { z } from "zod";\n' : ""}import type { AppEnv, Awaitable, Ctx, Result, RouteDeps } from ${runtimeModule};${negotiates ? `\nimport { selectContentType } from ${runtimeModule};` : ""}${guardsHead ? `\nimport { headOnly } from ${runtimeModule};` : ""}
 ${imports}
 /**
  * One method per operation, each concretely typed from the schemas it validates against.
@@ -1021,7 +1263,7 @@ ${imports}
  * There is no cast anywhere in this file, and no dynamic lookup: the generated call sites name the
  * method, so an implementation whose input or output does not match the contract fails to compile.
  */
-${fieldsHelper}${declaredHelper}export interface Operations {
+${syncHelper}${bodyHelper}${fieldsHelper}${declaredHelper}export interface Operations {
 ${methods.join("\n")}
 }
 

package/dist/src/runtime.d.ts

@@ -1,5 +1,5 @@
 import type { Context, Env, Input, MiddlewareHandler } from "hono";
-import type { input, output, ZodType } from "zod";
+import type { ZodType } from "zod";
 /**
  * One arm of an operation's declared response set, as the document publishes it.
  *
@@ -36,7 +36,15 @@ export interface ResponseArm {
     }[];
     readonly when?: {
         readonly property: string;
-        readonly value: boolean | string;
+        /**
+         * **A number too, because a `@statusCode` union selects by the status itself.**
+         *
+         * `model Created { @statusCode statusCode: 200 | 201 }` names the property that chooses, and
+         * its values are the statuses. The discriminator case carries a boolean or string literal off
+         * the body instead; both are the same question - which arm did the handler mean - so both use
+         * this one field.
+         */
+        readonly value: boolean | number | string;
     };
 }
 /**
@@ -149,88 +157,20 @@ export declare function selectContentType(accept: string | undefined, offered: r
  */
 export declare const headOnly: MiddlewareHandler;
 /**
- * The `zValidator` targets a request BODY can be read from. Hono extracts `"json"` with
- * `c.req.json()` and `"form"` with `c.req.parseBody()`, and those are the only two that read a body.
- */
-export type BodyTarget = "json" | "form";
-/**
- * Apply the validator that parses the media type the request actually carries.
- *
- * A route may declare several request media types needing different parsers -- `addPet` in the
- * Swagger Petstore accepts JSON, XML and urlencoded on one path. `zValidator`'s target is fixed when
- * the server is generated; which parser applies is decided by the caller's `Content-Type` when the
- * request arrives. Those are different times, and only the second one has the answer.
- *
- * **Before this, one target was chosen for the whole route and everything else was rejected.** A
- * form-encoded body to a route declaring JSON first was handed to `c.req.json()` and answered 400,
- * with no diagnostic anywhere. The status looked like the caller's fault and was not.
- *
- * Parameters after the media type (`; charset=utf-8`, `; boundary=...`) are not part of the match,
- * which matters because a multipart request always carries a boundary.
+ * **The request-body middleware used to live here, and it moved into `app.gen.ts`.**
  *
- * A `Content-Type` matching nothing declared falls through to the first validator, which reproduces
- * the previous behaviour exactly for that case: the body fails to parse and `deps.invalid` answers.
- * No status is invented here that the document does not describe.
+ * `byContentType` and `optionalBody` were exported from this module and imported by the generated
+ * server, which made them part of a SECOND contract this package has: what an application that
+ * points `runtime-module` at a module of its own must export. That contract is easy to break without
+ * noticing, and it was the reason a required single-media-type body kept `zValidator` - whose
+ * `HTTPException` on an unreadable body is a `text/plain` 400 raised before `deps.invalid`, escaping
+ * the app's error envelope. Routing those through `byContentType` closed the gap in one line and
+ * made that export mandatory for every substituting app: measured, 15 arms red.
  *
- * **The validated body is published under `"json"` whichever parser produced it**, and that is what
- * makes a dispatched route the same shape as every other one downstream. `ValidationTargets` is a
- * closed union in Hono, so there is no seventh name to coin for "the body"; `"json"` is already the
- * slot this emitter reads a body from, and using it here means the handler spreads one
- * `c.req.valid("json")` exactly as it does for a route declaring a single media type.
- *
- * **The alternative was a middleware that publishes under whichever target ran**, and it was worse
- * in two ways that both shipped. `byContentType` was a bare `MiddlewareHandler`, which contributes no
- * `Input` to the chain, so the generated `c.req.valid("json")` did not compile at all
- * (`TS2345: Argument of type '"json"' is not assignable to parameter of type '"header"'`), and the
- * handler's declared input type omitted the body entirely because the body was not among the route's
- * ordinary validators. Publishing to one known slot removes both, rather than typing around them.
- */
-export declare function byContentType<E extends Env, S extends ZodType>(schema: S, invalid: <P extends string, I extends Input>(result: {
-    readonly success: boolean;
-}, c: Context<E, P, I>) => Response | undefined, 
-/**
- * **A NON-EMPTY list, stated in the type.** The fallback below reads the first branch, and
- * `branches[0]` on a plain array is `T | undefined`, which was silenced with a cast. A tuple says
- * the same thing the emitter already guarantees - this middleware is only ever emitted for a route
- * declaring at least one request media type - and removes the cast rather than typing around it.
+ * Emitting the middleware instead closes the gap and SHRINKS the runtime contract by these two
+ * names. Nothing generated imports them, so keeping them here would leave a second implementation of
+ * body reading that nothing exercises - which is how two copies of one rule drift apart.
  */
-branches: readonly [
-    readonly [mediaType: string, target: BodyTarget],
-    ...(readonly [mediaType: string, target: BodyTarget])[]
-]): MiddlewareHandler<E, string, {
-    in: {
-        json: input<S>;
-    };
-    out: {
-        json: output<S>;
-    };
-}>;
-/**
- * Validate a body the document says is OPTIONAL, and let a request carrying none through.
- *
- * **`requestBody.required: false` means a request with no body is one the contract permits**, and a
- * plain `zValidator` refused it. Measured against @hono/zod-validator 0.9.0 and hono 4.12.26: a
- * `POST` with `content-type: application/json` and no body answered **400 `Malformed JSON in request
- * body`** as `text/plain` - raised before the `invalid` hook, so outside the app's error envelope
- * entirely. A service refusing what its own document allows, in a shape that document forbids.
- *
- * **Nothing is published when the body is absent**, so `c.req.valid(...)` reads `undefined` and the
- * handler is told the truth. That is why an optional body is a NAMED property on the input rather
- * than merged into it: a merge has no way to say "these are here only sometimes" without making
- * every one of them optional, which is a weaker and different claim about the body that IS sent.
- *
- * A body that is present but unreadable still fails, through `invalid`, so the app's envelope holds.
- */
-export declare function optionalBody<E extends Env, S extends ZodType>(schema: S, invalid: <P extends string, I extends Input>(result: {
-    readonly success: boolean;
-}, c: Context<E, P, I>) => Response | undefined, target: BodyTarget): MiddlewareHandler<E, string, {
-    in: {
-        json: input<S> | undefined;
-    };
-    out: {
-        json: output<S> | undefined;
-    };
-}>;
 /**
  * What the app provides. One object, passed once, rather than a module the generated file imports by
  * path. A generated server that hard-codes `../../backend.js` is only usable by the project it was

package/dist/src/runtime.js

@@ -103,168 +103,3 @@ export function selectContentType(accept, offered) {
  * type. Measured: `hc<typeof app>` resolved a wrapped route's body to `unknown`.
  */
 export const headOnly = async (c, next) => c.req.method === "HEAD" ? next() : c.notFound();
-/**
- * The request body, read the way the target says to read it.
- *
- * The same two readers Hono's own `validator` uses, and the same rejection for a body that is not
- * the JSON it claims to be. `parseBody({ all: true })` builds the object Hono's `"form"` target
- * builds: a repeated key and a `key[]` name both become an array, everything else stays a string.
- */
-const UNREADABLE = Symbol("a body that is not what its content type claims");
-async function readBody(c, target) {
-    if (target === "form")
-        return c.req.parseBody({ all: true });
-    try {
-        return await c.req.json();
-    }
-    catch {
-        return UNREADABLE;
-    }
-}
-/**
- * The failure a malformed body produces, reported through the app's `invalid` hook like any other.
- *
- * **It used to `throw new HTTPException(400)`, which never reaches that hook.** The response was
- * `text/plain` with a bare message, so an API whose document declares a JSON error envelope answered
- * a shape its own contract forbids - and the app had no way to intervene, because the throw happened
- * before its code ran.
- *
- * Parsing `undefined` against the body's own schema is what produces a real Zod failure, so
- * `deps.invalid` receives the shape it receives for every other rejection rather than a special case
- * it has to know about. A schema that somehow accepts `undefined` still fails here: a body that
- * could not be read is not a body that validated.
- */
-async function unreadableResult(schema) {
-    const parsed = await schema.safeParseAsync(undefined);
-    return parsed.success ? { success: false } : parsed;
-}
-/**
- * The slot a validated request body is published under, whichever parser produced it.
- *
- * `ValidationTargets` is a closed union in Hono, so a body cannot be given a name of its own. This
- * is the slot the generated code already reads a body from when one media type is declared, so using
- * it for a dispatched body is what keeps the two cases identical downstream.
- */
-const BODY_TARGET = "json";
-/**
- * Apply the validator that parses the media type the request actually carries.
- *
- * A route may declare several request media types needing different parsers -- `addPet` in the
- * Swagger Petstore accepts JSON, XML and urlencoded on one path. `zValidator`'s target is fixed when
- * the server is generated; which parser applies is decided by the caller's `Content-Type` when the
- * request arrives. Those are different times, and only the second one has the answer.
- *
- * **Before this, one target was chosen for the whole route and everything else was rejected.** A
- * form-encoded body to a route declaring JSON first was handed to `c.req.json()` and answered 400,
- * with no diagnostic anywhere. The status looked like the caller's fault and was not.
- *
- * Parameters after the media type (`; charset=utf-8`, `; boundary=...`) are not part of the match,
- * which matters because a multipart request always carries a boundary.
- *
- * A `Content-Type` matching nothing declared falls through to the first validator, which reproduces
- * the previous behaviour exactly for that case: the body fails to parse and `deps.invalid` answers.
- * No status is invented here that the document does not describe.
- *
- * **The validated body is published under `"json"` whichever parser produced it**, and that is what
- * makes a dispatched route the same shape as every other one downstream. `ValidationTargets` is a
- * closed union in Hono, so there is no seventh name to coin for "the body"; `"json"` is already the
- * slot this emitter reads a body from, and using it here means the handler spreads one
- * `c.req.valid("json")` exactly as it does for a route declaring a single media type.
- *
- * **The alternative was a middleware that publishes under whichever target ran**, and it was worse
- * in two ways that both shipped. `byContentType` was a bare `MiddlewareHandler`, which contributes no
- * `Input` to the chain, so the generated `c.req.valid("json")` did not compile at all
- * (`TS2345: Argument of type '"json"' is not assignable to parameter of type '"header"'`), and the
- * handler's declared input type omitted the body entirely because the body was not among the route's
- * ordinary validators. Publishing to one known slot removes both, rather than typing around them.
- */
-export function byContentType(schema, invalid, 
-/**
- * **A NON-EMPTY list, stated in the type.** The fallback below reads the first branch, and
- * `branches[0]` on a plain array is `T | undefined`, which was silenced with a cast. A tuple says
- * the same thing the emitter already guarantees - this middleware is only ever emitted for a route
- * declaring at least one request media type - and removes the cast rather than typing around it.
- */
-branches) {
-    return async (c, next) => {
-        const declared = (c.req.header("content-type") ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
-        const matched = branches.find(([mediaType]) => mediaType.toLowerCase() === declared);
-        const [, target] = matched ?? branches[0];
-        /**
-         * **Registered against the body slot whichever parser runs**, so the validated body is
-         * published under one target and the handler reads it exactly as it reads a single-media-type
-         * one. Hono's `validator` is what `@hono/zod-validator` is built on, so this is the same
-         * extraction, the same `HTTPException` on malformed JSON, and the same default rejection.
-         *
-         * **Hono's own `validator` is deliberately not called here.** Its target fixes the reader at
-         * registration time, and the whole point of this function is that the reader is chosen when the
-         * request arrives. What it does instead is reproduce `validator`'s observable behaviour for both
-         * targets: {@link readBody} performs the same two extractions and raises the same
-         * `HTTPException` on malformed JSON, and the rejection below is `zValidator`'s own.
-         *
-         * Annotated rather than inlined because `Context` is invariant in its environment and in its
-         * `Input`. Same reason `RouteDeps` is parameterised.
-         */
-        const parse = async (ctx, proceed) => {
-            const raw = await readBody(ctx, target);
-            const result = raw === UNREADABLE ? await unreadableResult(schema) : await schema.safeParseAsync(raw);
-            const response = invalid(result, ctx);
-            if (response !== undefined)
-                return response;
-            // `zValidator`'s own answer when a hook declines to, kept identical so a dispatched route
-            // and a single-media-type one reject a bad body the same way.
-            if (!result.success)
-                return ctx.json(result, 400);
-            ctx.req.addValidatedData(BODY_TARGET, ("data" in result ? result.data : undefined) ?? {});
-            await proceed();
-            return undefined;
-        };
-        return parse(c, next);
-    };
-}
-/**
- * Validate a body the document says is OPTIONAL, and let a request carrying none through.
- *
- * **`requestBody.required: false` means a request with no body is one the contract permits**, and a
- * plain `zValidator` refused it. Measured against @hono/zod-validator 0.9.0 and hono 4.12.26: a
- * `POST` with `content-type: application/json` and no body answered **400 `Malformed JSON in request
- * body`** as `text/plain` - raised before the `invalid` hook, so outside the app's error envelope
- * entirely. A service refusing what its own document allows, in a shape that document forbids.
- *
- * **Nothing is published when the body is absent**, so `c.req.valid(...)` reads `undefined` and the
- * handler is told the truth. That is why an optional body is a NAMED property on the input rather
- * than merged into it: a merge has no way to say "these are here only sometimes" without making
- * every one of them optional, which is a weaker and different claim about the body that IS sent.
- *
- * A body that is present but unreadable still fails, through `invalid`, so the app's envelope holds.
- */
-export function optionalBody(schema, invalid, target) {
-    return async (c, next) => {
-        if (!hasBody(c)) {
-            await next();
-            return undefined;
-        }
-        const raw = await readBody(c, target);
-        const result = raw === UNREADABLE ? await unreadableResult(schema) : await schema.safeParseAsync(raw);
-        const response = invalid(result, c);
-        if (response !== undefined)
-            return response;
-        if (!result.success)
-            return c.json(result, 400);
-        c.req.addValidatedData(BODY_TARGET, ("data" in result ? result.data : undefined) ?? {});
-        await next();
-        return undefined;
-    };
-}
-/**
- * Whether the request carries a body at all.
- *
- * Both halves are load-bearing. The platform reports `null` for a request sent without one, and a
- * caller may instead send `content-length: 0`, which is a body of no bytes and reads the same way to
- * anything downstream. Neither alone covers what arrives.
- */
-function hasBody(c) {
-    if (c.req.raw.body === null)
-        return false;
-    return (c.req.header("content-length") ?? "").trim() !== "0";
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-hono",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "TypeSpec emitter: generate a Hono server, and the Zod validators it enforces, from an HTTP service definition, agreeing with the OpenAPI document @typespec/openapi3 publishes from the same source.",
   "keywords": [
     "cloudflare-workers",
@@ -44,7 +44,7 @@
     "provenance": true
   },
   "dependencies": {
-    "typespec-http-zod": "^0.21.0"
+    "typespec-http-zod": "^0.24.0"
   },
   "devDependencies": {
     "@hono/zod-openapi": "^1.4.0",
@@ -67,14 +67,14 @@
     "typescript": "~7.0.2",
     "typespec-hono": "link:.",
     "vitest": "^4.1.9",
-    "zod": "^4.4.3"
+    "zod": "^4.5.2"
   },
   "peerDependencies": {
     "@hono/zod-validator": "^0.8.0 || ^0.9.0",
     "@typespec/compiler": "^1.15.0",
     "@typespec/http": "^1.15.0",
     "hono": "^4.12.0",
-    "zod": "^4.0.0"
+    "zod": "^4.5.0"
   },
   "engines": {
     "node": ">=22.0.0"

package/src/runtime.ts

@@ -1,5 +1,5 @@
 import type { Context, Env, Input, MiddlewareHandler } from "hono";
-import type { input, output, ZodType } from "zod";
+import type { ZodType } from "zod";
 
 /**
  * One arm of an operation's declared response set, as the document publishes it.
@@ -34,7 +34,15 @@ export interface ResponseArm {
 	readonly headers?: readonly { readonly name: string; readonly property: string }[];
 	readonly when?: {
 		readonly property: string;
-		readonly value: boolean | string;
+		/**
+		 * **A number too, because a `@statusCode` union selects by the status itself.**
+		 *
+		 * `model Created { @statusCode statusCode: 200 | 201 }` names the property that chooses, and
+		 * its values are the statuses. The discriminator case carries a boolean or string literal off
+		 * the body instead; both are the same question - which arm did the handler mean - so both use
+		 * this one field.
+		 */
+		readonly value: boolean | number | string;
 	};
 }
 
@@ -206,201 +214,20 @@ export const headOnly: MiddlewareHandler = async (c, next) =>
 	c.req.method === "HEAD" ? next() : c.notFound();
 
 /**
- * The `zValidator` targets a request BODY can be read from. Hono extracts `"json"` with
- * `c.req.json()` and `"form"` with `c.req.parseBody()`, and those are the only two that read a body.
- */
-export type BodyTarget = "json" | "form";
-
-/**
- * The request body, read the way the target says to read it.
- *
- * The same two readers Hono's own `validator` uses, and the same rejection for a body that is not
- * the JSON it claims to be. `parseBody({ all: true })` builds the object Hono's `"form"` target
- * builds: a repeated key and a `key[]` name both become an array, everything else stays a string.
- */
-const UNREADABLE = Symbol("a body that is not what its content type claims");
-
-async function readBody(c: Context, target: BodyTarget): Promise<unknown> {
-	if (target === "form") return c.req.parseBody({ all: true });
-	try {
-		return await c.req.json();
-	} catch {
-		return UNREADABLE;
-	}
-}
-
-/**
- * The failure a malformed body produces, reported through the app's `invalid` hook like any other.
- *
- * **It used to `throw new HTTPException(400)`, which never reaches that hook.** The response was
- * `text/plain` with a bare message, so an API whose document declares a JSON error envelope answered
- * a shape its own contract forbids - and the app had no way to intervene, because the throw happened
- * before its code ran.
- *
- * Parsing `undefined` against the body's own schema is what produces a real Zod failure, so
- * `deps.invalid` receives the shape it receives for every other rejection rather than a special case
- * it has to know about. A schema that somehow accepts `undefined` still fails here: a body that
- * could not be read is not a body that validated.
- */
-async function unreadableResult(schema: ZodType): Promise<{ readonly success: boolean }> {
-	const parsed = await schema.safeParseAsync(undefined);
-	return parsed.success ? { success: false } : parsed;
-}
-
-/**
- * The slot a validated request body is published under, whichever parser produced it.
- *
- * `ValidationTargets` is a closed union in Hono, so a body cannot be given a name of its own. This
- * is the slot the generated code already reads a body from when one media type is declared, so using
- * it for a dispatched body is what keeps the two cases identical downstream.
- */
-const BODY_TARGET = "json";
-
-/**
- * Apply the validator that parses the media type the request actually carries.
- *
- * A route may declare several request media types needing different parsers -- `addPet` in the
- * Swagger Petstore accepts JSON, XML and urlencoded on one path. `zValidator`'s target is fixed when
- * the server is generated; which parser applies is decided by the caller's `Content-Type` when the
- * request arrives. Those are different times, and only the second one has the answer.
- *
- * **Before this, one target was chosen for the whole route and everything else was rejected.** A
- * form-encoded body to a route declaring JSON first was handed to `c.req.json()` and answered 400,
- * with no diagnostic anywhere. The status looked like the caller's fault and was not.
- *
- * Parameters after the media type (`; charset=utf-8`, `; boundary=...`) are not part of the match,
- * which matters because a multipart request always carries a boundary.
- *
- * A `Content-Type` matching nothing declared falls through to the first validator, which reproduces
- * the previous behaviour exactly for that case: the body fails to parse and `deps.invalid` answers.
- * No status is invented here that the document does not describe.
+ * **The request-body middleware used to live here, and it moved into `app.gen.ts`.**
  *
- * **The validated body is published under `"json"` whichever parser produced it**, and that is what
- * makes a dispatched route the same shape as every other one downstream. `ValidationTargets` is a
- * closed union in Hono, so there is no seventh name to coin for "the body"; `"json"` is already the
- * slot this emitter reads a body from, and using it here means the handler spreads one
- * `c.req.valid("json")` exactly as it does for a route declaring a single media type.
+ * `byContentType` and `optionalBody` were exported from this module and imported by the generated
+ * server, which made them part of a SECOND contract this package has: what an application that
+ * points `runtime-module` at a module of its own must export. That contract is easy to break without
+ * noticing, and it was the reason a required single-media-type body kept `zValidator` - whose
+ * `HTTPException` on an unreadable body is a `text/plain` 400 raised before `deps.invalid`, escaping
+ * the app's error envelope. Routing those through `byContentType` closed the gap in one line and
+ * made that export mandatory for every substituting app: measured, 15 arms red.
  *
- * **The alternative was a middleware that publishes under whichever target ran**, and it was worse
- * in two ways that both shipped. `byContentType` was a bare `MiddlewareHandler`, which contributes no
- * `Input` to the chain, so the generated `c.req.valid("json")` did not compile at all
- * (`TS2345: Argument of type '"json"' is not assignable to parameter of type '"header"'`), and the
- * handler's declared input type omitted the body entirely because the body was not among the route's
- * ordinary validators. Publishing to one known slot removes both, rather than typing around them.
+ * Emitting the middleware instead closes the gap and SHRINKS the runtime contract by these two
+ * names. Nothing generated imports them, so keeping them here would leave a second implementation of
+ * body reading that nothing exercises - which is how two copies of one rule drift apart.
  */
-export function byContentType<E extends Env, S extends ZodType>(
-	schema: S,
-	invalid: <P extends string, I extends Input>(
-		result: { readonly success: boolean },
-		c: Context<E, P, I>,
-	) => Response | undefined,
-	/**
-	 * **A NON-EMPTY list, stated in the type.** The fallback below reads the first branch, and
-	 * `branches[0]` on a plain array is `T | undefined`, which was silenced with a cast. A tuple says
-	 * the same thing the emitter already guarantees - this middleware is only ever emitted for a route
-	 * declaring at least one request media type - and removes the cast rather than typing around it.
-	 */
-	branches: readonly [
-		readonly [mediaType: string, target: BodyTarget],
-		...(readonly [mediaType: string, target: BodyTarget])[],
-	],
-): MiddlewareHandler<E, string, { in: { json: input<S> }; out: { json: output<S> } }> {
-	return async (c, next) => {
-		const declared = (c.req.header("content-type") ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
-		const matched = branches.find(([mediaType]) => mediaType.toLowerCase() === declared);
-		const [, target] = matched ?? branches[0];
-		/**
-		 * **Registered against the body slot whichever parser runs**, so the validated body is
-		 * published under one target and the handler reads it exactly as it reads a single-media-type
-		 * one. Hono's `validator` is what `@hono/zod-validator` is built on, so this is the same
-		 * extraction, the same `HTTPException` on malformed JSON, and the same default rejection.
-		 *
-		 * **Hono's own `validator` is deliberately not called here.** Its target fixes the reader at
-		 * registration time, and the whole point of this function is that the reader is chosen when the
-		 * request arrives. What it does instead is reproduce `validator`'s observable behaviour for both
-		 * targets: {@link readBody} performs the same two extractions and raises the same
-		 * `HTTPException` on malformed JSON, and the rejection below is `zValidator`'s own.
-		 *
-		 * Annotated rather than inlined because `Context` is invariant in its environment and in its
-		 * `Input`. Same reason `RouteDeps` is parameterised.
-		 */
-		const parse: MiddlewareHandler<
-			E,
-			string,
-			{ in: { json: input<S> }; out: { json: output<S> } }
-		> = async (ctx, proceed) => {
-			const raw = await readBody(ctx, target);
-			const result =
-				raw === UNREADABLE ? await unreadableResult(schema) : await schema.safeParseAsync(raw);
-			const response = invalid(result, ctx);
-			if (response !== undefined) return response;
-			// `zValidator`'s own answer when a hook declines to, kept identical so a dispatched route
-			// and a single-media-type one reject a bad body the same way.
-			if (!result.success) return ctx.json(result, 400);
-			ctx.req.addValidatedData(BODY_TARGET, ("data" in result ? result.data : undefined) ?? {});
-			await proceed();
-			return undefined;
-		};
-		return parse(c, next);
-	};
-}
-
-/**
- * Validate a body the document says is OPTIONAL, and let a request carrying none through.
- *
- * **`requestBody.required: false` means a request with no body is one the contract permits**, and a
- * plain `zValidator` refused it. Measured against @hono/zod-validator 0.9.0 and hono 4.12.26: a
- * `POST` with `content-type: application/json` and no body answered **400 `Malformed JSON in request
- * body`** as `text/plain` - raised before the `invalid` hook, so outside the app's error envelope
- * entirely. A service refusing what its own document allows, in a shape that document forbids.
- *
- * **Nothing is published when the body is absent**, so `c.req.valid(...)` reads `undefined` and the
- * handler is told the truth. That is why an optional body is a NAMED property on the input rather
- * than merged into it: a merge has no way to say "these are here only sometimes" without making
- * every one of them optional, which is a weaker and different claim about the body that IS sent.
- *
- * A body that is present but unreadable still fails, through `invalid`, so the app's envelope holds.
- */
-export function optionalBody<E extends Env, S extends ZodType>(
-	schema: S,
-	invalid: <P extends string, I extends Input>(
-		result: { readonly success: boolean },
-		c: Context<E, P, I>,
-	) => Response | undefined,
-	target: BodyTarget,
-): MiddlewareHandler<
-	E,
-	string,
-	{ in: { json: input<S> | undefined }; out: { json: output<S> | undefined } }
-> {
-	return async (c, next) => {
-		if (!hasBody(c)) {
-			await next();
-			return undefined;
-		}
-		const raw = await readBody(c, target);
-		const result =
-			raw === UNREADABLE ? await unreadableResult(schema) : await schema.safeParseAsync(raw);
-		const response = invalid(result, c as never);
-		if (response !== undefined) return response;
-		if (!result.success) return c.json(result, 400);
-		c.req.addValidatedData(BODY_TARGET, ("data" in result ? result.data : undefined) ?? {});
-		await next();
-		return undefined;
-	};
-}
-
-/**
- * Whether the request carries a body at all.
- *
- * Both halves are load-bearing. The platform reports `null` for a request sent without one, and a
- * caller may instead send `content-length: 0`, which is a body of no bytes and reads the same way to
- * anything downstream. Neither alone covers what arrives.
- */
-function hasBody(c: Context): boolean {
-	if (c.req.raw.body === null) return false;
-	return (c.req.header("content-length") ?? "").trim() !== "0";
-}
 
 /**
  * What the app provides. One object, passed once, rather than a module the generated file imports by