typespec-hono 0.21.0 → 0.23.0

package/dist/src/app.js

@@ -1,5 +1,266 @@
-import { renderSecurity } from "./security.js";
-import { isRawBinaryMediaType, objectKey, } from "typespec-http-zod";
+import { isRawBinaryMediaType, jsDocComment, objectKey, } from "typespec-http-zod";
+/**
+ * Hono's status codes, group by group, exactly as `hono/utils/http-status` declares them.
+ *
+ * **The generated route needs the LITERALS, not only the type.** A range arm is served from a
+ * `switch` on the result's status, and TypeScript narrows the result to one member only through a
+ * `case` label per literal: a type guard narrows the status and leaves the result a union, and
+ * merging the range into `default` pairs every body with every status. Both measured on hono 4.13.1.
+ *
+ * `test/status-codes.test.ts` holds these equal to Hono's own unions, so a status Hono adds fails a
+ * test rather than silently falling out of a range.
+ */
+export const STATUS_GROUPS = {
+    1: { type: "InfoStatusCode", codes: [100, 101, 102, 103] },
+    2: { type: "SuccessStatusCode", codes: [200, 201, 202, 203, 204, 205, 206, 207, 208, 226] },
+    3: { type: "RedirectStatusCode", codes: [300, 301, 302, 303, 304, 305, 306, 307, 308] },
+    4: {
+        type: "ClientErrorStatusCode",
+        codes: [
+            400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418,
+            421, 422, 423, 424, 425, 426, 428, 429, 431, 451,
+        ],
+    },
+    5: {
+        type: "ServerErrorStatusCode",
+        codes: [500, 501, 502, 503, 504, 505, 506, 507, 508, 510, 511],
+    },
+};
+/**
+ * Where every generated file imports its runtime from: the copy this package writes beside them.
+ *
+ * Declared here, where the import is rendered, and re-exported by the emitter that writes the file.
+ */
+export const DEFAULT_RUNTIME_MODULE = "./runtime.gen.js";
+/** Hono's `ContentlessStatusCode`: a status that cannot carry a body, so `c.json` refuses it. */
+export const CONTENTLESS_STATUS_CODES = [101, 204, 205, 304];
+/** A media type whose body is a JSON value, served with `c.json`. The library's own rule. */
+function isJsonMediaType(type) {
+    return /^application\/(json|.*\+json)$/.test(type);
+}
+function bodyServingOf(member) {
+    const { response, mediaType } = member;
+    if (response.schema === undefined || mediaType === undefined)
+        return "none";
+    if (response.streamed)
+        return "stream";
+    if (response.binary)
+        return "binary";
+    if (isJsonMediaType(mediaType))
+        return "json";
+    /**
+     * **A string body under a non-JSON media type IS the text**, so it is validated and served as is.
+     * Any other body under one - a model as `application/xml` - has no serialisation this emitter can
+     * derive, so the handler supplies the text and it is served unvalidated, which the
+     * `unvalidated-response-media-type` warning says out loud.
+     */
+    return response.textual ? "text" : "unvalidated";
+}
+function membersOf(entry) {
+    return entry.route.responses.flatMap((response, index) => {
+        const schemaName = entry.names.arms[index]?.schema;
+        if (response.contentTypes.length === 0) {
+            return [{ response, schemaName, mediaType: undefined, choosesMediaType: false }];
+        }
+        /**
+         * The handler names the media type where the status offers several, and where the document names
+         * only a wildcard range, which is not a type a response can be sent as.
+         */
+        const choosesMediaType = response.contentTypes.length > 1 || response.contentTypes.some(isMediaRange);
+        return response.contentTypes.map((mediaType) => ({
+            response,
+            schemaName,
+            mediaType,
+            choosesMediaType,
+        }));
+    });
+}
+/** A media range such as `image/*`, rather than a type a response can be sent as. */
+function isMediaRange(mediaType) {
+    return mediaType.endsWith("/*");
+}
+/**
+ * The type of the `contentType` a handler names for a member.
+ *
+ * **A range is typed as the types inside it**: `image/*` is `` `image/${string}` ``, so `text/html`
+ * under it does not compile, and TypeScript still narrows a literal member away from it. Only the
+ * full range is `string`.
+ */
+function contentTypeTypeOf(mediaType) {
+    if (!isMediaRange(mediaType))
+        return JSON.stringify(mediaType);
+    if (mediaType === "*/*")
+        return "string";
+    return `\`${mediaType.slice(0, -1)}\${string}\``;
+}
+/** The Hono group a status key's codes belong to. */
+function groupOf(status) {
+    const digit = typeof status === "number" ? Math.floor(status / 100) : Number(String(status)[0]);
+    return digit >= 1 && digit <= 5 ? STATUS_GROUPS[digit] : undefined;
+}
+/**
+ * The codes a status key answers with, as `case` labels, or `"default"` for the catch-all.
+ *
+ * **A range excludes what is declared more precisely**, because OpenAPI resolves an exact code before
+ * its range and `armFor` does the same: a `404` beside a `4XX` is the `404`'s. A bodied range also
+ * excludes the statuses that cannot carry a body.
+ */
+function caseLabelsOf(response, route) {
+    const { status } = response;
+    if (status === "default")
+        return "default";
+    if (typeof status === "number")
+        return [status];
+    const exact = new Set(route.responses.flatMap((candidate) => typeof candidate.status === "number" ? [candidate.status] : []));
+    const contentless = new Set(response.schema === undefined ? [] : CONTENTLESS_STATUS_CODES);
+    return (groupOf(status)?.codes ?? []).filter((code) => !exact.has(code) && !contentless.has(code));
+}
+/**
+ * Serve a handler's `result` for every response the operation declares, as statements at `depth`.
+ *
+ * **One `case` per status literal, and one Hono call per declared response.** `c.json(body, 404)` is
+ * what gives `hc` a typed body for a 404, so the route serves each status through its own call rather
+ * than through one call over the union, which measured as a single endpoint pairing every body with
+ * every status.
+ *
+ * **Every served body is the PARSED body.** `servedBody` checks it against the schema the document
+ * publishes for that status and throws `ResponseContractError` when it does not match, failures
+ * included, and what is sent is the parse result - so a field the schema does not declare does not
+ * reach the wire.
+ */
+function servingLines(entry, depth, uses) {
+    const indent = "\t".repeat(depth);
+    const operationId = JSON.stringify(entry.route.operationId);
+    const members = membersOf(entry);
+    const lines = [`${indent}switch (result.status) {`];
+    let servesDefault = false;
+    for (const response of entry.route.responses) {
+        const labels = caseLabelsOf(response, entry.route);
+        if (labels !== "default" && labels.length === 0)
+            continue;
+        if (labels === "default") {
+            servesDefault = true;
+            lines.push(`${indent}\tdefault: {`);
+        }
+        else {
+            lines.push(...labels.map((code) => `${indent}\tcase ${code}:`));
+            lines[lines.length - 1] = `${lines.at(-1) ?? ""} {`;
+        }
+        const status = labels !== "default" && labels.length === 1 ? String(labels[0]) : "result.status";
+        const own = members.filter((member) => member.response === response);
+        if (!own.some((member) => member.choosesMediaType)) {
+            for (const member of own) {
+                lines.push(`${indent}\t\t${serveCall(member, status, operationId, uses)}`);
+            }
+        }
+        else {
+            /**
+             * **Exact types by `case`, then ranges by `mediaTypeWithin`, then a throw.** A `case "image/*"`
+             * would compare the range's own spelling and never match the `image/png` the handler is typed
+             * to name. Every `case` returns, so after the switch TypeScript has already narrowed the
+             * result to the range members, whose bodies are served the same way.
+             */
+            const exact = own.filter((member) => member.mediaType !== undefined && !isMediaRange(member.mediaType));
+            if (exact.length > 0) {
+                lines.push(`${indent}\t\tswitch (result.contentType) {`);
+                for (const member of exact) {
+                    lines.push(`${indent}\t\t\tcase ${JSON.stringify(member.mediaType)}:`);
+                    lines.push(`${indent}\t\t\t\t${serveCall(member, status, operationId, uses)}`);
+                }
+                lines.push(`${indent}\t\t}`);
+            }
+            for (const member of own) {
+                if (member.mediaType === undefined || !isMediaRange(member.mediaType))
+                    continue;
+                uses.runtime.add("mediaTypeWithin");
+                lines.push(`${indent}\t\tif (mediaTypeWithin(result.contentType, ${JSON.stringify(member.mediaType)})) ${serveCall(member, status, operationId, uses)}`);
+            }
+            uses.runtime.add("UndeclaredStatusError");
+            lines.push(`${indent}\t\tthrow new UndeclaredStatusError(${operationId}, result);`);
+        }
+        lines.push(`${indent}\t}`);
+    }
+    if (!servesDefault) {
+        /**
+         * **Unreachable from a typed handler**: every declared status has a `case`, so `result` is
+         * `never` here. A cast, or untyped data from a service binding, is what arrives - and serving
+         * it would publish a status the document does not declare.
+         */
+        uses.runtime.add("UndeclaredStatusError");
+        lines.push(`${indent}\tdefault:`);
+        lines.push(`${indent}\t\tthrow new UndeclaredStatusError(${operationId}, result);`);
+    }
+    lines.push(`${indent}}`);
+    return lines;
+}
+/** The one Hono call that serves one member, as a `return` statement. */
+function serveCall(member, status, operationId, uses) {
+    const { response, mediaType } = member;
+    const serving = bodyServingOf(member);
+    const headers = [];
+    /**
+     * **`Content-Type` wherever `c.json` would not already say it.** `c.json` writes
+     * `application/json`; a `+json` type such as `application/problem+json` has to be stated, and
+     * `c.body` states nothing. The key is spelled `Content-Type` because Hono merges its own default
+     * under exactly that key, so a lowercase spelling would send both.
+     */
+    if (mediaType !== undefined && serving !== "none" && mediaType !== "application/json") {
+        const value = member.choosesMediaType || mediaType.includes("*")
+            ? "result.contentType"
+            : JSON.stringify(mediaType);
+        headers.push(`"Content-Type": ${value}`);
+    }
+    const allOptional = response.headers.every((header) => header.optional);
+    for (const header of response.headers) {
+        const key = JSON.stringify(header.name);
+        headers.push(`${key}: result.headers${allOptional ? "?." : ""}[${key}]`);
+    }
+    if (headers.length > 0)
+        uses.runtime.add("headersOf");
+    const headersArgument = headers.length === 0 ? "" : `, headersOf({ ${headers.join(", ")} })`;
+    const validated = () => {
+        uses.runtime.add("servedBody");
+        return `servedBody(${member.schemaName ?? "undefined"}, result.body, ${operationId}, ${status})`;
+    };
+    switch (serving) {
+        case "none":
+            return `return c.body(null, ${status}${headersArgument});`;
+        case "json":
+            return `return c.json(${validated()}, ${status}${headersArgument});`;
+        case "text":
+            return `return c.body(${validated()}, ${status}${headersArgument});`;
+        default:
+            return `return c.body(result.body, ${status}${headersArgument});`;
+    }
+}
+/**
+ * A member's status as a TypeScript type: disjoint from every other member's, by construction.
+ *
+ * **Disjoint is the property that makes a wrong body a compile error.** Were `default` allowed to
+ * overlap a declared status, `{ status: 404, body: <the default arm's body> }` would type-check
+ * through the `default` member; measured, and the generated switch stopped compiling as well.
+ */
+function statusTypeOf(response, route) {
+    const { status } = response;
+    if (typeof status === "number")
+        return String(status);
+    const exact = route.responses.flatMap((candidate) => typeof candidate.status === "number" ? [String(candidate.status)] : []);
+    if (status !== "default") {
+        const group = groupOf(status);
+        if (group === undefined)
+            return "never";
+        const excluded = [
+            ...exact.filter((code) => groupOf(Number(code)) === group),
+            ...(response.schema === undefined ? [] : ["ContentlessStatusCode"]),
+        ];
+        return excluded.length === 0 ? group.type : `Exclude<${group.type}, ${excluded.join(" | ")}>`;
+    }
+    const ranges = route.responses.flatMap((candidate) => typeof candidate.status === "string" && candidate.status !== "default"
+        ? [groupOf(candidate.status)?.type ?? "never"]
+        : []);
+    const base = response.schema === undefined ? "StatusCode" : "ContentfulStatusCode";
+    return `Exclude<${base}, ${["InfoStatusCode", "UnofficialStatusCode", ...exact, ...ranges].join(" | ")}>`;
+}
 /**
  * The header every emitted file carries.
  *
@@ -16,56 +277,80 @@ export function generatedBanner(hint) {
 }
 /** A parameter name Hono can carry verbatim. Measured against Hono, not assumed. */
 const PLAIN_PATH_PARAMETER = /^[A-Za-z0-9_.~-]+$/;
