typespec-http-zod 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bison Digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,269 @@
+# typespec-http-zod
+
+Zod validators and framework-free contract types from a TypeSpec HTTP service — agreeing, keyword for
+keyword, with the OpenAPI document [`@typespec/openapi3`](https://typespec.io) publishes from the same
+source.
+
+It is a **library and an emitter**. Use the emitter to generate validators for any server — Express,
+Fastify, Elysia, a Workers fetch handler, a typed client — or use the API to build an emitter of your
+own. [`typespec-hono`](https://github.com/bison-digital/typespec-hono) is the second kind, and is
+where the API is proved.
+
+## The governing rule
+
+**If the document cannot say it, the validator must not enforce it.**
+
+A validator that checks something the published contract never states is a rule no caller reading that
+contract can see. This package ships **zero decorators** for exactly that reason — four once existed,
+and every one let a spec state something `@typespec/openapi3` could not publish — and asserts the
+class is empty rather than trusting it. Where openapi3 decides something, its rule is read from its
+source and copied, refusals included: the same spec has to be representable by both emitters or by
+neither, or a differential between them means nothing.
+
+## Install
+
+```bash
+npm install typespec-http-zod
+```
+
+⚠️ **A regular dependency, not a dev one, if your application calls `armFor`.** The emitter itself
+runs at build time, and the generated files import only `import type { ResponseArm }` — a type, which
+erases. But [`./runtime`](#answering-a-request) also exports `armFor`, a **function**, and it exists
+precisely so applications do not re-derive OpenAPI's response precedence by hand. An application that
+calls it and installed this package with `--save-dev` typechecks, builds, and runs in development,
+then fails on deploy:
+
+```
+Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'typespec-http-zod'
+    imported from dist/server.js
+```
+
+Measured in a fresh project installed from a `pnpm pack` tarball: identical build output, `pnpm
+install --prod`, **exit 1**; the same bytes with the package in `dependencies`, **exit 0**. If you use
+only the emitted validators and never import `armFor`, `--save-dev` is sufficient.
+
+Peers: `@typespec/compiler`, `@typespec/http`, `@typespec/openapi`, and `zod` (the generated output
+imports it). `@typespec/versioning` and `@typespec/streams` are **optional** — they are resolved
+behind a guarded `import()`, so a spec declaring neither needs neither.
+
+```yaml
+# tspconfig.yaml
+emit:
+  - typespec-http-zod
+options:
+  typespec-http-zod:
+    emitter-output-dir: "{project-root}/src/generated"
+```
+
+## What it emits
+
+⚠️ **Only `schemas.gen.ts` is emitted by the configuration above.** The other three are written only
+when `contracts-output-dir` names somewhere to put them — they are the framework-free contract types
+and the assertions that pair them against the validators, and a consumer that wants validators alone
+should not have them appear uninvited. Add it to get all four:
+
+```yaml
+# tspconfig.yaml
+emit:
+  - typespec-http-zod
+options:
+  typespec-http-zod:
+    emitter-output-dir: "{project-root}/src/generated"
+    contracts-output-dir: "{project-root}/src/generated"
+```
+
+| file                   | what it is                                                                                                                                           | emitted when                     |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| `schemas.gen.ts`       | every validator: the component schemas, **and** each operation's path, query, header, body and response validators, plus the arms it may answer with | always                           |
+| `requests.gen.ts`      | framework-free contract types — plain TypeScript, no imports, so they cross layers that must not see a validation library                            | `contracts-output-dir` is set    |
+| `vocabularies.gen.ts`  | each enum's members as a runtime tuple, because a generated type cannot be iterated                                                                  | `contracts-output-dir` is set    |
+| `wire-contract.gen.ts` | assertions pairing the emitted Zod against those types, so the two walks cannot disagree silently                                                    | that **and** `contracts-package` |
+
+Per operation you get `readWidgetPath`, `readWidgetQuery`, `readWidgetHeader`, `readWidgetBody`,
+`readWidgetResponse` and `readWidgetResponses` — named from **the operation id the document
+publishes**, which is not always the bare operation name.
+
+⚠️ **An operation inside a namespace is named after the whole id.** `op readWidget` inside
+`namespace Widgets` has operation id `Widgets_readWidget`, so the identifiers are
+`Widgets_readWidgetPath` and so on. Namespaces are the idiomatic way to group routes, so this is the
+common case rather than the exception — read the emitted file for the names rather than assuming
+them.
+
+⚠️ **A validator that is already a component gets no second name.** `readWidgetResponse` is emitted
+only when the response shape needs a name of its own; where the operation answers with a declared
+model the arm refers to that model's schema directly — `widgetSchema`, not `readWidgetResponse`. The
+same holds for a request body: `op createWidget(@body body: WidgetCreate)` is validated by
+`widgetCreateSchema`. The mapping from an operation to the schema that validates it is published
+through the [API](#building-an-emitter-on-this) as `EmittedService.schemaNames`; from the emitted file
+alone, an operation with no `…Body` const is one whose body is a named component.
+
+## Options
+
+| option                 | what it does                                                                                                                                                                                                                                                                                                                                         |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `seal-object-schemas`  | whether a model closed in the spec REJECTS an undeclared property rather than stripping it. ⚠️ **Set this to whatever `@typespec/openapi3`'s option of the same name is set to** — the two emitters answer the same question about the same models and neither can read the other's configuration. Defaults to `false`, which is openapi3's default. |
+| `contracts-output-dir` | where the framework-free contract types go, when they should not sit beside the validators. Omitted, they are not emitted.                                                                                                                                                                                                                           |
+| `contracts-package`    | the specifier the emitted Zod imports shared types from. **No default** — it once defaulted to one repository's package name, so a consumer who configured nothing got validators importing from a package they had never heard of. With none named, enums are emitted inline and the output depends on nothing.                                     |
+| `key-vocabularies`     | models whose PROPERTY NAMES are also emitted as a runtime tuple. For a closed key set that is a contract fact but cannot be a `Record` key type. A name matching no model is reported, not ignored.                                                                                                                                                  |
+| `runtime-module`       | where the generated files import `ResponseArm` from. Defaults to `typespec-http-zod/runtime`.                                                                                                                                                                                                                                                        |
+| `services`             | per-`@service` overrides, keyed by namespace name, for a spec that publishes more than one surface.                                                                                                                                                                                                                                                  |
+
+## Answering a request
+
+No server framework appears below, because none is needed: the emitted validators are plain Zod and
+`./runtime` is two exports. Express, Fastify, Elysia or a bare `fetch` handler each supply the
+`params`/`query`/`body` this reads.
+
+```ts
+import { armFor, type ResponseArm } from "typespec-http-zod/runtime";
+import { Widgets_readWidgetPath, Widgets_readWidgetResponses } from "./generated/schemas.gen.js";
+
+/** Answer a status with a body the document says that status carries. */
+function respond(arms: readonly ResponseArm[], status: number, body: unknown) {
+	const arm = armFor(arms, status);
+	if (arm === undefined) throw new Error(`no declared arm for ${status}`);
+	return { status, body: arm.schema === undefined ? undefined : arm.schema.parse(body) };
+}
+
+export function readWidget(params: Record<string, unknown>, widget: unknown | undefined) {
+	const parsed = Widgets_readWidgetPath.safeParse(params);
+	if (!parsed.success) return { status: 400, body: parsed.error.issues };
+	return widget === undefined
+		? respond(Widgets_readWidgetResponses, 404, { code: "not_found", message: "no such widget" })
+		: respond(Widgets_readWidgetResponses, 200, widget);
+}
+```
+
+**`armFor` is the whole reason `./runtime` exists.** An operation can declare `404`, `4XX` and
+`default` at once and all three describe a 404. OpenAPI settles it — an explicit code beats a range,
+and `default` is every status not otherwise listed — and a package that emits arms containing `4XX`
+and `default` without shipping the rule for reading them has shipped a footgun. Measured against the
+arms emitted for such an operation:
+
+| answered | arm chosen | body validated against |
+| -------- | ---------- | ---------------------- |
+| `200`    | `200`      | the success model      |
+| `404`    | `404`      | `NotFound`             |
+| `429`    | `4XX`      | `Throttled`            |
+| `500`    | `default`  | `Unexpected`           |
+
+⚠️ **A path or query value is a string on the wire, and the emitted validators already know.** A
+parameter the document types as `integer` is emitted wrapped in a `z.preprocess` that decodes `"1"`
+to `1` — and **decodes rather than coerces**, so `?limit=` stays empty and fails the schema instead of
+arriving as `0`. A flattened list (`?tags=a,b,c`) is split on the delimiter the document's `style`
+implies before the array schema runs. Hand the raw values straight in; do not pre-parse them.
+
+## Building an emitter on this
+
+The exported API — `emitHttpZod`, `EmittedService`, `EmittedRoute`, `collectRoutes` and the rest — is
+what an emitter for another framework calls. `emitHttpZod` returns one `EmittedService` per
+`@service`, and `EmittedService.schemaNames` maps each operation id to the identifiers its validators
+were declared under, so a wrapping emitter imports names rather than agreeing about them.
+
+```ts
+const services = await emitHttpZod(context, { defaultRuntimeModule: "my-emitter/runtime" });
+for (const service of services) {
+	for (const route of service.routes) {
+		const names = service.schemaNames.get(route.operationId);
+		// names.path / names.query / names.header / names.body / names.response / names.responses
+	}
+}
+```
+
+⚠️ **`defaultRuntimeModule` is a default, not an override** — a consumer's `runtime-module` still
+wins. It exists so a wrapping emitter whose generated files import more than `ResponseArm` can point
+them at its own module.
+
+## What it refuses, and why
+
+Every refusal is a **diagnostic**, not a thrown error: it points at the offending declaration, carries
+a code you can search for, and does not stop the walk — so one compile names every problem rather
+than the first.
+
+| code                            | why                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `unsupported-scalar`            | a scalar with no known base and no `@encode`. Give it `extends`, or encode it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `unsupported-type`              | a construct with no runtime representation — `never` is the reachable case.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `unsupported-default`           | a default value that is neither a scalar nor an empty collection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `empty-union`                   | a union with no representable variants has nothing to validate against.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `circular-model`                | a cycle closing through a union variant or dictionary value, neither of which is a property a getter can sit on. Ordinary recursion through a model property is fully supported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `unknown-key-vocabulary`        | a `key-vocabularies` entry naming no model. Reported because the failure mode is silence: a missing vocabulary looks exactly like an empty one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `unsupported-status-code-range` | OpenAPI keys a range as `1XX`…`5XX`, so `@minValue(494) @maxValue(499)` has nowhere to go. ⚠️ **Refused because `@typespec/openapi3` refuses it**, with the same rule copied from its source. A range covering a bucket exactly — `@minValue(400) @maxValue(499)` — is supported.                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `undeclared-discriminator`      | ⚠️ **Upstream, and not something you can fix with an emitter option.** `@discriminated(#{envelope: "none"})` puts the discriminator inside each variant on the wire, and openapi3 emits `oneOf` with a `discriminator` keyword while never adding that property to the variant schema — which OpenAPI 3.1 forbids ("the `discriminator` field MUST be a required field"). Tracked as [`microsoft/typespec#7141`](https://github.com/microsoft/typespec/issues/7141), open and maintainer-filed. **It is avoidable in your spec**: declare the discriminator on the variant (`model Cat { kind: "cat"; … }`) and openapi3 publishes it as required, with no divergence and no refusal. |
+
+## Known limits
+
+Stated here rather than left as numbers in a baseline file, because a number in a baseline is not a
+stated limitation once a package is published. Each is re-measured by the suite.
+
+- **`format` is deliberately not enforced, and that is now CHECKED rather than counted.** Under JSON
+  Schema 2020-12 `format` is an annotation, not a validation keyword, so turning one into a check
+  would enforce something the document does not assert. 136 annotations go unenforced, and
+  `test/vocabulary.test.ts` refuses any format-derived Zod call as a class — so turning it on breaks a
+  test rather than moving a number.
+- **4 negotiated response bodies cannot be attributed to a single arm.** OpenAPI lists one
+  body per media type against members that each carry their own, so there is no one arm to compare
+  them to. The status-to-body mapping is still graded for them.
+- **4 response bodies reduce to no readable kind on one side** — a stream, or a union. Counted, never
+  silently passed.
+- **A `@head` operation gets validators here and cannot be served by every router.** That is a fact
+  about the server, not about this package — see `typespec-hono`, which refuses it and says why.
+- **`int64` and `uint64` are validated as JavaScript numbers, so values above `2^53-1` are refused —
+  and `@encode(string)` is the fix.** The document publishes `type: integer` with `format: int64`,
+  which states no bound; the emitted `z.number().int()` refuses anything beyond
+  `Number.MAX_SAFE_INTEGER`. That is a constraint the document does not state, and it is kept anyway,
+  because it is imposed by the runtime rather than invented here — **above `2^53-1` an integer is no
+  longer uniquely representable as a JavaScript number**, so a validator cannot certify that the value
+  it holds is the value that was sent. Measured: `9007199254740993` reaches a handler as
+  `9007199254740992`, and int64's maximum as `9223372036854776000`, both through `JSON.parse` before
+  any validator runs. Accepting them would stamp "valid" on a number nobody sent, which is the one
+  answer a validator must never give. `z.int64()` is not an alternative: it is `bigint`-based and
+  `JSON.parse` never produces a `bigint`, so it would refuse every JSON body.
+
+  ⚠️ **TypeSpec's own remedy works and costs one decorator.** `@encode(string) value: int64` emits
+  `z.string()`, and openapi3 publishes `type: string` with `format: int64` — the two agree exactly, and
+  the digits survive the wire intact. Use it for any 64-bit integer whose values can exceed `2^53-1`:
+  identifiers, balances in minor units, timestamps in nanoseconds.
+
+- **The emitted output requires `zod`, not `zod/mini`.** The tree-shakeable variant has no chained
+  methods at all — measured on 4.4.3, `typeof z.string().optional`, `.nullable` and `.min` are each
+  `undefined` — and the emitted validators use `.optional()`, `.nullable()`, `.default()`, `.strict()`,
+  `.loose()` and `.catchall()`. A browser or Workers consumer therefore pays for the full `zod` build.
+  This is a property of the emitted spelling rather than of the schemas, so it is fixable; it is
+  recorded here as a measured fact rather than a plan.
+
+## How it is graded
+
+Nothing here is judged by fixtures we wrote alone.
+
+- **Conformance differential** — both emitters run from ONE compile of
+  [`@typespec/http-specs`](https://www.npmjs.com/package/@typespec/http-specs), Microsoft's own
+  scenario corpus, and the assertion is that the validators say what the document says. Components,
+  request parameters, declared statuses and response bodies. **0 divergences.**
+- **Round-trip against APIs nobody here designed** — the OpenAPI Initiative's teaching example and the
+  Swagger Petstore, converted to TypeSpec and compiled back out, then compared against the originals.
+  **22 operations, none lost, no shape disagreements.** Every other suite measures this emitter
+  against material that already knows about it; this one asks what a first adopter asks. The
+  documents are vendored with digests the suite asserts, never fetched.
+- **Request bodies are compared, and were compared by nothing at all** — 21 by shape and 36 by kind. Parameters were graded and responses were graded; what a caller may SEND, the largest surface of most APIs, had no arm.
+- **Response bodies are compared, not counted** — 24 inline bodies by SHAPE and
+  44 non-object bodies by KIND. This surface was a bare number for a long time, and closing it
+  immediately found three positions where the emitter required a string for a raw binary body the
+  document says nothing about.
+- **`content-type` and `accept` are compared** against the `content` keys that state them — 77
+  positions, no divergences. OpenAPI declares media types through `requestBody.content` and each
+  response's `content` rather than as parameters, so the parameter arm sets these aside; a separate
+  arm compares them where the document actually puts them.
+- **Depth fixtures** for what a protocol corpus does not contain: it declares **no constraints at
+  all**, so `test/reference/constraints.tsp` exercises every constraint keyword once, on the type it
+  is legal on.
+- **Every counting arm has a non-vacuity floor.** An arm that stops firing otherwise reports agreement
+  about nothing, which has happened here and is why the floors exist.
+- **The emitted output is compiled** by the real compiler under `strict` and
+  `exactOptionalPropertyTypes`, because "it emitted" is not "it works".
+- **The package is packed and its tarball inspected**, because `files` is a set of globs and a glob
+  that stops matching is indistinguishable from one that matches nothing.
+
+## Licence
+
+MIT

package/dist/src/api.d.ts

@@ -0,0 +1,304 @@
+import { type EmitContext, type Program, type Type } from "@typespec/compiler";
+import { type HttpOperation, type HttpService } from "@typespec/http";
+import { SchemaRegistry } from "./registry.js";
+/**
+ * `typespec-http-zod` — Zod validators and framework-free contract types from a TypeSpec HTTP
+ * service, agreeing with the OpenAPI document `@typespec/openapi3` publishes from the same source.
+ *
+ * **The governing rule: if the document cannot say it, the validator must not enforce it.** A
+ * validator that checks something the published contract never states is a rule no caller reading
+ * that contract can see. This package ships **zero decorators** for exactly that reason — four were
+ * deleted, each of which let a spec state something openapi3 could not publish — and asserts the
+ * class is empty rather than trusting it. Where openapi3 decides something, its rule is read from its
+ * source and copied, refusals included: the same spec has to be representable by both emitters or by
+ * neither, or a differential between them means nothing.
+ *
+ * **Why not `@typespec/http-server-js`.** The first-party JS server emitter is `0.58.0-alpha.*`,
+ * self-describes as "highly experimental", and emits a Node.js `http` router. It also answers a
+ * different question: this package emits no server at all. Validators are useful to Express, Fastify,
+ * Elysia, a Workers fetch handler or a typed client, and a server generator is a thin consumer of
+ * them — `typespec-hono` is one.
+ *
+ * **Built on the stable 1.x surface only** — `$onEmit` plus `@typespec/http` — rather than on
+ * `@typespec/emitter-framework` (pre-1.0) or `@typespec/asset-emitter`, which announces its own
+ * replacement in its package description. Fewer moving parts under something that has to keep working.
+ */
+export { $lib } from "./lib.js";
+/**
+ * The option contract, published so an emitter built on this library can **derive** its own rather
+ * than restate it.
+ *
+ * ⚠️ **Two schemas that have to agree are two lists that will not.** A server generator adds its own
+ * keys and forwards the rest; if it restates this one, an option added here is silently rejected as
+ * unknown by the wrapper, or accepted and never passed on. Neither failure is visible in output.
+ */
+export { EmitterOptionsSchema, type EmitterOptions } from "./lib.js";
+/**
+ * How a property name is spelled as an object key — quoted only when it has to be.
+ *
+ * ⚠️ **Published because a consumer emitting code beside these validators has to spell keys the
+ * SAME way, and getting it wrong produces a file that does not parse.** An unquoted
+ * `x-ms-test-header` is exactly that, and it happened: a corpus scenario declares one and the
+ * emitted module stopped being loadable. This is not a style choice a second emitter may make
+ * independently.
+ */
+export { objectKey } from "./zod.js";
+/**
+ * The success status a row registers.
+ *
+ * An operation declares exactly one success status. A range (`2XX`) or a wildcard is not a status a
+ * handler can return, so it is not something this emitter can turn into a `respond()` call — an
+ * operation carrying only those is skipped rather than guessed at.
+ */
+export declare function successStatusOf(operation: HttpOperation): number | undefined;
+/**
+ * **Every** success status the operation declares, ascending.
+ *
+ * An operation that answers `202` when the work was merely accepted and `200` when it completed
+ * inline declares both, and something has to choose. A route with two declared statuses and no way to
+ * choose would always answer the first, publishing a status that can never occur; the arm carrying
+ * asserts the two stay in step.
+ */
+export declare function successStatusesOf(operation: HttpOperation): number[];
+/**
+ * A status as the DOCUMENT keys it: an exact code, a `4XX` bucket, or the catch-all.
+ *
+ * `"default"` is kept as itself rather than mapped to a number. The document means "any status not
+ * listed above", and inventing one would be answering a question the contract left open.
+ */
+export type StatusKey = number | "default" | `${1 | 2 | 3 | 4 | 5}XX`;
+/**
+ * The body every `@error` response in the service declares, when they all declare the same one.
+ *
+ * ⚠️ **The emitter does not know what a problem document is, and must not.** This is the general
+ * capability — "a service may declare an error response; emit its validator so the runtime can check
+ * what it sends" — which is what makes it reusable by any gateway built on this emitter rather than a
+ * CM-shaped special case. RFC 9457 happens to be what `cm-api` puts in that slot.
+ *
+ * ⚠️ **This used to be an INVARIANT the emitter enforced, and it is now merely an observation.** It
+ * reported `mixed-error-bodies` — an error, aborting the compile — whenever a service declared two
+ * catch-all bodies, or a specific status whose body neither was nor spread the catch-all one. That
+ * was a real constraint while every failure arm carried this single schema; now each declared
+ * response resolves its own, and a service answering `404` with `NotFoundError` and everything else
+ * with `DefaultError` is an ordinary contract that the generated server serves correctly.
+ *
+ * So the refusal is gone, and what remains is a convenience: the module-level `GENERATED_ERROR_SCHEMA`
+ * the route table publishes, which exists precisely when the service has one such body. Where it does
+ * not, the constant is not emitted — and a consumer importing it gets a missing export, named at the
+ * import, which is the honest report of "there is no such thing here".
+ */
+export declare function errorBodyOf(program: Program, service: HttpService): Type | undefined;
+/**
+ * Whether a body served under these media types is RAW BINARY rather than a JSON value.
+ *
+ * ⚠️ **The distinction decides whether a validator may say anything about it at all.** A `bytes`
+ * body inside a JSON payload is base64 and the document publishes `type: "string"` with
+ * `contentEncoding`; a `bytes` body served as `application/octet-stream` or `image/png` is the bytes
+ * themselves, and `@typespec/openapi3` publishes a schema carrying only `contentMediaType` — which is
+ * an ANNOTATION under JSON Schema 2020-12, not an assertion. The document therefore states nothing
+ * about the value, and a validator that requires a string enforces a rule no caller reading the
+ * contract can see.
+ *
+ * ⚠️ **The same decision was already made for multipart and not for bodies**, which is how the two
+ * came to disagree: a binary PART is `z.unknown()` because openapi3 publishes `{}` for it, while a
+ * binary BODY stayed `z.string()`. Found by grading response-body kinds, a surface that had been
+ * counted and never compared — three positions in `encode/bytes`.
+ */
+export declare function isRawBinaryMediaType(contentTypes: readonly string[]): boolean;
+export interface EmittedRoute {
+    readonly operationId: string;
+    readonly verb: string;
+    readonly path: string;
+    readonly statusCode: number;
+    readonly statusCodes: readonly number[];
+    /** Media types the success body can be served as — the basis for `Accept` negotiation. */
+    readonly responseContentTypes: readonly string[];
+    /**
+     * Media types the request body may be SENT as.
+     *
+     * ⚠️ **This was missing entirely, and its absence was two live defects in the generated server.**
+     * The response side has carried `responseContentTypes` from the beginning; the request side carried
+     * nothing, so a server built on this library had no way to ask what the incoming body actually is.
+     * Both consequences were measured against a Petstore server under `wrangler dev`:
+     *
+     * - every request body was validated as JSON, so a `multipart/form-data` upload was handed to
+     *   `c.req.json()` — 17 such registrations in `payload/multipart` alone, and 11 of the 17 request
+     *   bodies in the Swagger Petstore are not JSON;
+     * - a `bytes` body was read with `c.req.text()` whatever it was sent as, which UTF-8-decodes. An
+     *   18-byte binary upload arrived at the handler as 23 code points with five bytes replaced by
+     *   U+FFFD — silently corrupted, answering **200**.
+     *
+     * A server emitter needs the document's own answer to "what is on the wire", and this is it.
+     * What to DO about it — which validator target, which body reader — belongs to the emitter that
+     * writes the server, exactly as `responseContentTypes` leaves negotiation to it.
+     */
+    readonly requestContentTypes: readonly string[];
+    readonly summary: string | undefined;
+    readonly requestSchema: string | undefined;
+    /**
+     * The parameters, split by WHERE they arrive — see `parameterSchemasOf`.
+     *
+     * ⚠️ **A MERGED `paramsSchema` sat beside these and was deleted before 0.1.0 froze the surface.**
+     * It was written on every route and read by nothing — not `nameRouteSchemas`, which declares from
+     * the split forms, and not the one consumer. Worse, it was computed by a second function under
+     * different rules, and both wire fixes the split forms received had been applied only there: it
+     * never decoded a path or query value, so `z.number().int()` met `"1"` and refused it, and it keyed
+     * headers on the TypeSpec property name rather than the wire name, which 400s every conformant
+     * request. It read as "the parameters" and was the field an adopter reached for first.
+     */
+    readonly pathSchema: string | undefined;
+    readonly querySchema: string | undefined;
+    readonly headerSchema: string | undefined;
+    /** The header schema minus `accept`, used when this route's operations negotiate. */
+    readonly negotiatedHeaderSchema: string | undefined;
+    /** The `accept` literal this operation answers to, when it declares one. */
+    readonly accept: {
+        readonly name: string;
+        readonly value: string;
+    } | undefined;
+    /**
+     * `undefined` when the operation's success response carries no body — a `204`, or any `@delete`
+     * returning `void`.
+     *
+     * ⚠️ **This used to be required, and requiring it silently deleted routes.** `collectRoutes`
+     * skipped any operation `successBodyOf` could not answer for, with no diagnostic: measured across
+     * `@typespec/http-specs`, the document declared 540 operations and this emitter mounted 256, with
+     * 282 of the 284 missing ones bodyless. `payload/multipart` produced `GENERATED_ROUTES = []`
+     * against seventeen declared operations and compiled clean. Even `parameters/path` lost both of
+     * its operations, because they answer `NoContentResponse`.
+     *
+     * A bodyless success is ordinary HTTP, not an edge case. The route is emitted; a server
+     * answers the declared status with no body.
+     */
+    readonly responseSchema: string | undefined;
+    /**
+     * The input property that receives the UNPARSED body, when the operation declares one.
+     *
+     * A `bytes` body means the bytes themselves are the contract: where a signature covers exactly
+     * what arrived, parsing and re-serialising would verify a different string than the sender signed.
+     */
+    readonly rawBodyProperty: string | undefined;
+    /** Declared failures, each with the schema for its OWN body, in OpenAPI's precedence order. */
+    readonly errorArms: readonly {
+        readonly status: StatusKey;
+        readonly schema: string | undefined;
+    }[];
+    /**
+     * No caller is established, so the operation receives no `ServiceContext`.
+     *
+     * Whether a tenant exists follows from whether the request was authenticated — there is no user,
+     * account or membership to build one from otherwise. Reading it here is what lets a server
+     * derive an operation's call shape rather than a hand-written table restating it per row.
+     */
+    readonly noAuth: boolean;
+    /**
+     * The OAuth scopes the operation requires, from `@useAuth`.
+     *
+     * ⚠️ **Per operation, never per surface.** A resource-wide list means either one scope for
+     * everything (a read-only grant could write) or the union of them (a read-only grant could not
+     * read), and neither is a grant a human would recognise from the consent screen. Emitted into the
+     * row so a server applies the gate the DOCUMENT publishes, rather than a hand-written
+     * `requireScopes(...)` repeated per route that nothing checks against it.
+     */
+    readonly scopes: readonly string[];
+    /** Which of two success statuses to answer, and the literal property that decides it. */
+    readonly statusBy: {
+        property: string;
+        value: boolean | string;
+        status: number;
+    } | undefined;
+    /** The schema for the SECOND success status, when the operation declares two distinct arms. */
+    readonly alternateResponseSchema: string | undefined;
+}
+export declare function collectRoutes(program: Program, registry: SchemaRegistry, service: HttpService): EmittedRoute[];
+/**
+ * The identifiers a route's validators are declared under, by what the DOCUMENT calls each one.
+ *
+ * ⚠️ **Keyed on request locations, not on a router's validator targets.** `@hono/zod-validator`
+ * spells these `"param"`, `"query"`, `"header"`, `"json"`; another framework spells them differently
+ * or not at all. The location is the contract fact and belongs here; the spelling is the server
+ * emitter's, and translating one to the other is a two-line map in the package that knows.
+ */
+export interface RouteSchemaNames {
+    readonly operationId: string;
+    readonly path: string | undefined;
+    readonly query: string | undefined;
+    readonly header: string | undefined;
+    readonly body: string | undefined;
+    readonly response: string | undefined;
+    readonly alternateResponse: string | undefined;
+    /**
+     * The `readonly ResponseArm[]` const — what the operation may answer with, and with which body.
+     *
+     * Always present, because every operation declares at least its success status. An operation whose
+     * every arm is bodyless still gets the const, carrying `schema: undefined` per arm, which is the
+     * document's own answer rather than an absence a consumer has to interpret.
+     */
+    readonly responses: string;
+}
+/**
+ * One `@service`, emitted — and everything a server emitter needs to render a router over it.
+ *
+ * ⚠️ **This is the shared seam, and it is deliberately narrow.** It carries no `SchemaRegistry`, no
+ * import collector, no error schema and no vocabulary map, because measurement said a server
+ * generator reads none of them: the registry is never touched once the names are minted, the external
+ * imports serve the very declarations that now live in `schemas.gen.ts`, the error schema fed a route
+ * table that no longer exists, and the vocabularies feed this library's own renderer. The smallest
+ * surface that works is the one to freeze; anything else is added when something demonstrates a need
+ * for it, with the reason recorded.
+ */
+export interface EmittedService {
+    readonly service: HttpService;
+    readonly routes: readonly EmittedRoute[];
+    /** The identifiers every per-operation validator was declared under, keyed by operation id. */
+    readonly schemaNames: ReadonlyMap<string, RouteSchemaNames>;
+    /** Where this service's artefacts were written — a server emitter writes its own beside them. */
+    readonly outputDir: string;
+    /** Already resolved through the per-service overrides, so a caller re-reads nothing. */
+    readonly options: ResolvedServiceOptions;
+}
+/** The options for one service, with every per-service override already applied. */
+export interface ResolvedServiceOptions {
+    readonly contractsOutputDir: string | undefined;
+    readonly contractsPackage: string | undefined;
+    readonly sealObjectSchemas: boolean;
+    readonly keyVocabularies: readonly string[];
+    readonly runtimeModule: string;
+}
+/** What the generated files import their runtime contract from when nothing says otherwise. */
+export declare const DEFAULT_RUNTIME_MODULE = "typespec-http-zod/runtime";
+/**
+ * What a WRAPPING emitter may change about this one, without changing what a consumer may set.
+ *
+ * ⚠️ **`defaultRuntimeModule` is a default, not an override.** A consumer's `runtime-module` still
+ * wins; this only decides what `schemas.gen.ts` and any file a wrapper emits beside it import from
+ * when the consumer says nothing.
+ *
+ * ⚠️ **It exists because this package's own default is wrong for a wrapper, and shipped that way.**
+ * `typespec-hono` emits `import type { AppEnv, Awaitable, Ctx, Result, RouteDeps }` and
+ * `import { selectContentType }` from whatever this resolves to. None of those six is exported here —
+ * this module exports `ResponseArm` and `armFor`, and nothing else. Worse, `typespec-http-zod` is a
+ * TRANSITIVE dependency of a `typespec-hono` consumer, so under a strict `node_modules` the specifier
+ * does not resolve at all whatever it exports. Measured in a fresh project installed from tarballs:
+ * `tsp compile` succeeded with zero diagnostics and `tsc` then reported **two `TS2307`s**, one in each
+ * generated file.
+ *
+ * Nothing in either suite saw it, because every compile in both harnesses sets `runtime-module`
+ * explicitly. The default branch was ungraded across 240 tests.
+ */
+export interface EmitHttpZodOptions {
+    /** The specifier generated files import their runtime contract from when the consumer sets none. */
+    readonly defaultRuntimeModule?: string;
+}
+/**
+ * Emit this library's artefacts for every `@service` in the program, and hand back what was emitted.
+ *
+ * ⚠️ **The whole orchestration lives here, once.** The nesting below is load-bearing — a walk that
+ * runs outside `collectExternalImports` throws, vocabularies must be collected from what the service
+ * DECLARES rather than from what the Zod walk happens to touch, and the error body has to be
+ * registered inside the walk or its validator never reaches `schemas.gen.ts`. An emitter built on this
+ * library calls this rather than restating it: two copies of a sequence that must agree are two
+ * copies that will not, and the symptom would be a subtly different set of declarations in a file
+ * whose name is the contract.
+ */
+export declare function emitHttpZod(context: EmitContext, wrapper?: EmitHttpZodOptions): Promise<readonly EmittedService[]>;