typespec-hono 0.1.0 → 0.3.0

package/README.md

@@ -1,44 +1,22 @@
 # typespec-hono
 
-Generate a [Hono](https://hono.dev) server — and the Zod validators it enforces — from a TypeSpec HTTP
-service, agreeing with the OpenAPI document [`@typespec/openapi3`](https://typespec.io) publishes from
-the same source.
+Generate a [Hono](https://hono.dev) server from a TypeSpec API definition. Routing, request
+validation and handler types all come from the spec.
 
-This package runs the whole of
-[`typespec-http-zod`](https://github.com/bison-digital/typespec-http-zod) and adds one file. **A
-consumer lists one emitter and gets five artefacts.**
+Add [`@typespec/openapi3`](https://typespec.io) to the same config and it writes the OpenAPI document
+from that same definition, so your server and your docs cannot drift apart.
 
-## Why one emitter and not two
-
-The server and the validators share a naming contract: `app.gen.ts` imports `readWidgetPath` and
-`readWidgetResponses` from `schemas.gen.js` **by name**. Two separate TypeSpec emitters would each get
-their own `$onEmit` and their own registry, and would have to arrive at identical identifiers by
-coincidence. Running the library from inside this one means it mints the names, writes them, and hands
-them back — so the agreement is structural.
-
-If you want the validators without a server, install `typespec-http-zod` alone. Nothing here is
-required for that.
+Validation and types come from
+[`typespec-http-zod`](https://github.com/bison-digital/typespec-http-zod), which this runs for you, so
+your config lists one emitter.
 
 ## Install
 
 ```bash
-npm install typespec-hono
+pnpm add -D typespec-hono
 ```
 
-⚠️ **A dependency, not a devDependency, and this is not a style preference.** `typespec-hono/runtime`
-exports **runtime values** — `armFor`, and `selectContentType` where a route negotiates — and both the
-generated server and your own `deps` import them. Under `--save-dev` everything looks fine: install,
-typecheck and `wrangler dev` all pass. It fails at **deploy**, when the production install drops it:
-
-```
-✘ [ERROR] Could not resolve "typespec-hono/runtime"
-      import { armFor, type RouteDeps } from "typespec-hono/runtime";
-```
-
-Measured: `pnpm install --prod` then `wrangler deploy --dry-run` → exit 1. The emitter half is
-build-time, but the runtime half ships.
-
-Peers: `hono`, `@hono/zod-validator`, `zod`, `@typespec/compiler`.
+Peer dependencies: `hono`, `@hono/zod-validator`, `zod`, `@typespec/compiler`.
 
 ```yaml
 # tspconfig.yaml
@@ -50,283 +28,153 @@ options:
     seal-object-schemas: true
 ```
 
-## What it emits
-
-`app.gen.ts`, plus everything `typespec-http-zod` emits — see its README for the other four.
+## Quick start
 
-Routes are grouped into a **sub-app per resource** and mounted with `app.route()`, which is what
-[Hono's best-practices guide](https://hono.dev/docs/guides/best-practices) recommends for building a
-larger application. Its other recommendation is honoured at the same time and matters more: handlers
-are written **directly after the path definitions**, never lifted into Rails-style controllers, because
-a handler in a separate file cannot infer its path parameters. A resource with one route gets no
-sub-app — that is ceremony around a single line, and not what an author writes.
-
-Measured before relying on it: `app.route(prefix, sub)` composes paths exactly, including a parameter
-in the prefix, and the parent's `app.routes` reports the fully composed path — so every arm that
-counts routes still counts them.
-
-The server is **plain `Hono` and `@hono/zod-validator`**, deliberately not `@hono/zod-openapi`. That
-package is the same validation plus a document generated FROM the code — spec-last, and a second
-source of truth competing with the one openapi3 publishes from the spec. We want its validation, not
-its documentation.
-
-```ts
-import { Hono } from "hono";
-import { registerRoutes } from "./generated/app.gen.js";
-
-// ⚠️ Unannotated on purpose — annotating widens the value and disables the exhaustiveness check.
-const handlersFor = (c) => backendFor(c.env);
-const routes = registerRoutes(new Hono<AppEnv>(), handlersFor, deps);
+You write four files. Everything under `src/generated/` is produced by the compiler and never edited:
 
-export default routes;
 ```
-
-### Hono RPC (`hc`) works, and the return value is why
-
-`registerRoutes` **chains** its registrations and hands back the result, so Hono's RPC client gets a
-fully typed surface derived from the same document:
-
-```ts
-import { hc } from "hono/client";
-
-const client = hc<typeof routes>("https://api.example.com");
-const response = await client.widgets[":widget-id"].$get({
-	param: { "widget-id": "w-1" },
-	header: { "x-request-id": "r-1" },
-});
+main.tsp              your API definition
+tspconfig.yaml        which emitters to run
+src/
+  generated/          written by `tsp compile`, never edited by hand
+    app.gen.ts
+    runtime.gen.ts
+    schemas.gen.ts
+  deps.ts             your application's answers
+  index.ts            your handlers, and the app
 ```
 
-⚠️ **Use the RETURNED value, not the instance you passed in.** `hc` reads the `Schema` type Hono
-accumulates through the chain; the bare `new Hono()` still carries nothing. Measured before this
-worked: `hc<typeof app>` resolved to `unknown` — not an empty client, an unusable one.
-
-`handlersFor` is a **factory** rather than an object because in Workers a service binding lives on
-`c.env` and exists only for the duration of a request — there is no module scope in which
-`backendFor(env)` can be resolved.
-
-### The document's base path is honoured
+### `main.tsp`
 
-`@server("/api/v1")` reaches OpenAPI as `servers: [{ url: "/api/v1" }]`, and **an OpenAPI path is
-relative to its server** — so the document publishes `/api/v1/accounts`, not `/accounts`. The
-generated routes are mounted under that prefix with a nested `app.route()`, so the server and the
-document agree and a client generated from the document reaches it.
+```tsp
+import "@typespec/http";
+using Http;
 
-Where the document is ambiguous — several servers with disagreeing paths — routes are mounted at the
-root and `ambiguous-server-path` says so. A templated server such as `@server("{endpoint}")` means the
-caller supplies the whole origin, so the root is already correct and nothing is reported.
+@service(#{ title: "Widgets" })
+namespace Widgets;
 
-### Authentication carries the scheme, not just "someone is here"
+model Widget {
+  id: string;
+  name: string;
+}
 
-`@useAuth(BearerAuth)` publishes `security: [{ "BearerAuth": [] }]`, and `deps.authorize` receives
-exactly that:
-
-```ts
-deps.authorize([{ BearerAuth: [] }])                      // one scheme, no scopes
-deps.authorize([{ OAuth2Auth: ["widgets:read"] }])        // scopes, from the declared flows
-deps.authorize([{ OAuth2Auth: [...] }, { BearerAuth: [] }]) // EITHER authorises
+@route("/widgets")
+interface WidgetRoutes {
+  @get list(@query limit?: int32): Widget[];
+  @get read(@path id: string): Widget;
+}
 ```
 
-Satisfying **any one** requirement authorises the caller; every scheme **within** one must be
-satisfied together. That is what an array of OpenAPI `security` objects means, and a flat list of
-scopes cannot express the difference.
-
-⚠️ **This used to carry scopes only**, so a gate was emitted for OAuth2 and for nothing else — bearer,
-api-key and basic carried none at all and rested entirely on `deps.context` returning null. That
-answers "is somebody here", not "did they satisfy the scheme the contract names": an application
-reading a cookie would have served a route the document says needs a bearer token.
-
-Which credentials satisfy a scheme is still yours — it could not be anything else. Which schemes an
-operation accepts is a contract fact, and is now generated.
-
-## Middleware — register it BEFORE `registerRoutes`
-
-⚠️ **This is the one ordering rule, and getting it wrong fails silently.** Hono middleware applies
-only to routes registered _after_ it, and `registerRoutes` registers everything at once. Middleware
-added afterwards does not error — it simply never runs.
-
-```ts
-const app = new Hono<AppEnv>();
-
-app.use(cors()); // ✅ global
-app.use("/widgets/*", rateLimit()); // ✅ per resource
-app.use("/widgets/:widget-id", cache()); // ✅ per route
-
-const routes = registerRoutes(app, handlersFor, deps); // ← everything above applies
-
-app.use(cors()); // ❌ silently applies to nothing
+```bash
+pnpm exec tsp compile .
 ```
 
-All three scopes are reachable and each is asserted by a real request in
-`test/wire/middleware.test.ts`. Per-resource works through a prefix wildcard rather than a handle on
-the sub-app: the sub-apps are `const`s inside `registerRoutes`, and `/widgets/*` is the equivalent —
-it works because every route of a resource is mounted under that resource's prefix.
-
-`app.onError` and `app.notFound` are **not** subject to this: they are app-level handlers rather than
-route middleware, and may be registered in any order.
-
-## Cloudflare Workers — pick a router
-
-You construct the `Hono` instance, so the router is your choice. **Make it deliberately.** Measured on
-a generated **580-operation** service (58 resources × 10), three runs, on Hono 4.13.1:
-
-| router                         | register       | first request    | 1000 requests |
-| ------------------------------ | -------------- | ---------------- | ------------- |
-| SmartRouter _(Hono's default)_ | 5.4–6.1 ms     | **18.5–18.9 ms** | 24–26 ms      |
-| **RegExpRouter**               | 2.6–4.4 ms     | 2.2–2.6 ms       | **16–18 ms**  |
-| LinearRouter                   | **1.1–1.2 ms** | **0.6 ms**       | 66–70 ms      |
-| PatternRouter                  | 2.7–2.9 ms     | 2.5 ms           | 36–39 ms      |
-
-⚠️ **The default is the worst choice here, and the reason is a cold-start cost you pay per isolate.**
-SmartRouter picks a router by trying one, and that build happens on the **first request** rather than
-at registration. At this scale that is ~18.8 ms of CPU — and the Workers **free plan allows 10 ms of
-CPU per request**, so the first request into every new isolate can be killed with `exceededCpu`.
+### `src/index.ts`
 
-**Recommendation for a generated app: `RegExpRouter`.**
+`input` and the return type are both known from the spec, so a handler that does not match the
+contract does not compile:
 
 ```ts
 import { Hono } from "hono";
-import { RegExpRouter } from "hono/router/reg-exp-router";
-
-const routes = registerRoutes(new Hono<AppEnv>({ router: new RegExpRouter() }), handlersFor, deps);
-```
-
-Its reputation for slow registration does not bite here — it registered in under 5 ms and is fastest
-in steady state. Choose `LinearRouter` instead only for a very low-traffic Worker where cold start
-dominates: it is the cheapest to start and ~4× slower per request thereafter.
-
-### Bundle size is not the constraint
+import { registerRoutes } from "./generated/app.gen.js";
+import { deps } from "./deps.js";
 
-|                | raw      | gzip          | share of the 3 MB free limit |
-| -------------- | -------- | ------------- | ---------------------------- |
-| 20 operations  | 642 KiB  | 100.8 KiB     | 3.3%                         |
-| 580 operations | 1008 KiB | **112.6 KiB** | **3.7%**                     |
+const handlersFor = () => ({
+	WidgetRoutes_list: (ctx, input) => widgets.slice(0, input.limit ?? 20),
+	WidgetRoutes_read: (ctx, input) => widgets.find((w) => w.id === input.id),
+});
 
-560 extra operations cost ~12 KiB gzipped — the baseline is Hono and Zod, not your API. Router choice
-moves it by under 1 KiB, so do not choose a router for size. Limits are 3 MB gzipped on the free plan
-and 10 MB on paid.
+export default registerRoutes(new Hono(), handlersFor, deps);
+```
 
-`registerRoutes` runs at module scope in 1.1–6.1 ms, comfortably inside the **1 second** startup
-budget, despite the docs' warning that "generating or consuming a large schema at the top level is a
-common cause of exceeding this limit".
+Leave `handlersFor` unannotated: annotating it widens the value and disables the check that catches a
+handler for an operation the spec no longer declares. It is a factory rather than an object because a
+Workers service binding lives on `c.env` and exists only for the duration of a request.
 
-Nothing here needs `nodejs_compat`: the generated server runs on `workerd` with no Node built-ins.
+### `src/deps.ts`
 
-## Streaming
+Six hooks, each answering something the spec does not contain:
 
-A generated operation returns a **value**, not a `Response`, so a handler cannot hand back a
-`ReadableStream`. Streaming happens in `deps.respond`, which may return any `Response`:
+| hook            | the spec says                               | you say                              |
+| --------------- | ------------------------------------------- | ------------------------------------ |
+| `authorize`     | which schemes and scopes an operation needs | whether this caller satisfies them   |
+| `context`       | whether a caller is required                | who the caller is                    |
+| `noContext`     |                                             | what to answer when there is not one |
+| `notAcceptable` | which media types are offered               | what to answer when none match       |
+| `invalid`       | the schema                                  | what a validation failure looks like |
+| `respond`       | every status arm and its schema             | which arm this result is             |
 
 ```ts
-const deps: RouteDeps = {
-	// ...
-	respond: (c, arms, result) =>
-		streamSSE(c, async (stream) => {
-			for await (const item of pageThrough(result)) {
-				await stream.writeSSE({ data: JSON.stringify(item) });
-			}
-		}),
+import type { RouteDeps } from "./generated/runtime.gen.js";
+
+export const deps: RouteDeps = {
+	authorize: (requirements) => async (c, next) => {
+		await next();
+	},
+	context: (c) => ({ userId: c.req.header("x-user") }),
+	noContext: (c) => c.json({ error: "unauthorized" }, 401),
+	notAcceptable: (c, offered) => c.json({ error: "not_acceptable", offered }, 406),
+	invalid: (result, c) => (result.success ? undefined : c.json({ error: "invalid" }, 400)),
+	respond: (c, arms, result) => c.json(result as never, 200),
 };
 ```
 
-The validators are middleware, so they still run **before** anything is streamed — a request the
-document forbids is refused with an ordinary response and never opens a stream. Both properties are
-asserted by real requests in `test/wire/streaming.test.ts`.
-
-Point `runtime-module` at your own module and re-declare `Result<T>` if you want the handler's return
-type to carry the stream shape; that is the same seam the README describes for result envelopes.
-
-## Observability
+Routing, request validation and the handler types come from the spec. What is left is the four files
+above.
 
-Nothing here is Sentry-specific, and this package deliberately ships no instrumentation — but two
-properties an APM needs are asserted rather than hoped for:
-
-- **`c.req.routePath` yields the route pattern**, `/widgets/:widget-id`, not the concrete URL. That is
-  the span name you want; the URL would be a cardinality bomb. It survives being mounted through a
-  sub-app, which is not obvious.
-- **A handler's `throw` reaches an app-level `onError`.** Nothing in the generated file swallows it —
-  `deps.respond` is only reached on success.
-
-Both are pinned by real requests, so a change to how routes are grouped cannot quietly remove them.
-
-## Options
+## What it emits
 
-Every option `typespec-http-zod` accepts, forwarded — the schema is **derived** from that package's,
-not restated, and a test asserts the forwarding as a class at both the top level and inside the
-per-service overrides. See its README for `seal-object-schemas`, `contracts-output-dir`,
-`contracts-package`, `key-vocabularies`, `runtime-module` and `services`.
+Into your output directory:
 
-`runtime-module` is the one you are most likely to set: point it at a module of your own that
-re-declares `Result`, `Ctx`, `AppEnv` and `RouteDeps`, and every generated signature carries your
-types instead of the identity defaults.
+| file                   | what it is                                                                     |
+| ---------------------- | ------------------------------------------------------------------------------ |
+| `app.gen.ts`           | the server: routes, validators, and the handler interface you implement        |
+| `runtime.gen.ts`       | the types your `deps` implements against, and the helpers the server calls     |
+| `schemas.gen.ts`       | a Zod schema for every request and response, and the status arms each declares |
+| `vocabularies.gen.ts`  | shared enums, where the spec declares them                                     |
+| `requests.gen.ts`      | request types, when `contracts-output-dir` is set                              |
+| `wire-contract.gen.ts` | assertions that the schemas and the types agree, with the same option          |
 
-## What it refuses, and why
+The last four are `typespec-http-zod`'s; see its README for what they contain.
 
-Both refusals are about the target framework. `typespec-http-zod` emits correct validators for these
-operations; only a Hono server cannot serve them.
+Your own code imports from `runtime.gen.ts`:
 
-| code                        | why                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `unroutable-verb`           | ⚠️ **A `@head` operation.** Hono rewrites every HEAD request to GET _before_ matching — `hono-base.js` does it unconditionally at the top of `#dispatch` — so a route registered under HEAD is never reached: 404 where the path has no GET, dead code where it has one. Measured on Hono 4.13.1; `on("PURGE", …)` and `on("OPTIONS", …)` both work, so this is HEAD specifically. **The remedy is in your spec:** declare `@get`, and Hono answers HEAD from it with the body stripped, which is what RFC 9110 requires anyway. Hono's own [best-practices guide](https://hono.dev/docs/guides/best-practices) states the same rule. |
-| `ambiguous-server-path`     | The service declares several `@server` entries whose base paths disagree, so there is no single prefix to mount under. Routes are mounted at the **root** and this says so. An OpenAPI path is relative to its server, so callers following the document will prefix one of them — mount the returned app under the prefix you actually serve, or declare a single base path.                                                                                                                                                                                                                                                         |
-| `unsupported-path-template` | a path parameter that is not a plain name. Hono reads a parameter up to the next `/`, so an RFC 6570 operator or modifier would become part of the name — and `*` would become Hono's wildcard, mounting a route that matches the wrong requests and answers them. Refused rather than approximated, because a route that works and is wrong is worse than one that fails.                                                                                                                                                                                                                                                            |
+```ts
+import type { Ctx, RouteDeps } from "./generated/runtime.gen.js";
+```
 
-### Refusals are warnings, and you choose whether they fail the build
+Setting `runtime-module` replaces it with a module of your own, and it is then not written.
 
-A refusal is reported as a **warning**, so a compile that contains one still succeeds and still emits
-everything else — including `@typespec/openapi3`'s document, if you run it.
+Routes are grouped into a sub-app per resource and mounted with `app.route()`, following
+[Hono's best-practices guide](https://hono.dev/docs/guides/best-practices). Handlers are written
+directly after the path definitions rather than lifted into separate controller files, because a
+handler in another file cannot infer its path parameters. A resource with a single route gets no
+sub-app.
 
-⚠️ **That last part is why.** A TypeSpec `error` sets `program.hasError()`, and openapi3 declines to
-write anything when the program has errors — _including errors that are not its own_. With these
-refusals as errors, one `@head` operation cost you your entire OpenAPI document, and whether it did
-depended on the order emitters were listed in. Measured: `openapi/` went from one file to none.
+The output is plain `Hono` and `@hono/zod-validator`, not `@hono/zod-openapi`. That package generates
+a document from the code, which would compete with the one openapi3 publishes from the spec.
 
-It is also what the first-party rule says. openapi3 uses `warning` for exactly this shape —
-`streams-not-supported`, `unsupported-auth` — meaning _"the spec is valid and this emitter cannot
-express it"_, and reserves `error` for a spec that is wrong for any emitter. A `@head` operation is
-valid TypeSpec that openapi3 renders perfectly; only Hono cannot route it.
+```ts
+import { Hono } from "hono";
+import { registerRoutes } from "./generated/app.gen.js";
 
-**Nothing is lost.** The operation is still excluded from the server, still named, still carries its
-remedy. If you want a refusal to fail your build, that is the compiler's switch and always was:
+// Leave handlersFor unannotated. Annotating it widens the value and disables the
+// exhaustiveness check that catches a handler for an operation the spec no longer declares.
+const handlersFor = (c) => backendFor(c.env);
+const routes = registerRoutes(new Hono<AppEnv>(), handlersFor, deps);
 
-```yaml
-# tspconfig.yaml
-warn-as-error: true
+export default routes;
 ```
 
-```
-default            -> exit 0, document written, operation excluded
-warn-as-error      -> exit 1, build fails, refusal reported as an error
-```
+`handlersFor` is a factory rather than an object because a Workers service binding lives on `c.env`
+and exists only for the duration of a request.
+
+## Docs
 
-## Known limits
-
-- **Fifteen of the seventeen `@head` operations in `@typespec/http-specs` are refused**, and that is
-  the honest count rather than a defect: they have no sibling `GET`, so Hono cannot route them at all.
-  This emitter previously emitted them, and every route-counting arm called them mounted.
-- **`app.on(method, …)` is reachable by no TypeSpec spec**, because `@typespec/http` declares six
-  verbs, five have Hono helpers, and the sixth is `@head`, which is refused. The branch is exercised
-  directly by `test/render.test.ts` rather than left untested or deleted — deleting it would make
-  `HONO_METHOD[verb]` `undefined` for any verb TypeSpec adds later, emitting `app.undefined(...)`
-  from a spec that compiles.
-
-## How it is graded
-
-- **Route surface over the corpus** — 61 scenarios of `@typespec/http-specs`, with counts read from
-  `app.routes` after mounting the real `registerRoutes`, never from the emitted text. **577 declared,
-  564 mounted, 13 refused**, and `mounted + refused === declared` is asserted, because
-  `mounted === declared` can be satisfied by a route nobody can reach — and was.
-- **An application is compiled against it**, with `runtime-module` pointed at a module that
-  substitutes real types, and with no cast anywhere. A signature no application could satisfy passed
-  every other test for a long time because the suite that mounted it cast to `unknown`.
-- **Equivalence against a hand-written Hono app** — `test/equivalence/reference-app.ts` follows the
-  pattern in Hono's own validation guide, written without reference to what this emitter produces.
-  Both apps serve the same API and answer thirteen identical exchanges identically, and both routing
-  tables are compared, because behaviour alone would miss two apps that happen to 404 together. ⚠️
-  **Its value is entirely in its independence** — adjusted to match our output, it would prove only
-  that we agree with ourselves, so when the two disagree the emitter is what changes.
-- **Real requests through the real router** — the only thing that can see a validator-to-wire defect.
-  A flattened collection parameter once had the document saying `array`, the validator saying `array`,
-  and the server rejecting every conformant caller.
+- [Guides](docs/guides.md): middleware, the RPC client, authentication, base paths, HEAD operations,
+  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
 
 ## Licence
 

package/dist/src/app.d.ts

@@ -3,57 +3,63 @@ import { type EmittedRoute, type EmittedService } from "typespec-http-zod";
 /**
  * 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
+ * **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. Hono reads a parameter up to the next
- * `/`, so an RFC 6570 modifier would survive into the name and `*` would become Hono's wildcard — a
- * route that matches the wrong requests and answers them, which is worse than one that fails.
+ * 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 runs at RENDER time, not during collection.** It used to run inside `collectRoutes`, which
+ * **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
+ * operation (validators included) over a template no router could mount. What a request body must
  * look like does not depend on that.
  */
 export declare function toHonoPath(template: string, refuse: (template: string, name: string) => void): string;
-/** The two things a Hono server cannot express, handed back rather than thrown. */
+/** The one thing a Hono server cannot express, handed back rather than thrown. */
 export interface RenderRefusals {
     readonly unsupportedPathTemplate: (route: EmittedRoute, template: string, name: string) => void;
-    readonly unroutableVerb: (route: EmittedRoute) => void;
+    readonly unvalidatableMediaType: (route: EmittedRoute, types: readonly string[]) => void;
 }
 /**
  * The generated Hono server.
  *
- * ⚠️ **This replaces a data table that a hand-written loop interpreted at run time.** The emitter knew,
- * per operation, which validators applied and what the call looked like — and then flattened all of it
+ * **This replaces a data table that a hand-written loop interpreted at run time.** The emitter knew,
+ * per operation, which validators applied and what the call looked like, and then flattened all of it
  * into one homogeneous array, so the consumer had to recover it dynamically and could not. Emitting
  * the call sites keeps that knowledge, and every one of them is monomorphic and checked.
  *
- * ⚠️ **Plain `Hono` and `@hono/zod-validator`, deliberately not `@hono/zod-openapi`.** The latter is
- * the same validation plus a document generated FROM the code — spec-last, and a second source of
+ * **Plain `Hono` and `@hono/zod-validator`, deliberately not `@hono/zod-openapi`.** The latter is
+ * the same validation plus a document generated FROM the code, spec-last, and a second source of
  * truth competing with the one `@typespec/openapi3` publishes from the spec. We want its validation,
  * not its documentation.
  *
- * ⚠️ **It declares no schema of its own.** Every validator this file names was declared by
+ * **It declares no schema of its own.** Every validator this file names was declared by
  * `typespec-http-zod` into `schemas.gen.ts` and is imported by name. That is what makes the two
- * packages one emitter rather than two that must agree by coincidence — and it is why a consumer who
+ * packages one emitter rather than two that must agree by coincidence, and it is why a consumer who
  * wants the validators without a server can simply not install this one.
  */
 export declare function renderApp(emitted: EmittedService, refuse: RenderRefusals, 
 /**
- * The path the DOCUMENT says this service is served under, when it says one unambiguously.
+ * Every path the DOCUMENT says this service is served under. All of them are mounted.
  *
- * ⚠️ **An OpenAPI path is relative to its server**, so `@server("/api/v1")` plus `/accounts` means
+ * **An OpenAPI path is relative to its server**, so `@server("/api/v1")` plus `/accounts` means
  * 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.
  */
-basePath?: string, 
+basePaths?: readonly string[], 
 /**
  * What the DOCUMENT says a caller must satisfy, per operation id.
  *
- * ⚠️ **Resolved by the caller rather than read off `EmittedRoute`**, because which schemes an
+ * **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.