+/** Text matched literally inside a Hono `{...}` parameter pattern. */
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^$()|[\]\\]/g, "\\$&");
+}
 /**
- * TypeSpec publishes `/widgets/{widget-id}`; Hono routes on `/widgets/:widget-id`.
- *
- * **This used to match `\w+`, so any parameter carrying a hyphen was left ALONE.**
- * `@path("thing-id")` produced the literal route `/things/{thing-id}`, mounted, counted by every arm
- * that counts routes, and reachable by nobody. It answered 404 to the only requests it was for. Hono
- * handles `:thing-id` and `:x.y` perfectly well; the narrow character class was ours.
- *
- * A name that is not plain is REFUSED rather than approximated, and the route stays at the literal
- * template so it matches nothing rather than matching the wrong thing.
- *
- * **This is about the NAME, not about RFC 6570 operators.** An earlier version of this comment
- * claimed `{+path}` or `{tag*}` would survive into the name and that `*` would become Hono's
- * wildcard. Measured, that is false: `@typespec/http` resolves the operator before this emitter sees
- * the path, and `@typespec/openapi3` strips it from the published document too, so both artefacts say
- * `/files{path}` and agree. What actually reaches here is a wire name from `@path("...")`, and the
- * forms that fail are a space, `+` and `!`. `*` is rejected by `@typespec/http` before it arrives.
- *
- * **This runs at RENDER time, not during collection.** It used to run inside `collectRoutes`, which
- * put one framework's spelling into the shared intermediate representation and refused the whole
- * operation (validators included) over a template no router could mount. What a request body must
- * look like does not depend on that.
- */
-export function toHonoPath(template, refuse, 
-/**
- * Wire names the document says carry RFC 6570 reserved expansion, so their value may contain `/`.
- *
- * **A hierarchical identifier is ONE value, not several segments.** An Obsidian note is
- * `areas/health.md`; an S3 key and a GitHub file path are the same shape. A router that stops at
- * the first `/` binds `areas` and 404s the rest. Hono spells the greedy form `:name{.+}`.
- *
- * Read from `EmittedRoute.reservedPathParameters`, which the library resolves from `allowReserved`
- * on the parameter. **Never from the template**: the operator does not survive to `route.path`,
- * `@typespec/http` strips it, and it can also be set with no operator in the template at all, so
- * the template is a derived artefact rather than the source of truth.
+ * The Hono route for a route template, from the segments `typespec-http-zod` reads out of the
+ * operation's RFC 6570 `uriTemplate`.
+ *
+ * **This used to convert `route.path`, which has every operator stripped**, so `array{.param*}`,
+ * `array{;param}` and `optional{/name}` were mounted as `array:param` and `optional:name`, which Hono
+ * does not match at all. Measured by request: 31 of the URIs `@typespec/http-specs` `routes` and
+ * `parameters/path` declare answered 404 from a server generated from them.
+ *
+ * - A whole-segment expression is `:name`; a reserved or exploding `/` one crosses `/`, so it is
+ *   `:name{.+}` (Hono's spelling of greedy); an optional last segment is `:name?`.
+ * - An expression written beside literal text, or with a label or matrix operator, is a pattern
+ *   parameter matching the whole segment: `:param{array\.[^\x2F]*}`. The captured text is the
+ *   segment, and the path validator undoes the expansion. `\x2F` rather than `/`, so the mounted
+ *   path still splits into its segments on `/` for the ordering and sub-app rules below.
+ *
+ * **A name Hono cannot carry is REFUSED rather than approximated**, and so is a segment holding two
+ * expressions, which no segment router can split. The segment stays literal, so it matches nothing
+ * rather than the wrong thing. A space, `+` and `!` are the characters that fail; a hyphen, a dot and
+ * a tilde do not.
+ *
+ * **This runs at RENDER time, not during collection**, so what a request body must look like never
+ * depends on whether one framework's router can express the path.
  */
-reserved = new Set()) {
-    return template.replace(/\{([^}]+)\}/g, (match, name) => {
-        /**
-         * **The name check comes FIRST and is unconditional.** A name Hono cannot carry is refused
-         * whether or not it is reserved: greedy matching does not make a space or a `+` in a parameter
-         * name expressible, and letting one through because another flag was set would mount a route
-         * matching the wrong requests rather than one that fails.
-         */
+export function toHonoPath(segments, refuse) {
+    const template = `/${segments
+        .map((segment) => segment.kind === "expression"
+        ? `${segment.prefix}{${segment.operator}${segment.parameter}${segment.explode ? "*" : ""}}${segment.suffix}`
+        : segment.text)
+        .join("/")}`;
+    const parts = segments.map((segment, index) => {
+        if (segment.kind === "literal")
+            return segment.text;
+        if (segment.kind === "unsupported") {
+            refuse(template, segment.text);
+            return segment.text;
+        }
+        const name = segment.parameter;
         if (!PLAIN_PATH_PARAMETER.test(name)) {
             refuse(template, name);
-            return match;
+            return `{${name}}`;
+        }
+        const whole = segment.prefix === "" &&
+            segment.suffix === "" &&
+            segment.operator !== "." &&
+            segment.operator !== ";";
+        if (whole) {
+            if (segment.reserved || (segment.operator === "/" && segment.explode))
+                return `:${name}{.+}`;
+            return segment.optional && index === segments.length - 1 ? `:${name}?` : `:${name}`;
         }
-        return reserved.has(name) ? `:${name}{.+}` : `:${name}`;
+        const leader = segment.operator === "." || segment.operator === ";" ? escapeRegExp(segment.operator) : "";
+        const body = segment.reserved ? ".*" : "[^\\x2F]*";
+        return `:${name}{${escapeRegExp(segment.prefix)}${leader}${body}${escapeRegExp(segment.suffix)}}`;
     });
+    return `/${parts.join("/")}`;
+}
+/**
+ * The document's `security` as a TypeScript literal, for the generated `authorize` call. `{}` is the
+ * anonymous alternative, written out so an `authorize` applying the documented rule (any one
+ * requirement, every scheme within it) admits a caller who presents nothing.
+ */
+function renderSecurity(requirements) {
+    return `[${requirements
+        .map((requirement) => Object.keys(requirement).length === 0
+        ? "{}"
+        : `{ ${Object.entries(requirement)
+            .map(([scheme, scopes]) => `${JSON.stringify(scheme)}: [${scopes.map((scope) => JSON.stringify(scope)).join(", ")}]`)
+            .join(", ")} }`)
+        .join(", ")}]`;
 }
 /**
  * The verb Hono actually dispatches under.
@@ -120,12 +405,23 @@ const VALIDATOR_TARGET = {
  * justifies, so it keeps the existing behaviour rather than acquiring a new one on the way past. That
  * gap is real and is stated in the README rather than papered over here.
  */
-function targetForMediaType(type) {
+function targetForMediaType(type, textual) {
     if (type === "application/x-www-form-urlencoded" || type.startsWith("multipart/"))
         return "form";
     // `application/json`, and the `+json` structured suffix RFC 6839 defines.
     if (type === "application/json" || type.endsWith("+json"))
         return VALIDATOR_TARGET.body;
+    /**
+     * **A body the document says IS text is read as text**, `@body body: string` under `text/plain`
+     * being the ordinary case. `requestTextual` is the library's answer about the TYPE, so the same
+     * media type carrying a model stays unparseable and keeps its warning: `text/plain` says how the
+     * value is framed, not what it is.
+     *
+     * Measured before this existed: such a route emitted no body middleware at all, so the body was
+     * never read and the handler was called with an empty input.
+     */
+    if (textual)
+        return "text";
     return undefined;
 }
 /**
@@ -146,13 +442,13 @@ function targetForMediaType(type) {
  * package should make. Naming them is what stops a consumer believing a route is validated when it
  * is not -- the previous behaviour said nothing and rejected them.
  */
-function bodyValidationFor(contentTypes) {
+function bodyValidationFor(contentTypes, textual) {
     if (contentTypes.length === 0)
         return { byType: [["", VALIDATOR_TARGET.body]], unparseable: [] };
     const byType = [];
     const unparseable = [];
     for (const type of contentTypes) {
-        const target = targetForMediaType(type);
+        const target = targetForMediaType(type, textual);
         if (target === undefined)
             unparseable.push(type);
         else
@@ -164,9 +460,9 @@ function bodyValidationFor(contentTypes) {
  * 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
+ * **Because the runtime module was a contract too, and it was the one that broke quietly.** An
+ * application could point `runtime-module` at a module of its own, and everything the generated file
+ * imported from there was something that application had 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
@@ -222,7 +518,7 @@ const SYNC = { validationFunction: (schema: z.ZodType, value: unknown) => schema
 
 `;
 const BODY_READER = `/** The two ways Hono can read a request body: \`c.req.json()\` and \`c.req.parseBody()\`. */
-type BodyTarget = "json" | "form";
+type BodyTarget = "json" | "form" | "text";
 
 /**
  * A body that is not what its content type claims.
@@ -236,7 +532,10 @@ 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();
+		if (target === "form") return await c.req.parseBody({ all: true });
+		// A text body IS the text: it is validated as the string the caller sent, not parsed first.
+		if (target === "text") return await c.req.text();
+		return await c.req.json();
 	} catch {
 		return UNREADABLE;
 	}
@@ -375,6 +674,47 @@ function validateOptionalBody<E extends Env, S extends z.ZodType>(
 	};
 }
 
+`;
+/**
+ * The caller context, established in middleware and handed to the handler.
+ *
+ * **Middleware, because a refusal returned inside the final handler erases the route's typed
+ * responses** - see `registrations`. **A per-request `WeakMap`, because `c.set` cannot carry it
+ * without leaking into the application's types.** Setting a variable needs the route's environment to
+ * declare it, and Hono's `Context` is invariant in its environment through `set`: a generated
+ * extension made every \`deps\` hook the application wrote against its own environment unassignable,
+ * measured as \`TS2345\` at the application's call site. The map keys on the request's own
+ * \`Context\`, which Hono passes unchanged from middleware to handler, including through a mounted
+ * sub-app.
+ */
+const CONTEXT_MIDDLEWARE = `\tconst contexts = new WeakMap<object, { readonly value: C }>();
+	const contextFor =
+		(authentication: "none" | "optional" | "required"): MiddlewareHandler<AppEnv> =>
+		async (c, next) => {
+			const ctx = deps.context(c, authentication);
+			if (ctx === null) return deps.noContext(c);
+			contexts.set(c, { value: ctx });
+			await next();
+			return undefined;
+		};
+	const contextOf = (c: object): C => {
+		const held = contexts.get(c);
+		if (held === undefined) throw new Error("typespec-hono: no caller context was established for this request");
+		return held.value;
+	};
+
+`;
+/** A caller accepting none of the media types a negotiated route offers is refused here. */
+const ACCEPTABLE_MIDDLEWARE = `\tconst acceptable =
+		(offered: readonly string[]): MiddlewareHandler<AppEnv> =>
+		async (c, next) => {
+			if (selectContentType(c.req.header("accept"), offered) === undefined) {
+				return deps.notAcceptable(c, offered);
+			}
+			await next();
+			return undefined;
+		};
+
 `;
 /**
  * How an unparsed body reaches the handler, and as what.
@@ -558,16 +898,7 @@ export function renderApp(emitted, refuse,
  * the document publishes `/api/v1/accounts`. Mounting at the root made every client generated from
  * the document, and every "try it" in a rendered document, 404.
  */
-basePaths = [], 
-/**
- * What the DOCUMENT says a caller must satisfy, per operation id.
- *
- * **Resolved by the caller rather than read off `EmittedRoute`**, because which schemes an
- * operation accepts is a fact about the HTTP program and not part of the validator IR the library
- * publishes. Keeping it out of that IR is what stops a Hono concern leaking into a package whose
- * audience is wider.
- */
-securityFor) {
+basePaths = []) {
     const mounted = emitted.routes.flatMap((route) => {
         const names = emitted.schemaNames.get(route.operationId);
         // The library declares a `Responses` const for every operation, so a missing entry is a bug in
@@ -590,7 +921,7 @@ securityFor) {
              * 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 validation = bodyValidationFor(route.requestContentTypes);
+            const validation = bodyValidationFor(route.requestContentTypes, route.requestTextual);
             if (validation.unparseable.length > 0) {
                 refuse.unvalidatableMediaType(route, validation.unparseable);
             }
@@ -685,8 +1016,82 @@ type Fields<T> = string extends keyof T ? ([T[string]] extends [never] ? unknown
      */
     const validates = entries.some((entry) => entry.validators.filter(([target]) => entry.body === undefined || target !== VALIDATOR_TARGET.body).length > 0);
     const syncHelper = validates ? SYNC_PARSE : "";
+    /**
+     * **One result type per operation: the union of every response its document declares.**
+     *
+     * A handler returns `{ status, body, headers }` for whichever response it means, success or
+     * failure. That is `c.json(body, status, headers)` as data - what `@hono/zod-openapi` requires of a
+     * handler as a union of typed responses - and the document's own Responses Object: keyed by status,
+     * each with its body and its headers.
+     *
+     * **The return type used to be the SUCCESS body alone.** The arms named every failure the document
+     * declares and no handler could return one, so failures were thrown past the generated code into
+     * `onError`, where no declared status or body was checked. Nine of a real operation's ten arms were
+     * unreachable that way.
+     *
+     * Data rather than a `Response`, so a handler stays transport-neutral: the same object can cross a
+     * Workers service binding and serve `typespec-http-mcp`'s tools.
+     */
+    const resultTypes = entries.map((entry) => {
+        for (const response of entry.route.responses) {
+            const unvalidated = membersOf(entry)
+                .filter((member) => member.response === response && bodyServingOf(member) === "unvalidated")
+                .flatMap((member) => (member.mediaType === undefined ? [] : [member.mediaType]));
+            if (unvalidated.length > 0) {
+                refuse.unvalidatedResponseMediaType(entry.route, response.status, unvalidated);
+            }
+        }
+        const members = membersOf(entry).map((member) => {
+            const { response } = member;
+            const fields = [`readonly status: ${statusTypeOf(response, entry.route)}`];
+            if (member.choosesMediaType && member.mediaType !== undefined) {
+                fields.push(`readonly contentType: ${contentTypeTypeOf(member.mediaType)}`);
+            }
+            /**
+             * **What the handler SUPPLIES for this body, which is not always what the schema infers.** A
+             * stream or raw binary body is handed to Hono unread, a model under a non-JSON media type is text
+             * the handler serialised, and everything else is the producer's view of the schema.
+             */
+            switch (bodyServingOf(member)) {
+                case "none":
+                    fields.push("readonly body?: undefined");
+                    break;
+                case "stream":
+                    fields.push("readonly body: ReadableStream");
+                    break;
+                case "binary":
+                    fields.push("readonly body: ReadableStream | Uint8Array<ArrayBuffer> | ArrayBuffer");
+                    break;
+                case "unvalidated":
+                    fields.push("readonly body: string");
+                    break;
+                default:
+                    fields.push(`readonly body: Produced<z.infer<typeof ${member.schemaName}>>`);
+            }
+            if (response.headers.length > 0) {
+                /**
+                 * Keyed by the WIRE name, as the document publishes it. `headers` itself is optional only
+                 * when every header in it is, so a response declaring a required header cannot be returned
+                 * without one.
+                 */
+                const every = response.headers.every((header) => header.optional);
+                const rendered = response.headers
+                    .map((header) => header.optional
+                    ? `readonly ${objectKey(header.name)}?: ${header.type} | undefined`
+                    : `readonly ${objectKey(header.name)}: ${header.type}`)
+                    .join("; ");
+                fields.push(`readonly headers${every ? "?" : ""}: { ${rendered} }`);
+            }
+            return `{ ${fields.join("; ")} }`;
+        });
+        const name = `${capitaliseId(entry.route.operationId)}Result`;
+        const body = members.length <= 1
+            ? ` ${members[0] ?? "never"}`
+            : members.map((member) => `\n\t| ${member}`).join("");
+        return `export type ${name} =${body};`;
+    });
     const methods = entries.map((entry) => {
-        const { route, names } = entry;
+        const { route } = entry;
         /**
          * A negotiated member's `accept` is not in its validator (the negotiation supplies it) but it
          * IS in the operation's declared input, so the interface has to keep it. The literal is known
@@ -702,75 +1107,18 @@ type Fields<T> = string extends keyof T ? ([T[string]] extends [never] ? unknown
                 ? negotiated
                 : `${validated} & ${negotiated}`;
         /**
-         * **The RETURN type is the producer's view; the input type is left exactly as it arrives.**
-         *
-         * A handler receives whatever the validator let through, so an input carrying
-         * `[key: string]: unknown`, `T | undefined` on an optional, and mutable arrays is an honest
-         * description of the value in hand. Returning is the opposite direction: the handler supplies
-         * something the application already holds, and each of those becomes an obligation rather than
-         * a description. See `Produced` below for what that cost, measured.
-         *
-         * `typespec-http-zod` fixes the same three things on its contract types. None of it reaches
-         * 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.
-         */
-        /**
-         * **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.
+         * **A PROPERTY signature, not a method signature, and the difference is a check.** TypeScript
+         * compares a method signature's parameters bivariantly, so a handler declaring a richer caller
+         * context than `deps.context` produces compiled against the method form - measured - and failed
+         * against this one.
          */
-        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}>>;`;
+        const doc = jsDocComment(route.summary, "\t");
+        return `${doc}\treadonly ${objectKey(route.operationId)}: (ctx: C, input: ${input ?? EMPTY_INPUT}) => Awaitable<${capitaliseId(route.operationId)}Result>;`;
     });
-    /**
-     * Emitted only when an operation actually returns something, because a generated file has to pass
-     * `noUnusedLocals` like any other - the lint that has already failed this emitter twice over an
-     * import written for a construct the service did not use.
-     *
-     * **Decided from the routes, not by searching the rendered text.** Asking whether the output
-     * 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 returnsAnything = entries.some((entry) => entry.names.response !== undefined);
+    const returnsAnything = entries.some((entry) => membersOf(entry).some((member) => {
+        const serving = bodyServingOf(member);
+        return serving === "json" || serving === "text";
+    }));
     const declaredHelper = returnsAnything
         ? `/**
  * What a handler must SUPPLY, as opposed to what it receives.
@@ -828,7 +1176,7 @@ type Produced<T> = T extends (...args: never[]) => unknown
 
 `
         : "";
-    const aliases = entries.map((entry) => `export type ${capitaliseId(entry.route.operationId)}Handler = Operations[${JSON.stringify(entry.route.operationId)}];`);
+    const aliases = entries.map((entry) => `export type ${capitaliseId(entry.route.operationId)}Handler<C = unknown> = Operations<C>[${JSON.stringify(entry.route.operationId)}];`);
     /**
      * **Which resources get a sub-app, and which routes stay on the root.**
      *
@@ -871,6 +1219,7 @@ type Produced<T> = T extends (...args: never[]) => unknown
         const slot = `${registrationVerbOf(route.verb)} ${route.path}`;
         slots.set(slot, [...(slots.get(slot) ?? []), group]);
     }
+    const uses = { runtime: new Set() };
     const registrations = [...slots.values()].map((groupsInSlot) => {
         const headGroups = groupsInSlot.filter((g) => g[0].route.verb === "HEAD");
         const plainGroups = groupsInSlot.filter((g) => g[0].route.verb !== "HEAD");
@@ -888,7 +1237,7 @@ type Produced<T> = T extends (...args: never[]) => unknown
         /** A HEAD with no GET beside it: registered under GET, and guarded so only a HEAD reaches it. */
         const headOnly = plainGroups.length === 0 && headGroups.length > 0;
         const method = HONO_METHOD[registrationVerbOf(route.verb)] ?? "on";
-        const path = toHonoPath(route.path, (template, name) => refuse.unsupportedPathTemplate(route, template, name), new Set(route.reservedPathParameters));
+        const path = toHonoPath(route.pathSegments, (template, name) => refuse.unsupportedPathTemplate(route, template, name));
         /**
          * A route inside a sub-app is registered RELATIVE to the prefix it is mounted at.
          *
@@ -914,8 +1263,21 @@ type Produced<T> = T extends (...args: never[]) => unknown
          * all and rested entirely on `deps.context` returning null, which answers "is somebody here"
          * rather than "did they satisfy the scheme the contract names".
          */
-        const requirements = securityFor?.(route.verb, route.path) ?? [];
-        const gate = requirements.length === 0 ? [] : [`\t\tdeps.authorize(${renderSecurity(requirements)}),`];
+        /**
+         * Read from the route record, which carries the document's own `security` (`{}` for an
+         * anonymous alternative) and whether a caller is needed at all. **This package kept a second
+         * copy of that rule** in `security.ts`, because the library's once dropped `{}`; one copy now.
+         */
+        const gate = route.authentication === "none"
+            ? []
+            : [`\t\tdeps.authorize(${renderSecurity(route.security)}),`];
+        /**
+         * A query string written into the route itself identifies it as much as the path does, so a
+         * request without it is not a request for this operation: 404, as any unrouted request gets.
+         */
+        const literalQueryGuard = route.literalQuery.length === 0
+            ? []
+            : [`\t\tliteralQuery(${JSON.stringify(route.literalQuery)}),`];
         /**
          * A HEAD operation with no GET beside it is registered under GET, because that is the only verb
          * Hono dispatches. The guard keeps the registration honest: a real GET is not in the document,
@@ -948,8 +1310,33 @@ type Produced<T> = T extends (...args: never[]) => unknown
                 ...entry.body.branches.map(([type, target]) => `\t\t\t[${JSON.stringify(type)}, ${JSON.stringify(target)}],`),
                 "\t\t]),",
             ];
+        /**
+         * Whether the operation requires a caller, and NOTHING else about the caller.
+         *
+         * **This used to pass `"account"` or `"resource"`, chosen by how many path parameters the
+         * route had, and that was a rule no document states.** `@useAuth(NoAuth)` reaches OpenAPI as
+         * `security: []`, so "does this need a caller" is a contract fact and is generated. "Is this
+         * account-scoped or resource-scoped" is not: no OpenAPI keyword expresses it, and the
+         * path-parameter heuristic happened to fit the first consumer.
+         *
+         * **Middleware, after the validators, and never inline in the handler.** Hono reads a route's
+         * response types from its final handler, and one plain `Response` returned there collapses
+         * every typed response `hc` would otherwise see - measured, `res.json()` fell back to
+         * `unknown` for every status. A plain `Response` from middleware contributes nothing to those
+         * types, so the refusal moves there and the handler returns typed responses only.
+         */
+        const authentication = route.authentication;
+        /**
+         * Several operations, one route: the caller's `Accept` chooses which one answers, and a caller
+         * accepting none of them is refused in middleware for the same reason the context is.
+         */
+        const offers = group.length > 1
+            ? group.flatMap((member) => member.route.responseContentTypes.map((contentType) => ({ contentType, member })))
+            : [];
+        const offered = `[${offers.map((offer) => JSON.stringify(offer.contentType)).join(", ")}]`;
         const middleware = [
             ...(headOnly ? ["\t\theadOnly,"] : []),
+            ...literalQueryGuard,
             ...gate,
             ...validators
                 // The body's validator IS the middleware above; emitting a `zValidator` beside it would
@@ -957,43 +1344,12 @@ type Produced<T> = T extends (...args: never[]) => unknown
                 .filter(([target]) => entry.body === undefined || target !== VALIDATOR_TARGET.body)
                 .map(([target, name]) => `\t\tzValidator(${JSON.stringify(target)}, ${name}, deps.invalid, SYNC),`),
             ...bodyMiddleware,
+            `\t\tcontextFor(${JSON.stringify(authentication)}),`,
+            ...(offers.length > 0 ? [`\t\tacceptable(${offered}),`] : []),
         ];
-        /**
-         * Whether the operation requires a caller, and NOTHING else about the caller.
-         *
-         * **This used to pass `"account"` or `"resource"`, chosen by how many path parameters the
-         * route had, and that was a rule no document states.** `@useAuth(NoAuth)` reaches OpenAPI as
-         * `security: []`, so "does this need a caller" is a contract fact and is generated. "Is this
-         * account-scoped or resource-scoped" is not: no OpenAPI keyword expresses it, and the
-         * path-parameter heuristic happened to fit the first consumer.
-         */
         const body = [];
-        if (route.noAuth !== true) {
-            body.push(`\t\t\tconst ctx = deps.context(c, "required");`);
-            body.push("\t\t\tif (ctx === null) return deps.noContext(c);");
-        }
-        else {
-            /**
-             * **The same null check as an authenticated route, and it is what removes a CAST from
-             * generated output.** This used to emit `deps.context(c, "none") as Ctx`, because one
-             * signature returning `C | null` cannot express "this argument makes null impossible". A cast
-             * in generated code is worse than one in hand-written code: nobody reviews it, and it
-             * reappears on every compile.
-             *
-             * **Overloading `context` was tried and is worse.** It removes the cast from here and puts
-             * one in every consumer's `deps`, because an overloaded property type stops contextually
-             * typing a single implementation. Measured, the wiring consumer lost inference on every
-             * hook. Trading a cast in generated code for a cast in hand-written code is the wrong
-             * direction.
-             *
-             * Checking is also more honest than asserting: an app that returns null here has said it
-             * could not build a context, and the old cast handed the handler that null typed as `Ctx`.
-             */
-            body.push(`\t\t\tconst ctx = deps.context(c, "none");`);
-            body.push("\t\t\tif (ctx === null) return deps.noContext(c);");
-        }
         // A dispatched body is in `validators` under the body target like any other, so there is
-        // nothing extra to spread: `byContentType` published it there whichever parser ran.
+        // nothing extra to spread: the body middleware published it there whichever parser ran.
         // Same rule as `inputTypeOf`: the body is identified by its schema, not by its target.
         const bodyTarget = validators.find(([, name]) => name === entry.names.body)?.[0];
         const pieces = validators.map(([target]) => 
@@ -1011,7 +1367,16 @@ type Produced<T> = T extends (...args: never[]) => unknown
             const reader = rawBodyReaderFor(route.requestContentTypes);
             pieces.push(`${objectKey(route.rawBodyProperty)}: ${reader.call}`);
         }
-        const invoke = (member) => {
+        /**
+         * Call one operation's handler and serve what it returns, as statements at `depth` tabs.
+         *
+         * **Broken across lines rather than emitted as one.** Generated code is read far more often
+         * than it is written (in review, in a stack trace, in a diff) and a single call reached 219
+         * characters on a real service, against the 60-to-80 of every example in Hono's own
+         * documentation. A call with no input stays on one line.
+         */
+        const serve = (member, depth) => {
+            const indent = "\t".repeat(depth);
             // The member's own `accept` literal, which its input type requires and which the shared
             // validator no longer supplies. We know it exactly: it is the branch we are in.
             const own = group.length > 1 && member.route.accept !== undefined
@@ -1020,42 +1385,20 @@ type Produced<T> = T extends (...args: never[]) => unknown
                 ]
                 : [];
             const input = [...pieces, ...own];
-            /**
-             * **Broken across lines rather than emitted as one.** Generated code is read far more often
-             * than it is written (in review, in a stack trace, in a diff) and a single call reached 219
-             * characters on a real service, against the 60-to-80 of every example in Hono's own
-             * documentation. Nothing about the behaviour changes; a reader's ability to see it does.
-             *
-             * A call with no input stays on one line, because wrapping it would add ceremony to something
-             * already short.
-             */
-            /**
-             * **Indented literally, because the surrounding `+1 tab` only reaches the FIRST physical
-             * line.** A multi-line fragment keeps whatever tabs it was written with, so the depths here
-             * are absolute: the `return` sits at four, its arguments at five, and the handler's input
-             * properties at six.
-             */
-            const call = input.length === 0
+            const call = `handlersFor(c).${member.route.operationId}(contextOf(c), {`;
+            const invocation = input.length === 0
                 ? // An empty object, because every operation takes `(ctx, input)`. See `EMPTY_INPUT`.
-                    `handlersFor(c).${member.route.operationId}(ctx, {})`
-                : [
-                    `handlersFor(c).${member.route.operationId}(ctx, {`,
-                    ...input.map((piece) => `\t\t\t\t\t\t${piece},`),
-                    "\t\t\t\t\t})",
-                ].join("\n");
-            return input.length === 0
-                ? `deps.respond(c, ${member.names.responses}, await ${call})`
+                    [`${indent}const result = await ${call}});`]
                 : [
-                    `deps.respond(`,
-                    `\t\t\t\t\tc,`,
-                    `\t\t\t\t\t${member.names.responses},`,
-                    `\t\t\t\t\tawait ${call},`,
-                    "\t\t\t\t)",
-                ].join("\n");
+                    `${indent}const result = await ${call}`,
+                    ...input.map((piece) => `${indent}\t${piece},`),
+                    `${indent}});`,
+                ];
+            return [...invocation, ...servingLines(member, depth, uses)];
         };
         /**
          * Both verbs on one path: `c.req.method` still reads `HEAD` after Hono's rewrite, so one
-         * registration serves both and each operation keeps its own handler and its own response arms.
+         * registration serves both and each operation keeps its own handler and its own responses.
          * Hono strips the body on the HEAD branch itself.
          *
          * The HEAD branch is emitted FIRST because it is the narrower condition, and it returns, so the
@@ -1064,31 +1407,31 @@ type Produced<T> = T extends (...args: never[]) => unknown
         if (headBranch !== undefined) {
             const headEntry = headBranch[0];
             body.push(`\t\t\tif (c.req.method === "HEAD") {`);
-            body.push(`\t\t\t\treturn ${invoke(headEntry).replaceAll("\n", "\n\t")};`);
+            body.push(...serve(headEntry, 4));
             body.push("\t\t\t}");
         }
         if (group.length === 1) {
-            body.push(`\t\t\treturn ${invoke(entry)};`);
+            body.push(...serve(entry, 3));
         }
         else {
             /**
-             * Several operations, one route: the caller's `Accept` chooses which one answers.
-             *
              * The offered list and which operation serves each type are both read from the document.
-             * `selectContentType` applies RFC 9110 section 12.5.1 to them. It lives in the runtime rather than
-             * in `deps` because both halves are derivable, and an app forced to supply it would be
+             * `selectContentType` applies RFC 9110 section 12.5.1 to them. It lives in the runtime rather
+             * than in `deps` because both halves are derivable, and an app forced to supply it would be
              * re-implementing the standard.
              */
-            const offers = group.flatMap((member) => member.route.responseContentTypes.map((contentType) => ({ contentType, member })));
-            const offered = `[${offers.map((offer) => JSON.stringify(offer.contentType)).join(", ")}]`;
             body.push(`\t\t\tconst served = selectContentType(c.req.header("accept"), ${offered});`);
-            body.push(`\t\t\tif (served === undefined) return deps.notAcceptable(c, ${offered});`);
             for (const offer of offers) {
-                body.push(`\t\t\tif (served === ${JSON.stringify(offer.contentType)}) return ${invoke(offer.member)};`);
+                body.push(`\t\t\tif (served === ${JSON.stringify(offer.contentType)}) {`);
+                body.push(...serve(offer.member, 4));
+                body.push("\t\t\t}");
             }
-            // `selectContentType` only ever returns a member of the list it was given, so this is
-            // unreachable, and stating that is cheaper than a cast that would hide it if it were not.
-            body.push(`\t\t\treturn deps.notAcceptable(c, ${offered});`);
+            /**
+             * Unreachable: `acceptable` refused every request whose `Accept` matches none of these, and
+             * `selectContentType` only returns a member of the list it was given. Thrown rather than
+             * answered, because a plain `Response` here would erase every typed response on the route.
+             */
+            body.push(`\t\t\tthrow new Error(${JSON.stringify(`typespec-hono: no operation on ${route.verb} ${route.path} serves the negotiated media type`)});`);
         }
         /**
          * **`app.on` takes the METHOD first, and we were not passing one.** Only five verbs have a
@@ -1115,7 +1458,7 @@ type Produced<T> = T extends (...args: never[]) => unknown
             "\t\t\t},",
             "\t\t)",
         ].join("\n");
-        return { target, text, headOnly };
+        return { target, path: registeredPath, text, headOnly };
     });
     /**
      * Every identifier this file names, imported from the module that declares it.
@@ -1136,7 +1479,12 @@ type Produced<T> = T extends (...args: never[]) => unknown
      * Splitting on the language's own identifier rule and testing membership has neither failure: no
      * metacharacter can be misread, and `Foo` cannot match `FooExtra`.
      */
-    const rendered = [...registrations.map((r) => r.text), ...methods, ...aliases].join("\n");
+    const rendered = [
+        ...registrations.map((r) => r.text),
+        ...resultTypes,
+        ...methods,
+        ...aliases,
+    ].join("\n");
     const mentioned = new Set(rendered.match(/[A-Za-z_$][A-Za-z0-9_$]*/g) ?? []);
     const referenced = [
         ...new Set(entries.flatMap((entry) => [
@@ -1144,8 +1492,7 @@ type Produced<T> = T extends (...args: never[]) => unknown
             entry.names.query,
             entry.names.header,
             entry.names.body,
-            entry.names.response,
-            entry.names.responses,
+            ...entry.names.arms.map((arm) => arm.schema),
         ].filter((name) => name !== undefined))),
     ]
         .filter((identifier) => mentioned.has(identifier))
@@ -1173,6 +1520,27 @@ type Produced<T> = T extends (...args: never[]) => unknown
      * bottom". A rule a reordering could break. A single expression cannot be reordered wrongly: the
      * sub-app is complete at the point it is mounted because it is its own initialiser.
      */
+    /**
+     * **A concrete path is registered before a templated one it would otherwise lose to.**
+     *
+     * Hono runs the first registered handler that matches, so `GET /items/:id` registered before
+     * `GET /items/plain` answered every request for `/items/plain` - measured, with the wrong handler's
+     * body. OpenAPI's Paths Object states the opposite rule: "concrete (non-templated) paths would be
+     * matched before their templated counterparts". Ordering the registrations is how a router that
+     * matches in order applies it. Otherwise the document's own order is kept, because the sort is
+     * stable.
+     */
+    registrations.sort((a, b) => {
+        const left = a.path.split("/");
+        const right = b.path.split("/");
+        for (let index = 0; index < Math.min(left.length, right.length); index++) {
+            const leftTemplated = (left[index] ?? "").startsWith(":");
+            const rightTemplated = (right[index] ?? "").startsWith(":");
+            if (leftTemplated !== rightTemplated)
+                return leftTemplated ? 1 : -1;
+        }
+        return 0;
+    });
     const byTarget = new Map();
     for (const registration of registrations) {
         byTarget.set(registration.target, [
@@ -1199,6 +1567,7 @@ type Produced<T> = T extends (...args: never[]) => unknown
     const negotiates = [...grouped.values()].some((group) => group.length > 1);
     // Same rule: imported only where a HEAD operation stands alone on its path.
     const guardsHead = registrations.some((registration) => registration.headOnly);
+    const guardsQuery = emitted.routes.some((route) => route.literalQuery.length > 0);
     /**
      * **Which runtime imports to write is read from the DATA, never from the rendered text.**
      *
@@ -1242,8 +1611,9 @@ type Produced<T> = T extends (...args: never[]) => unknown
     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);
+        entries.some((entry) => inputTypeOf(entry) !== undefined) ||
+        returnsAnything;
+    const runtimeModule = JSON.stringify(DEFAULT_RUNTIME_MODULE);
     /**
      * **One base sub-app, mounted with `app.route()`. Hono's own nesting, not a rewritten path on
      * every registration.** Prefixing each path individually would fight the resource grouping, and
@@ -1253,17 +1623,59 @@ type Produced<T> = T extends (...args: never[]) => unknown
      */
     const usesBasePath = basePaths.length > 0;
     const needsHonoValue = subApps.size > 0 || usesBasePath;
+    /**
+     * Hono's status-code types the result unions name, read from the rendered unions by TOKEN, the
+     * same way the validator identifiers above are: an identifier absent from the text is genuinely
+     * not needed, so the check cannot be wrong in the direction that breaks a build.
+     */
+    const renderedResults = new Set(resultTypes.join("\n").match(/[A-Za-z_$][A-Za-z0-9_$]*/g) ?? []);
+    const statusTypes = [
+        "ClientErrorStatusCode",
+        "ContentfulStatusCode",
+        "ContentlessStatusCode",
+        "InfoStatusCode",
+        "RedirectStatusCode",
+        "ServerErrorStatusCode",
+        "StatusCode",
+        "SuccessStatusCode",
+        "UnofficialStatusCode",
+    ].filter((name) => renderedResults.has(name));
+    const operates = entries.length > 0;
+    const honoTypes = [
+        "Context",
+        ...(mountsBody ? ["Env"] : []),
+        ...(needsHonoValue ? [] : ["Hono"]),
+        "Input",
+        ...(operates || mountsBody ? ["MiddlewareHandler"] : []),
+    ];
+    const runtimeValues = [
+        ...uses.runtime,
+        ...(negotiates ? ["selectContentType"] : []),
+        ...(guardsHead ? ["headOnly"] : []),
+        ...(guardsQuery ? ["literalQuery"] : []),
+    ].toSorted();
+    const runtimeTypes = ["AppEnv", ...(operates ? ["Awaitable"] : []), "RouteDeps"];
     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";'}${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};` : ""}
+${validates ? 'import { zValidator } from "@hono/zod-validator";\n' : ""}${needsHonoValue ? 'import { Hono } from "hono";\n' : ""}import type { ${honoTypes.join(", ")} } from "hono";
+${statusTypes.length > 0 ? `import type { ${statusTypes.join(", ")} } from "hono/utils/http-status";\n` : ""}${usesZod ? 'import { z } from "zod";\n' : ""}import type { ${runtimeTypes.join(", ")} } from ${runtimeModule};${runtimeValues.length > 0 ? `\nimport { ${runtimeValues.join(", ")} } from ${runtimeModule};` : ""}
 ${imports}
+${syncHelper}${bodyHelper}${fieldsHelper}${declaredHelper}/**
+ * What each operation may answer with: one member per response the document declares.
+ *
+ * A handler returns \`{ status, body, headers }\` for whichever response it means. The generated route
+ * serves it with the Hono call for that status, so \`hc\` sees a typed body per status, and a status
+ * or body the document does not declare does not compile.
+ */
+${resultTypes.join("\n\n")}
+
 /**
- * One method per operation, each concretely typed from the schemas it validates against.
+ * One handler per operation, each concretely typed from the schemas it validates against.
  *
- * 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.
+ * \`C\` is the caller context, inferred by \`registerRoutes\` from \`deps.context\`. There is no cast
+ * anywhere in this file, and no dynamic lookup: the generated call sites name the handler, so an
+ * implementation whose input or result does not match the contract fails to compile.
  */
-${syncHelper}${bodyHelper}${fieldsHelper}${declaredHelper}export interface Operations {
+export interface Operations<C = unknown> {
 ${methods.join("\n")}
 }
 
@@ -1304,12 +1716,12 @@ ${aliases.join("\n")}
 export type Exhaustive<T> = T & Record<Exclude<keyof T, keyof Operations>, never>;
 
 /** Mount every operation the service declares. */
-export function registerRoutes<T extends Operations>(
+export function registerRoutes<C, T extends Operations<C>>(
 	app: Hono<AppEnv>,
 	handlersFor: <P extends string, I extends Input>(c: Context<AppEnv, P, I>) => Exhaustive<T>,
-	deps: RouteDeps,
+	deps: RouteDeps<AppEnv, C>,
 ) {
-${subAppDeclarations}${usesBasePath
+${operates ? CONTEXT_MIDDLEWARE : ""}${negotiates ? ACCEPTABLE_MIDDLEWARE : ""}${subAppDeclarations}${usesBasePath
         ? `\tconst basePathRoutes = new Hono<AppEnv>()\n${rootChain.join("\n")};\n\n\treturn app${basePaths.map((prefix) => `\n\t\t.route(${JSON.stringify(prefix)}, basePathRoutes)`).join("")};`
         : `\treturn app\n${rootChain.join("\n")};`}
 }