typespec-http-zod 0.1.0

package/dist/src/api.js

@@ -0,0 +1,1425 @@
+import { emitFile, getDoc, getEncode, getSummary, isErrorModel, isNeverType, isVoidType, resolvePath, } from "@typespec/compiler";
+import { getAuthenticationForOperation, resolveRequestVisibility, Visibility, } from "@typespec/http";
+import { resolveOperationId } from "@typespec/openapi";
+import { reportDiagnostic } from "./lib.js";
+import { SchemaRegistry, TypeRegistry } from "./registry.js";
+import { resolveStreamModule, streamedTypeOf, withStreamModule } from "./streams.js";
+import { resolveVersioningModule, serviceSnapshots } from "./versioning.js";
+import { collectExternalImports, noteDeclaredVocabularies, noteKeyVocabularies, objectKey, withContractsPackage, withSealedObjects, withVisibility, } from "./zod.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 } 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";
+/** Named once. The emitted banner and the internal-invariant messages both quote it. */
+const PACKAGE_NAME = "typespec-http-zod";
+/**
+ * The header every emitted file carries.
+ *
+ * ⚠️ **This once named one repository's build script** — `pnpm --filter … generate`, a command that
+ * exists in exactly one checkout. A generated file is the most-read artefact an emitter produces, and
+ * a banner sending the reader to a script they do not have is worse than no instruction at all.
+ *
+ * The package name stays, because that IS the answer to "what wrote this". The instruction becomes
+ * the one thing true for every consumer: recompile the source, do not edit the output.
+ */
+const GENERATED_BANNER = `// GENERATED by ${PACKAGE_NAME} from the TypeSpec service definition. DO NOT EDIT.
+// Recompile the spec that produced it; edits here are overwritten on the next run.
+`;
+/**
+ * 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 function successStatusOf(operation) {
+    return successStatusesOf(operation)[0];
+}
+/**
+ * **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 function successStatusesOf(operation) {
+    const codes = [];
+    for (const response of operation.responses) {
+        const code = response.statusCodes;
+        if (typeof code === "number" && code >= 200 && code < 300)
+            codes.push(code);
+    }
+    return [...new Set(codes)].toSorted((a, b) => a - b);
+}
+/** The five buckets OpenAPI can express a status RANGE as, in the order it names them. */
+const STATUS_RANGE_GROUPS = [1, 2, 3, 4, 5];
+/**
+ * What the document will key this response under — **openapi3's rule, copied, not re-derived.**
+ *
+ * ⚠️ **`HttpStatusCodesEntry` is `HttpStatusCodeRange | number | "*"`, and the third case was
+ * silently dropped.** A response declared `@minValue(400) @maxValue(499) @statusCode _: int32` is a
+ * `4XX` entry in the document and was emitted NOWHERE here: not refused, not warned about, just
+ * absent from the arms — so a service could publish a whole class of failures and hand `respond`
+ * nothing to check them against. Two of the two operations in `response/status-code-range` lost an
+ * arm each this way, and the emitter's own `mixed-error-bodies` refusal was firing over the same
+ * scenario for an unrelated and by then obsolete reason, which is how it stayed hidden.
+ *
+ * ⚠️ **A partial range is REFUSED, because `@typespec/openapi3` refuses it.** `494-499` does not
+ * cover the `4XX` bucket, and bucketing it anyway would have the server claim that a `400` carries
+ * `ErrorInRange` — a rule no document states, since openapi3 declines to publish a document at all.
+ * Agreeing with the reference implementation is the whole point of copying its line: the same spec
+ * is either representable by both or by neither.
+ *
+ * `@defaultResponse` is not tested separately the way openapi3 tests it; `@typespec/http` resolves
+ * that decorator to `"*"` before we see it, so the one check covers both spellings.
+ */
+function statusKeysOf(program, response) {
+    const codes = response.statusCodes;
+    if (codes === "*")
+        return ["default"];
+    if (typeof codes === "number")
+        return [codes];
+    const keys = [];
+    let { start, end } = codes;
+    const refuse = () => {
+        reportDiagnostic(program, {
+            code: "unsupported-status-code-range",
+            target: response.type,
+            format: { start: String(codes.start), end: String(codes.end) },
+        });
+    };
+    if (start < 100) {
+        refuse();
+        start = 100;
+        keys.push("default");
+    }
+    else if (end > 599) {
+        refuse();
+        keys.push("default");
+        end = 599;
+    }
+    for (const group of STATUS_RANGE_GROUPS) {
+        if (start > end)
+            break;
+        const groupStart = group * 100;
+        const groupEnd = groupStart + 99;
+        if (start >= groupStart && start <= groupEnd) {
+            keys.push(`${group}XX`);
+            if (start !== groupStart || end < groupEnd)
+                refuse();
+            start = groupStart + 100;
+        }
+    }
+    return keys;
+}
+/** Whether a document status key describes a SUCCESS, so the success arms already carry it. */
+function isSuccessKey(status) {
+    return status === "2XX" || (typeof status === "number" && status >= 200 && status < 300);
+}
+/**
+ * Every FAILURE arm the operation declares, each with the schema for ITS OWN body.
+ *
+ * ⚠️ **None of these reached the generated output at all, and a census is the proof.** Measured on one
+ * service, the document declared `200`x9, `201`x3, `202`x1, `401`x1 and `default`x2, and only the
+ * first three were emitted. So the schema for a failure never arrived, and no application could have
+ * checked what it sends when something goes wrong even if it wanted to.
+ *
+ * ⚠️ **Then every arm that did arrive carried the SERVICE-WIDE error schema.** The spike declares
+ * `@error model WebhookUnauthorized { ...ProblemDetails; @statusCode 401 }` and openapi3 publishes
+ * the 401 as `$ref: WebhookUnauthorized` while we answered with `problemDetailsSchema`. The shapes
+ * were identical there, so nothing was mis-validated — but the component the document names for that
+ * response had no declaration at all.
+ *
+ * ⚠️ **`"default"` used to be the one arm with no body of its own**, filled in downstream from the
+ * service-wide schema. That was backwards: a catch-all response declares a body like any other
+ * response, and `response/status-code-range` gives two operations whose `default` is a DIFFERENT
+ * model from every other failure they declare. Reading each response's own body answers all three at
+ * once, and is why the emitter no longer needs to believe a service has one error shape.
+ *
+ * Arms come out in the order OpenAPI resolves them — exact codes, then ranges, then the catch-all —
+ * so a consumer scanning for the first match applies the precedence the specification states.
+ */
+function errorArmsOf(program, operation, registry) {
+    const arms = new Map();
+    for (const response of operation.responses) {
+        for (const status of statusKeysOf(program, response)) {
+            if (isSuccessKey(status) || arms.has(status))
+                continue;
+            arms.set(status, bodySchemaOf(response, registry));
+        }
+    }
+    return [...arms]
+        .map(([status, schema]) => ({ status, schema }))
+        .toSorted((a, b) => statusPrecedenceOf(a.status) - statusPrecedenceOf(b.status));
+}
+/**
+ * Where an arm sits in OpenAPI's own precedence order.
+ *
+ * ⚠️ **The specification decides this, not us.** The Responses Object says a range MAY be given as
+ * an uppercase `X` wildcard, and that "if a response is defined using an explicit code, the explicit
+ * code definition takes precedence over the range definition for that code". `default` is by
+ * definition every status not otherwise listed, so it is last. Emitting the arms already sorted is
+ * what lets a consumer take the first match and be right — the alternative is every application
+ * re-deriving the rule, and getting it wrong quietly when a range and an exact code both apply.
+ */
+function statusPrecedenceOf(status) {
+    if (status === "default")
+        return 2;
+    return typeof status === "number" ? 0 : 1;
+}
+/** A response's own body, as an emitted Zod expression — `undefined` where it declares none. */
+function bodySchemaOf(response, registry) {
+    for (const content of response.responses) {
+        if (content.body?.bodyKind !== "single")
+            continue;
+        const type = bodyTypeOf(content.body.type);
+        if (type !== undefined)
+            return registry.expressionFor(type);
+    }
+    return undefined;
+}
+/**
+ * Whether the operation declares `@useAuth(NoAuth)` — no caller is established for it.
+ *
+ * ⚠️ **`@useAuth(NoAuth)` reaches OpenAPI as `security: []`, which is why this is derivable at all.**
+ * Whether an operation needs a caller is a contract fact the document publishes. What KIND of caller
+ * — account-scoped, resource-scoped — is not: no OpenAPI keyword expresses it, and a server emitter
+ * that guesses is enforcing something no document states.
+ */
+function noAuthFor(program, operation) {
+    return (getAuthenticationForOperation(program, operation.operation)?.options.some((option) => option.schemes.some((scheme) => scheme.type === "noAuth")) === true);
+}
+/**
+ * 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 function errorBodyOf(program, service) {
+    const canonical = new Set();
+    const specific = new Set();
+    for (const operation of service.operations) {
+        for (const response of operation.responses) {
+            /**
+             * ⚠️ `@error` sits on the RESPONSE type, which is not always the body type.
+             *
+             * Two declaration styles are both idiomatic and both occur. One returns the error model bare
+             * (`op x(): Foo | ProblemDetails`), so response type and body type are the same; the other wraps
+             * it (`@error model ErrorResponse { @statusCode …; @body body: Problem }`), so the `@error` is
+             * on the wrapper and the body is a plain model. Testing the body missed the second style
+             * entirely — measured on a surface declaring an error on all
+             * eleven operations and this found none of them.
+             */
+            if (!isErrorModel(program, response.type))
+                continue;
+            for (const content of response.responses) {
+                const body = content.body;
+                if (body?.bodyKind !== "single")
+                    continue;
+                /**
+                 * ⚠️ **An error response can declare no body either.** `tsp-openapi3` renders a bare
+                 * `default` response as `DefaultResponse<Body = void>`, so the Swagger Petstore reaches
+                 * here with the `void` intrinsic — which was then registered as the service's error schema
+                 * and refused by the Zod walk. There is nothing there to validate.
+                 */
+                const type = bodyTypeOf(body.type);
+                if (type === undefined)
+                    continue;
+                // `"*"` is what `@error` resolves to when the model declares no status — the operation's
+                // general "any failure" contract, and the shape the runtime constructs.
+                (response.statusCodes === "*" ? canonical : specific).add(type);
+            }
+        }
+    }
+    /**
+     * Two catch-all bodies means there is no "the" service-wide error body, so there is nothing to
+     * publish — which is a reason to emit no constant, not a defect to refuse. Each operation's own
+     * `default` arm carries its own schema, and that is what the server validates against.
+     */
+    if (canonical.size > 1)
+        return undefined;
+    const [body] = canonical;
+    if (body !== undefined)
+        return body;
+    /**
+     * A service can decline to declare a catch-all and still have one error shape — ten specific
+     * statuses carrying one problem model between them. That is a service-wide
+     * body by any honest reading. Two different ones is not, and picking the first would be naming a
+     * contract fact by iteration order.
+     */
+    return specific.size === 1 ? [...specific][0] : undefined;
+}
+/**
+ * A response's body type, or `undefined` where it declares no body.
+ *
+ * ⚠️ **`void` and `never` ARE "no body", wherever they appear.** Answering that in one place is the
+ * whole point: the fact reached this emitter by three different roads and each one had to learn it
+ * separately otherwise. A `204` with no content at all; an `op remove(): void`; and — the road that
+ * actually broke the Swagger Petstore — `tsp-openapi3` writing a `default` error response as
+ * `DefaultResponse<Body = void>`. Returned as a type, any of them is walked and refused with
+ * `Cannot emit Zod for Intrinsic: 'void' has no runtime representation'`.
+ */
+function bodyTypeOf(type) {
+    return isVoidType(type) || isNeverType(type) ? undefined : type;
+}
+/**
+ * The declared body type of the operation's success response, if it has one.
+ *
+ * ⚠️ **`void` and `never` ARE "no body", and reading them as types was a defect.** A response with
+ * no content reaches this in two shapes: as no body at all, which `undefined` already covered, and
+ * as a body whose type is `void` — which is what `tsp-openapi3` writes when it converts a `204`,
+ * and what `op remove(): void` means. The second used to be returned as a type, walked, and refused
+ * with `Cannot emit Zod for Intrinsic: 'void' has no runtime representation'`. That took out the
+ * Swagger Petstore, the most widely implemented reference API there is, on the round-trip suite's
+ * first run.
+ *
+ * One fact arriving by two roads. Answering it here rather than at each of the four call sites is
+ * what keeps them from drifting — `collectRoutes`, the contract types, the dual-status
+ * discriminator and the alternate-arm schema all want the same answer to the same question.
+ */
+function successBodyOf(operation, status) {
+    for (const response of operation.responses) {
+        if (response.statusCodes !== status)
+            continue;
+        for (const content of response.responses) {
+            if (content.body?.bodyKind !== "single")
+                continue;
+            return bodyTypeOf(content.body.type);
+        }
+    }
+    return undefined;
+}
+/**
+ * The media types this operation's success response can be served as.
+ *
+ * ⚠️ **The fact that decides whether two operations are a collision or a CHOICE.** TypeSpec models
+ * content negotiation as several operations on one route, each accepting a different media type;
+ * OpenAPI models it as one path entry whose response lists them all. This emitter read neither, so
+ * it registered every operation and Hono — which matches in registration order — left all but the
+ * first as dead code that looks mounted.
+ *
+ * Empty when the response carries no body, which is not the same as a body served as anything.
+ */
+function responseContentTypesOf(operation, status) {
+    const types = new Set();
+    for (const response of operation.responses) {
+        if (response.statusCodes !== status)
+            continue;
+        for (const content of response.responses) {
+            for (const contentType of content.body?.contentTypes ?? [])
+                types.add(contentType);
+        }
+    }
+    return [...types];
+}
+/** Whether a type is an array — TypeSpec models one as a `Model` carrying an integer indexer. */
+function isArrayType(type) {
+    return type.kind === "Model" && type.indexer?.key.name === "integer";
+}
+/**
+ * How to choose between an operation's two success statuses, read from the declared arms.
+ *
+ * ⚠️ **A discriminator, not a trial-parse.** "Try the 200 schema, and if it fails use the 202" is the
+ * banned fallback wearing a different hat: a genuine validation failure on the first arm would be
+ * reported as the second arm's shape. Each arm pins a **required literal** property instead —
+ * `awaiting: true` on the accepted one — and a consumer reads that one property.
+ *
+ * This replaces hand-written per-operation closures, which existed only because a spec declaring the
+ * SAME body model for both statuses could not say which was which.
+ */
+function statusDiscriminatorOf(operation, statuses) {
+    if (statuses.length < 2)
+        return undefined;
+    for (const status of statuses) {
+        const body = successBodyOf(operation, status);
+        if (body?.kind !== "Model")
+            continue;
+        for (const [name, property] of body.properties) {
+            // The OTHER arm carries the same property as optional; a required literal is the mark.
+            if (property.optional)
+                continue;
+            if (property.type.kind === "Boolean" || property.type.kind === "String") {
+                return { property: name, value: property.type.value, status };
+            }
+        }
+    }
+    return undefined;
+}
+/** The emitted schema for a specific success status, used for the second arm of a dual-status op. */
+function alternateSchemaFor(operation, status, registry) {
+    const body = successBodyOf(operation, status);
+    return body === undefined ? undefined : registry.expressionFor(body);
+}
+/**
+ * The Zod for a **multipart** request body, built from its parts.
+ *
+ * ⚠️ **`requestBodyOf` returns a type only for `bodyKind === "single"`, so every multipart operation
+ * was mounted with NO body validator at all** — 19 routes across `payload/multipart` and 12
+ * components the document declares that nothing here could check. Not a refusal, not a diagnostic:
+ * silently unvalidated, which is the failure mode this emitter exists to remove.
+ *
+ * `HttpPart<T>` is unwrapped to `T`, which is what the document publishes — `HttpPart<string>` is
+ * `{type: "string"}` and `HttpPart<Address>` is a `$ref`.
+ *
+ * ⚠️ **A binary part is `z.unknown()`, deliberately.** `SCALARS` maps `bytes` to `z.string()`, which
+ * is right for a JSON body (base64) and wrong here: in a multipart part `bytes` is raw binary, and
+ * openapi3 publishes `{}` for it — no type at all. Emitting `z.string()` would enforce a rule the
+ * document does not state AND reject what a server actually receives, since `c.req.parseBody()`
+ * hands back a `File`. The type of a value is positional, exactly as its visibility is.
+ */
+function multipartSchemaOf(body, registry) {
+    const entries = body.parts.map((part) => {
+        const type = part.body?.type;
+        const inner = type === undefined || isBinaryPart(type) ? "z.unknown()" : registry.expressionFor(type);
+        // `multi` is `HttpPart<T>[]` — the same part repeated, which arrives as an array.
+        const value = part.multi === true ? `z.array(${inner})` : inner;
+        return `\t${objectKey(part.name ?? "")}: ${part.optional === true ? `${value}.optional()` : value},`;
+    });
+    const shape = entries.length === 0 ? "z.object({})" : `z.object({\n${entries.join("\n")}\n})`;
+    /**
+     * Declared under the model's own name when it has one, because the document publishes a component
+     * for it. Emitted inline the schema is correct and the component still has no validator, which the
+     * differential reports — rightly — as a contract the runtime cannot check.
+     */
+    const named = body.type;
+    const name = named !== undefined && named.kind === "Model" && named.name !== "" ? named.name : undefined;
+    return name === undefined ? shape : registry.declareNamed(name, () => shape);
+}
+/** `bytes`, or a model built on `File` — the parts openapi3 publishes as an empty schema. */
+function isBinaryPart(type) {
+    if (type.kind === "Scalar") {
+        for (let scalar = type; scalar !== undefined; scalar = scalar.baseScalar) {
+            if (scalar.name === "bytes")
+                return true;
+        }
+        return false;
+    }
+    if (type.kind !== "Model")
+        return false;
+    for (let model = type; model !== undefined; model = model.baseModel) {
+        if (model.name === "File")
+            return true;
+    }
+    return false;
+}
+/**
+ * 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 function isRawBinaryMediaType(contentTypes) {
+    if (contentTypes.length === 0)
+        return false;
+    return contentTypes.every((type) => !/^application\/(json|.*\+json)$/.test(type));
+}
+/** The declared request body type, if the operation takes one. */
+function requestBodyOf(operation) {
+    const body = operation.parameters.body;
+    return body?.bodyKind === "single" ? body.type : undefined;
+}
+/**
+ * Parameters are emitted as their **own** schemas rather than folded into the body, because the two
+ * are separate things in HTTP and in OpenAPI — but they are equally part of the operation's input,
+ * and `?state=nonsense` must be a 400 rather than something the application has to defend against.
+ * Leaving them undescribed would document a constraint the runtime does not enforce, which is the
+ * same failure the vocabulary tuples exist to prevent one level down.
+ *
+ * ⚠️ **Split by WHERE they arrive, and only so.** A validator library validates one target at a time
+ * — `("param", …)`, `("query", …)` — which is how a caller learns *which* part of the request was
+ * wrong instead of being handed a merged object's complaint. A merged form existed beside these until
+ * 0.1.0 and was deleted: nothing read it, and it had drifted into a second set of rules. See
+ * `EmittedRoute.pathSchema`.
+ */
+/**
+ * How a list is flattened into one query or header value, per OpenAPI's `style`.
+ *
+ * ⚠️ **Three of the four standard collection formats rejected every conformant request**, and only
+ * one of the three was visible to the differential. `?colors=blue,red,green` arrives as a single
+ * string; a validator expecting an array refuses it. For `pipes` and `ssv` the emitter also typed
+ * the parameter as a string, so document and validator disagreed and the oracle said so — but for
+ * `csv` both sides said `array` and **agreed perfectly** while the server 400'd every caller. No
+ * document-to-validator comparison can see that: the disagreement is with the WIRE.
+ *
+ * `explode: true` is the exception — the value repeats (`?colors=blue&colors=red`) and Hono hands
+ * back an array already, so there is nothing to undo.
+ */
+const COLLECTION_DELIMITERS = {
+    "ArrayEncoding.pipeDelimited": "|",
+    "ArrayEncoding.spaceDelimited": " ",
+    "ArrayEncoding.commaDelimited": ",",
+    "ArrayEncoding.newlineDelimited": "\n",
+};
+/** Whether the declared type is a list, which is what makes a delimiter meaningful. */
+function isCollectionParameter(property) {
+    return isArrayType(property.type);
+}
+/**
+ * The delimiter a parameter's values were joined with, or `undefined` when they were not joined.
+ *
+ * Defaults matter as much as the encodings: a query parameter with no `@encode` and no explode is
+ * `form` style, which OpenAPI joins with a comma, and a header list is `simple` style, also comma.
+ * Those are the two that looked correct because the document and the validator agreed.
+ */
+function collectionDelimiterOf(program, parameter) {
+    if (!isCollectionParameter(parameter.param))
+        return undefined;
+    if (parameter.type !== "query" && parameter.type !== "header")
+        return undefined;
+    if (parameter.explode === true)
+        return undefined;
+    const encoding = getEncode(program, parameter.param)?.encoding;
+    if (encoding !== undefined && encoding in COLLECTION_DELIMITERS) {
+        return COLLECTION_DELIMITERS[encoding];
+    }
+    return ",";
+}
+/**
+ * Decode a path, query or header value from the only thing HTTP can carry: text.
+ *
+ * ⚠️ **A path or query parameter ALWAYS arrives as a string, and `type: integer` describes what it
+ * means once decoded — not what is on the wire.** `zValidator("param", …)` hands `c.req.param()`
+ * straight to the schema, so `z.number().int()` met `"1"` and refused it. Measured against a server
+ * generated from the Swagger Petstore and run under `wrangler dev`:
+ *
+ * ```
+ * GET /pet/findByStatus?status=available -> 200   (string)
+ * GET /user/zach                         -> 200   (string)
+ * GET /pet/1                             -> 400   (integer)   <- every conformant caller
+ * GET /store/order/1                     -> 400   (integer)
+ * ```
+ *
+ * ⚠️ **Nothing saw it because nothing ever asked.** Every path and query parameter in
+ * `test/reference/service.tsp` — the only fixture that makes real requests — is a `string`. Across
+ * the corpus this emitter writes **29 numeric query and header parameters** and requests none of
+ * them. The validators were right about the document the whole time; the disagreement was with what
+ * arrives, which is the one thing no document comparison can see.
+ *
+ * ⚠️ **This DECODES, it does not coerce.** `z.coerce.number()` would have been one character of
+ * effort and wrong: `Number("")` is `0`, so `?limit=` would satisfy a required integer and an empty
+ * value the document forbids would sail through as zero. A value that is not a well-formed number is
+ * passed along UNCHANGED, so it fails against the schema the document published and reports the error
+ * the document justifies. Same rule as the collection split above — decode the wire form, then apply
+ * the document's schema to the result, never instead of it.
+ *
+ * Derived from the emitted expression rather than a restated list of scalar names: `SCALARS` in
+ * `zod.ts` decides what becomes `z.number()`, and a second copy of that list here would stop agreeing
+ * with it silently.
+ */
+function wireDecoded(declared) {
+    const NUMBER = '(raw) => (typeof raw === "string" && raw.trim() !== "" && Number.isFinite(Number(raw)) ? Number(raw) : raw)';
+    const BOOLEAN = '(raw) => (raw === "true" ? true : raw === "false" ? false : raw)';
+    if (declared.startsWith("z.number()"))
+        return `z.preprocess(${NUMBER}, ${declared})`;
+    if (declared.startsWith("z.boolean()"))
+        return `z.preprocess(${BOOLEAN}, ${declared})`;
+    /**
+     * A list whose ELEMENTS are numeric or boolean — `?ids=1,2,3` after the collection split, or a
+     * repeated `?id=1&id=2`. The elements are strings for exactly the same reason the scalar is, so
+     * the same decoder applies per element. A non-array value is left alone; the split that produces
+     * the array runs outside this and may not have happened.
+     */
+    const element = /^z\.array\((z\.(?:number|boolean)\(\).*)\)$/s.exec(declared);
+    if (element !== null) {
+        const inner = element[1] ?? "";
+        const decoder = inner.startsWith("z.number()") ? NUMBER : BOOLEAN;
+        return `z.preprocess((raw) => (Array.isArray(raw) ? raw.map(${decoder}) : raw), ${declared})`;
+    }
+    return declared;
+}
+/**
+ * Decode a `content-type` header down to the media type the document names.
+ *
+ * ⚠️ **A media type is a type PLUS parameters, and the document states only the type.** `@header
+ * contentType: "multipart/form-data"` becomes `z.literal("multipart/form-data")`, which refuses
+ * `multipart/form-data; boundary=…` — and RFC 2046 §5.1.1 makes that boundary MANDATORY, so the
+ * validator rejected **every syntactically valid multipart request**. Measured under `wrangler dev`:
+ *
+ * ```
+ * expected "multipart/form-data"
+ * received "multipart/form-data; boundary=------------------------IQFk2KVVVwrsWuOSm212u0"
+ * ```
+ *
+ * Across the corpus this emitter writes **78 `z.literal` header validators, every one of them on
+ * `content-type`**, in 12 scenarios. Seventeen are `multipart/form-data` and fail 100% of the time;
+ * the remaining 61 refuse any caller sending the entirely legal `; charset=utf-8`.
+ *
+ * ⚠️ **Enforcing "no parameters" is enforcing something the document does not say**, which is the
+ * governing rule read in the direction that is easy to miss: the rule forbids inventing constraints
+ * just as much as it forbids dropping them. Stripping the parameters before comparing is the same
+ * move as decoding `"1"` to `1` — undo the transport form, then apply the document's schema to the
+ * result.
+ *
+ * Lowercased because RFC 9110 §8.3.1 makes media type comparison case-insensitive — but ONLY when the
+ * declared literal is itself lowercase, so a document that published an oddly-cased type keeps
+ * matching exactly rather than silently never matching. Every literal openapi3 publishes across the
+ * corpus is lowercase; this costs one condition and removes the way that fact could stop being true.
+ */
+function mediaTypeDecoded(declared) {
+    /**
+     * ⚠️ **One accepted media type is a literal; several are an ENUM, and the second form is the one a
+     * real document produces.** The corpus writes 78 `content-type` validators and every one is a
+     * single literal, so a decoder that handled only `z.literal` looked complete against it. The
+     * Swagger Petstore's `addPet` accepts three media types and openapi3 publishes
+     * `z.enum(["application/json", "application/xml", "application/x-www-form-urlencoded"])` — which
+     * went on refusing `application/json; charset=utf-8` after the literal case was fixed. Measured:
+     * with the charset parameter **400**, without it **200**, same body.
+     */
+    const values = /^z\.literal\("([^"]+)"\)/.exec(declared)?.slice(1, 2) ??
+        /^z\.enum\(\[([^\]]+)\]\)/
+            .exec(declared)?.[1]
+            ?.split(",")
+            .map((entry) => entry.trim().replace(/^"|"$/g, ""));
+    if (values === undefined || values.length === 0)
+        return declared;
+    // Lowercased only when every declared value already is, so an oddly-cased one keeps matching.
+    const normalise = values.every((value) => value === value.toLowerCase()) ? ".toLowerCase()" : "";
+    return `z.preprocess((raw) => (typeof raw === "string" ? (raw.split(";")[0] ?? "").trim()${normalise} : raw), ${declared})`;
+}
+function parameterSchemasOf(program, operation, registry) {
+    const byTarget = {};
+    let accept;
+    for (const parameter of operation.parameters.parameters) {
+        if (parameter.type !== "path" && parameter.type !== "query" && parameter.type !== "header") {
+            continue;
+        }
+        /**
+         * ⚠️ **`parameter.name` is the WIRE name; `parameter.param.name` is the TypeSpec one.** Headers
+         * used to be keyed on the second, and it made every header validator reject every conformant
+         * request: `@header("webhook-id") id: string` produced `z.object({ id })`, while `zValidator`
+         * reads what actually arrived — a header called `webhook-id`. Measured: **400 against the
+         * emitted schema, 200 against the documented one**, on a webhook's signed headers.
+         *
+         * The wire name is also the right answer for path and query where the two differ
+         * (`@query("$select") select`), and it is what `propertyKey` already does for body properties
+         * via `resolveEncodedName` — the document publishes one name per parameter, and it is this one.
+         * The TypeSpec property name is an authoring convenience that does not survive to the contract.
+         */
+        const delimiter = collectionDelimiterOf(program, parameter);
+        const declared = registry.expressionForProperty(parameter.param);
+        /**
+         * The wire form is decoded before it is validated, never instead of it. `z.preprocess` undoes
+         * exactly the flattening the document's `style` describes and then applies the schema the
+         * document publishes, so every constraint on the list — `minItems`, the element type — still
+         * runs. Splitting in the handler instead would have left those unenforced.
+         */
+        /**
+         * Decoded BEFORE the split is wrapped around it, so the two nest in wire order: the outer
+         * preprocess turns `"1,2,3"` into `["1","2","3"]`, the inner one turns those into numbers, and
+         * the document's schema then validates the result. Wrapping the other way round would hand the
+         * element decoder an unsplit string.
+         */
+        const decoded = parameter.type === "header" && parameter.name.toLowerCase() === "content-type"
+            ? mediaTypeDecoded(declared)
+            : wireDecoded(declared);
+        const expression = delimiter === undefined
+            ? decoded
+            : `z.preprocess((raw) => (typeof raw === "string" ? raw.split(${JSON.stringify(delimiter)}) : raw), ${decoded})`;
+        const entry = `\t${objectKey(parameter.name)}: ${expression},`;
+        (byTarget[parameter.type] ??= []).push(entry);
+        /**
+         * ⚠️ **On a route several operations share, `accept` SELECTS the operation — it is not a
+         * constraint on one of them.** Each member declares its own literal, so validating against any
+         * single member's would 400 every request asking for one of the others, and 400 is the wrong
+         * answer twice over: the request is well-formed, and the contract's answer to "I cannot serve
+         * what you asked for" is 406. `selectContentType` decides it instead, so the negotiated route
+         * validates every OTHER header and leaves this one to the negotiation.
+         */
+        if (parameter.type === "header" && parameter.name.toLowerCase() === "accept") {
+            const literal = parameter.param.type;
+            if (literal.kind === "String")
+                accept = { name: parameter.name, value: literal.value };
+        }
+        else if (parameter.type === "header") {
+            (byTarget["header-without-accept"] ??= []).push(entry);
+        }
+    }
+    const shape = (target) => {
+        const entries = byTarget[target];
+        return entries === undefined ? undefined : `z.object({\n${entries.join("\n")}\n})`;
+    };
+    return {
+        path: shape("path"),
+        query: shape("query"),
+        header: shape("header"),
+        negotiatedHeader: shape("header-without-accept"),
+        accept,
+    };
+}
+export function collectRoutes(program, registry, service) {
+    const routes = [];
+    {
+        for (const operation of service.operations) {
+            const statusCode = successStatusOf(operation);
+            if (statusCode === undefined)
+                continue;
+            // No body is a legitimate success — see `EmittedRoute.responseSchema`. Skipping here is what
+            // dropped 282 operations across the conformance corpus without a word.
+            const responseType = successBodyOf(operation, statusCode);
+            const requestType = requestBodyOf(operation);
+            /**
+             * ⚠️ **A streamed operation's EVENT payloads are not reachable from its body.**
+             *
+             * `op receive(): SSEStream<UnnamedEvents>` has a response body of `string` — the event
+             * stream — so the walk above sees a scalar and stops, and `Unnamed.Info` gets no validator
+             * even though the document publishes it as a component. Declaring the union here reaches
+             * every payload through it, which is the same set openapi3 emits. The result is discarded:
+             * the route's response schema is still the stream, and this exists so the vocabulary a
+             * consumer needs to check each `data:` against is actually generated.
+             */
+            const streamed = streamedTypeOf(program, operation.operation.returnType);
+            if (streamed !== undefined) {
+                withVisibility(program, Visibility.Read, () => registry.expressionFor(streamed));
+            }
+            // `@requestVisibility` when the operation states one, otherwise the verb's default — the
+            // same resolution `@typespec/openapi3` performs before emitting a request schema.
+            const requestVisibility = resolveRequestVisibility(program, operation.operation, operation.verb);
+            const statusCodes = successStatusesOf(operation);
+            const discriminator = statusDiscriminatorOf(operation, statusCodes);
+            /**
+             * A `bytes` body means the BYTES are the contract.
+             *
+             * A webhook's MAC covers exactly what arrived, so a parsed-and-re-serialised object would
+             * verify a different string and every delivery would fail authentication.
+             */
+            const bodyParameter = operation.parameters.body;
+            const rawBodyProperty = requestType?.kind === "Scalar" && requestType.name === "bytes"
+                ? (bodyParameter?.property?.name ?? "body")
+                : undefined;
+            routes.push({
+                operationId: resolveOperationId(program, operation.operation),
+                verb: operation.verb.toUpperCase(),
+                /**
+                 * The path TEMPLATE, exactly as the document publishes it — `/widgets/{widget-id}`.
+                 *
+                 * ⚠️ **This used to be a router's path, converted here.** `toHonoPath` ran during
+                 * collection and rewrote `{widget-id}` to `:widget-id`, so the shared intermediate
+                 * representation carried one framework's spelling of a contract fact — and a template
+                 * that router could not mount refused the whole operation, validators included.
+                 *
+                 * A server emitter converts this when it renders, and refuses what it cannot mount with
+                 * a diagnostic of its own. The validators for such an operation are still correct and
+                 * still emitted: what a request body must look like does not depend on whether some
+                 * particular router can express the path.
+                 */
+                path: operation.path,
+                statusCode,
+                statusCodes,
+                responseContentTypes: responseContentTypesOf(operation, statusCode),
+                requestContentTypes: [...(operation.parameters.body?.contentTypes ?? [])],
+                /**
+                 * `@summary` first, `@doc` as the fallback.
+                 *
+                 * OpenAPI distinguishes them — `summary` is the short line, `description` the verbose
+                 * explanation — and `@typespec/openapi3` maps them to exactly those. A spec whose operation
+                 * strings are one-liners means `summary`; written as `@doc` they land in `description`
+                 * instead and leave `summary` empty on every operation. The fallback keeps a spec that
+                 * uses `@doc` working.
+                 */
+                summary: getSummary(program, operation.operation) ?? getDoc(program, operation.operation),
+                /**
+                 * ⚠️ **Each position is walked at ITS OWN visibility, which is the whole point.** A model
+                 * used as a request body and as a response is two shapes: `@statusCode` is applicable to
+                 * one and not the other, and `@visibility` can add or remove properties outright. Walking
+                 * both at one visibility gives whichever was seen first to both.
+                 */
+                requestSchema: withVisibility(program, requestVisibility, () => {
+                    // Multipart first: its body has no single type to walk, and skipping it left every
+                    // such route mounted with nothing checking the request at all.
+                    const parameterBody = operation.parameters.body;
+                    if (parameterBody?.bodyKind === "multipart") {
+                        return multipartSchemaOf(parameterBody, registry);
+                    }
+                    return requestType === undefined ? undefined : registry.expressionFor(requestType);
+                }),
+                ...(() => {
+                    const split = withVisibility(program, requestVisibility, () => parameterSchemasOf(program, operation, registry));
+                    return {
+                        pathSchema: split.path,
+                        querySchema: split.query,
+                        headerSchema: split.header,
+                        negotiatedHeaderSchema: split.negotiatedHeader,
+                        accept: split.accept,
+                    };
+                })(),
+                responseSchema: responseType === undefined
+                    ? undefined
+                    : withVisibility(program, Visibility.Read, () => 
+                    /**
+                     * A raw binary body is `z.unknown()`, matching what a binary multipart part
+                     * already emits and what the document actually asserts — see
+                     * {@link isRawBinaryMediaType}.
+                     */
+                    isBinaryPart(responseType) &&
+                        isRawBinaryMediaType(responseContentTypesOf(operation, statusCode))
+                        ? "z.unknown()"
+                        : registry.expressionFor(responseType)),
+                rawBodyProperty,
+                // Responses are read at Visibility.Read, exactly as the success body above is. Resolving
+                // them under the ambient request visibility declared six components under the wrong
+                // suffix — measured: type/model/visibility gained six divergences.
+                errorArms: withVisibility(program, Visibility.Read, () => errorArmsOf(program, operation, registry)),
+                scopes: [
+                    ...new Set((getAuthenticationForOperation(program, operation.operation)?.options ?? []).flatMap((option) => option.schemes.flatMap((scheme) => scheme.type === "oauth2"
+                        ? scheme.flows.flatMap((flow) => flow.scopes.map((scope) => scope.value))
+                        : []))),
+                ],
+                noAuth: noAuthFor(program, operation),
+                statusBy: discriminator,
+                /**
+                 * ⚠️ **Each arm is validated against its OWN shape.**
+                 *
+                 * A consumer checks its value against the arm's schema, and with one schema
+                 * for two statuses the acknowledged response was checked against the resolved arm's
+                 * shape — a 502 on a perfectly good 202.
+                 */
+                alternateResponseSchema: discriminator === undefined
+                    ? undefined
+                    : alternateSchemaFor(operation, discriminator.status, registry),
+            });
+        }
+    }
+    return routes;
+}
+/**
+ * Emit only the external names a given file actually references.
+ *
+ * Both generated files can need them — `schemas.gen.ts` for the vocabulary tuples and `@refine`
+ * predicates, and `routes.gen.ts` when an inline params schema carries a refined scalar.
+ * Emitting the whole set into both would leave unused imports (which lint rejects); emitting it into
+ * neither is what left `routes.gen.ts` referencing `isParsableInstant` with no import at all.
+ */
+function renderExternalImports(externals, ...bodies) {
+    const haystack = bodies.join("\n");
+    const lines = [];
+    for (const [module, names] of externals) {
+        const used = [...names].filter((name) => new RegExp(`\\b${name}\\b`).test(haystack));
+        if (used.length > 0) {
+            lines.push(`import { ${used.toSorted().join(", ")} } from ${JSON.stringify(module)};\n`);
+        }
+    }
+    return lines.join("");
+}
+/**
+ * Every validator this service needs, in one module: the component schemas, and the per-operation
+ * request and response validators.
+ *
+ * ⚠️ **The per-operation half used to be emitted by the SERVER generator, into the server file.** So
+ * a package advertising *TypeSpec HTTP → Zod* produced component schemas and nothing a caller could
+ * validate a request or a response against, and every oracle that graded those validators had to read
+ * a server to find them. See {@link nameRouteSchemas}.
+ */
+function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
+    const declarations = registry
+        .declarations()
+        .map((d) => `\nexport const ${d.identifier} = ${d.source};\nexport type ${d.typeName} = z.infer<typeof ${d.identifier}>;\n`);
+    const parts = [GENERATED_BANNER, '\nimport { z } from "zod";\n'];
+    /**
+     * A TYPE import, so nothing of this package's survives into the emitted JavaScript.
+     *
+     * The annotation is what makes a misspelled or omitted `schema` a compile error rather than an arm
+     * that silently validates nothing — see the option's own docblock for the measurement. Emitted only
+     * when there are arms to annotate, because an unused import fails the lint a generated file has to
+     * pass like any other.
+     */
+    if (routeDeclarations.length > 0) {
+        parts.push(`import type { ResponseArm } from ${JSON.stringify(runtimeModule)};\n`);
+    }
+    parts.push(renderExternalImports(externals, [...declarations, ...routeDeclarations].join("")));
+    parts.push(declarations.join(""));
+    if (routeDeclarations.length > 0)
+        parts.push(`\n${routeDeclarations.join("\n")}\n`);
+    return parts.join("");
+}
+/**
+ * The IDENTIFIER a schema can be referred to by, which `z.infer<typeof …>` requires.
+ *
+ * A route's schema is often an expression rather than a declaration — `z.array(widgetSchema)`,
+ * `z.object({…})` for inline parameters — and `typeof z.array(widgetSchema)` is not valid
+ * TypeScript. Anything that is not already a bare identifier gets a name here; anything that is
+ * keeps it, so the generated file does not fill up with aliases that alias nothing.
+ */
+const isIdentifier = (expression) => /^[A-Za-z_$][\w$]*$/.test(expression);
+const schemaConst = (operationId, suffix) => `${operationId}${suffix}`;
+/** `[the name to refer to it by, the `const` line to emit]` — the line is absent when none is needed. */
+function namedSchema(operationId, suffix, expression) {
+    if (expression === undefined)
+        return { name: undefined, declaration: undefined };
+    if (isIdentifier(expression))
+        return { name: expression, declaration: undefined };
+    const name = schemaConst(operationId, suffix);
+    /**
+     * ⚠️ **Exported, because a schema nothing outside this file can name is a schema nothing can
+     * check.** These are the validators the server actually enforces on every request — the path,
+     * query and header shapes — and while they were module-local the only thing that could read them
+     * was the generated code itself. That is how a header validator keyed on the wrong name shipped:
+     * the conformance differential compares `components.schemas`, a parameter schema is not a
+     * component, and there was no third artefact to compare against even in principle.
+     *
+     * Exporting also gives an application the request shape by name, which is what the per-operation
+     * type aliases will be built from.
+     */
+    return { name, declaration: `export const ${name} = ${expression};` };
+}
+/**
+ * Which `verb path` slots carry more than one operation.
+ *
+ * ⚠️ **A DOCUMENT fact, not a router one, which is why it lives here.** TypeSpec models content
+ * negotiation as several operations on one route; OpenAPI models it as a single path item whose
+ * response lists every media type. A route reached that way must not validate `accept` against any
+ * one member's literal — `accept` SELECTS the operation, so validating it would answer `400` to a
+ * well-formed request whose real answer is `406`. That is why `negotiatedHeaderSchema` exists, and
+ * deciding which of the two applies is what this set is for.
+ */
+function sharedSlots(routes) {
+    const shared = new Set();
+    const seen = new Set();
+    for (const route of routes) {
+        const slot = `${route.verb} ${route.path}`;
+        if (seen.has(slot))
+            shared.add(slot);
+        seen.add(slot);
+    }
+    return shared;
+}
+/**
+ * Declare every per-operation validator, and hand back the names they were declared under.
+ *
+ * ⚠️ **These used to be declared by the SERVER emitter, into the server file.** Six identifiers per
+ * operation — the path, query and header validators, the request body, the success response and the
+ * response arms — were built and emitted inside `renderApp`, which had three consequences and none of
+ * them were intended:
+ *
+ * 1. a package whose entire claim is *TypeSpec HTTP → Zod* emitted **no** request or response
+ *    validator that a consumer could name. Component schemas, and nothing to check a call against;
+ * 2. every oracle that graded them had to read the SERVER file, so splitting this library out would
+ *    have taken the parameter, response and response-body arms with it and left component agreement
+ *    as the only thing still measured — three of the four largest arms, lost silently;
+ * 3. two emitters would have had to mint identical identifiers by coincidence, which is the coupling
+ *    that made a library-plus-emitter split look impossible in the first place.
+ *
+ * Declaring them here dissolves all three: the library mints the names AND emits them, and a server
+ * emitter imports what it is told rather than agreeing about it.
+ */
+function nameRouteSchemas(routes) {
+    const shared = sharedSlots(routes);
+    const declarations = [];
+    const names = new Map();
+    for (const route of routes) {
+        const declare = (suffix, expression) => {
+            const resolved = namedSchema(route.operationId, suffix, expression);
+            if (resolved.declaration !== undefined)
+                declarations.push(resolved.declaration);
+            return resolved.name;
+        };
+        // Order follows the request: what identifies the resource, then what filters it, then its body.
+        const path = declare("Path", route.pathSchema);
+        const query = declare("Query", route.querySchema);
+        const negotiating = shared.has(`${route.verb} ${route.path}`);
+        const header = declare("Header", negotiating ? route.negotiatedHeaderSchema : route.headerSchema);
+        // A raw body is read as text, never parsed, so it has no validator — the bytes are the contract.
+        const body = route.rawBodyProperty === undefined ? declare("Body", route.requestSchema) : undefined;
+        const response = declare("Response", route.responseSchema);
+        const alternateResponse = declare("AlternateResponse", route.alternateResponseSchema);
+        const responses = schemaConst(route.operationId, "Responses");
+        declarations.push(`export const ${responses} = ${responseArmsOf(route, response, alternateResponse)} satisfies readonly ResponseArm[];`);
+        names.set(route.operationId, {
+            operationId: route.operationId,
+            path,
+            query,
+            header,
+            body,
+            response,
+            alternateResponse,
+            responses,
+        });
+    }
+    return { names, declarations };
+}
+/**
+ * What an operation may answer with, as a literal — each declared status paired with the body the
+ * document gives it, in OpenAPI's own precedence order.
+ *
+ * ⚠️ **This docblock was orphaned in the source it came from**, sitting above an unrelated function
+ * while the one it describes had none. Reattached.
+ */
+function responseArmsOf(route, response, alternate) {
+    const arms = [];
+    const primary = response ?? "undefined";
+    if (route.statusBy === undefined) {
+        arms.push(`{ status: ${route.statusCode}, schema: ${primary} }`);
+    }
+    else {
+        const alternateSchema = alternate ?? "undefined";
+        const { property, value, status } = route.statusBy;
+        arms.push(`{ status: ${status}, schema: ${alternateSchema}, when: { property: ${JSON.stringify(property)}, value: ${JSON.stringify(value)} } }`, `{ status: ${route.statusCode}, schema: ${primary} }`);
+    }
+    /**
+     * The failure arms, which used to be dropped entirely.
+     *
+     * ⚠️ **The document declares what an error body looks like and the server never passed it on**, so
+     * `respond` could not check what it sends on failure even in principle.
+     *
+     * ⚠️ **This used to fall back to the service-wide error schema, and the fallback was the defect.**
+     * `arm.schema ?? errorSchema` was reached by every arm the emitter could not resolve a body for —
+     * which, while `"default"` was deliberately given none, meant every catch-all in every service
+     * answered with whichever shape `errorBodyOf` had settled on rather than the one its own response
+     * declares. Each arm resolves its own body now, so an arm with no schema is a response the document
+     * says carries no body, and saying `undefined` is the truthful answer rather than a guess.
+     */
+    for (const arm of route.errorArms) {
+        arms.push(`{ status: ${JSON.stringify(arm.status)}, schema: ${arm.schema ?? "undefined"} }`);
+    }
+    return `[${arms.join(", ")}]`;
+}
+const upperFirst = (value) => value.charAt(0).toUpperCase() + value.slice(1);
+/**
+ * The effective input of every operation, as TypeScript: its body, with the path, query and header
+ * parameters merged over it.
+ *
+ * ⚠️ **This used to drop any parameter literally named `companyId`.** One application carried its
+ * tenant identifier in a context object rather than in the payload, and the emitter was taught to
+ * match — so for every consumer, a path parameter with that name vanished from the generated input
+ * type while the Zod validator went on requiring it. Two artefacts describing different shapes, from
+ * a rule no document states.
+ *
+ * It is the same defect class this emitter exists to delete, and it hid better than most: the
+ * emitted assertions pair the validator against the contract types for MODELS, so a disagreement
+ * about a merged input type is not among the things they compare.
+ */
+function collectRequestTypes(program, registry, service) {
+    const entries = [];
+    {
+        for (const operation of service.operations) {
+            if (successStatusOf(operation) === undefined)
+                continue;
+            const body = requestBodyOf(operation);
+            /**
+             * Headers are part of the input too.
+             *
+             * The webhook's three Standard-Webhooks headers are inside the MAC — they are not metadata
+             * beside the payload, they are arguments to the verification. Leaving them out of the wire
+             * type would describe an input the application cannot act on.
+             */
+            const extraProperties = operation.parameters.parameters
+                .filter((parameter) => parameter.type === "path" || parameter.type === "query" || parameter.type === "header")
+                .map((parameter) => registry.expressionForProperty(parameter.param));
+            if (body === undefined && extraProperties.length === 0)
+                continue;
+            /**
+             * A `bytes` body reaches the use-case as a NAMED property holding the unparsed text, not as
+             * a bare string — so the wire type is `{ rawBody: string }`, matching what a server
+             * actually builds. Referencing the scalar directly would type the whole input as `string`
+             * and quietly drop the headers beside it.
+             */
+            const rawBody = body?.kind === "Scalar" && body.name === "bytes"
+                ? (operation.parameters.body?.property?.name ?? "body")
+                : undefined;
+            entries.push({
+                operationId: resolveOperationId(program, operation.operation),
+                bodyRef: rawBody !== undefined
+                    ? `{\n\t${rawBody}: string;\n}`
+                    : body === undefined
+                        ? undefined
+                        : registry.expressionFor(body),
+                extraProperties,
+            });
+        }
+    }
+    return entries;
+}
+/**
+ * The success response every operation declares, so a producer can be held to producing it.
+ *
+ * ⚠️ **Pinned fields only — these are PERMISSIVE shapes.** The gateway names the fields it depends on
+ * and lets a richer view through untouched, so this is a floor and not an equality: the
+ * domain's result must CONTAIN what the document promises, and may contain more. Asserting equality
+ * would turn every field a producer legitimately adds into a build failure, which is the same mistake
+ * as making a response schema strict.
+ */
+function collectResponseTypes(program, registry, service) {
+    const entries = [];
+    {
+        for (const operation of service.operations) {
+            const status = successStatusOf(operation);
+            if (status === undefined)
+                continue;
+            const body = successBodyOf(operation, status);
+            if (body === undefined)
+                continue;
+            entries.push({
+                operationId: resolveOperationId(program, operation.operation),
+                ref: registry.expressionFor(body),
+            });
+        }
+    }
+    return entries;
+}
+/**
+ * `requests.gen.ts` — the shape both sides are checked against.
+ *
+ * Plain TypeScript with no imports at all, so the contract types stay framework-free and a layering
+ * rule banning a validation library from the rest of the codebase is untouched. `wire-contract.gen.ts`
+ * asserts the emitted Zod infers exactly this; a consumer asserts its own code produces it. Neither
+ * imports the other, and a disagreement that would otherwise answer 400 on every request becomes a
+ * typecheck failure.
+ */
+function renderRequestTypes(entries, responses, registry) {
+    const declarations = registry.declarations().map((declaration) => {
+        // A vocabulary alias stays module-local: the vocabularies artefact already exports these names
+        // as runtime tuples, and exporting both collides on every one.
+        if (declaration.isVocabulary)
+            return `\ntype ${declaration.name} = ${declaration.source};\n`;
+        return declaration.isObject
+            ? `\nexport interface ${declaration.name} ${declaration.source}\n`
+            : `\nexport type ${declaration.name} = ${declaration.source};\n`;
+    });
+    const inputs = entries.map((entry) => {
+        const parts = [];
+        if (entry.bodyRef !== undefined)
+            parts.push(entry.bodyRef);
+        if (entry.extraProperties.length > 0) {
+            parts.push(`{\n${entry.extraProperties.map((line) => `\t${line}`).join("\n")}\n}`);
+        }
+        return (`\n/** The effective input for \`${entry.operationId}\` — its body, with path and query parameters merged over it. */\n` +
+            `export type ${upperFirst(entry.operationId)}Input = Simplify<${parts.join(" & ")}>;\n`);
+    });
+    /**
+     * The same set again, keyed by operation id.
+     *
+     * TypeScript cannot index a module's *type* exports by a computed name — `typeof Contracts` carries
+     * only the value side, so `Contracts["AppointOfficerInput"]` does not resolve. Both sides'
+     * assertions are written as mapped types over every operation, and this is what makes that
+     * possible. Generated with the aliases above, so it cannot fall behind them.
+     */
+    const responseLookup = responses
+        .map((entry) => `\t${entry.operationId}: Produced<${entry.ref}>;`)
+        .join("\n");
+    const lookup = entries
+        .map((entry) => `\t${entry.operationId}: ${upperFirst(entry.operationId)}Input;`)
+        .join("\n");
+    return `${GENERATED_BANNER}
+/**
+ * Flattens an intersection into a single object type.
+ *
+ * Without it, \`Body & { filingId: string }\` and the equivalent flat object are structurally the
+ * same but are NOT equal under the \`Equals<>\` conditional-type trick — so the assertions that pair
+ * this file with the emitted Zod would fail on correct code.
+ */
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+
+/**
+ * The same shape, tolerant of \`readonly\`.
+ *
+ * A producer's result is asserted assignable to its published shape, and a codebase commonly declares
+ * views with \`readonly\` properties and \`readonly T[]\` arrays — neither of which is assignable to a
+ * mutable one. Mutability is not a fact about a wire shape: it says nothing about what a caller
+ * receives. Making the TARGET readonly accepts both, which is the permissive direction; the reverse
+ * would reject every view a producer actually returns.
+ */
+type Produced<T> = T extends readonly (infer Element)[]
+	? readonly Produced<Element>[]
+	: T extends object
+		? { readonly [K in keyof T]: Produced<T[K]> }
+		: T;
+${declarations.join("")}${inputs.join("")}
+/** Every operation's effective input, keyed by operation id — what both sides assert against. */
+export interface WireInputs {
+${lookup}
+}
+
+/**
+ * Every operation's success response, keyed by operation id.
+ *
+ * ⚠️ **A floor, not an equality.** These shapes are permissive: a caller pins the fields it depends
+ * on and lets a richer view through, so a producer's result must CONTAIN what the document promises
+ * and may contain more. This is what makes a published response checkable at all — measured once, a
+ * route advertised a field it had never returned, and nothing anywhere could see it.
+ */
+export interface WireOutputs {
+${responseLookup}
+}
+`;
+}
+/**
+ * The validator's half of the wire contract: the emitted Zod must infer **exactly** the shared type.
+ *
+ * Two artefacts describe one contract — the runtime validator and the framework-free type a codebase
+ * passes around — and a shared declaration compared against only one of them lets the other drift
+ * into it unnoticed. This asserts the validator *produces* the shared shape; a consumer that also
+ * asserts its own code *accepts* that shape has both directions pinned.
+ *
+ * ⚠️ This is also the only thing that catches the emitter disagreeing with **itself**. `zod.ts` and
+ * `types.ts` walk the same TypeSpec twice, once to Zod and once to TypeScript, and a construct one
+ * handles differently from the other produces two artefacts that describe different shapes while
+ * both look right in isolation. That happened during this emitter's first run: a vocabulary in a
+ * query-parameter position was inlined by one walk and referenced by the other.
+ *
+ * `Equals` here, not assignability — `z.infer` is the output type, and the wire type is emitted with
+ * defaulted properties required for exactly that reason, so the two really are equal.
+ */
+function renderWireAssertions(schemas, types, entries, contractsPackage) {
+    // The assertions pair the emitted Zod against the request TYPES, which live in the contracts
+    // package. With no package named there is nothing to import them from and nothing to pair — the
+    // types are still written to `contracts-output-dir`, they simply have no shared specifier yet.
+    if (contractsPackage === undefined)
+        return undefined;
+    const requestModels = new Set(entries.map((entry) => entry.bodyRef).filter((ref) => ref !== undefined));
+    const paired = [];
+    for (const declaration of types.declarations()) {
+        if (!requestModels.has(declaration.name))
+            continue;
+        const schema = schemas
+            .declarations()
+            .find((candidate) => candidate.typeName === declaration.name);
+        if (schema === undefined)
+            continue;
+        paired.push({ name: declaration.name, identifier: schema.identifier });
+    }
+    if (paired.length === 0)
+        return undefined;
+    const assertions = paired.map((pair) => `export type Assert${pair.name} = MustHold<Identical<z.infer<typeof ${pair.identifier}>, Contracts.${pair.name}>>;`);
+    return `${GENERATED_BANNER}
+import type { z } from "zod";
+import type * as Contracts from "${contractsPackage}";
+import type {
+${paired.map((pair) => `\t${pair.identifier},`).join("\n")}
+} from "./schemas.gen.js";
+
+/**
+ * Exact structural equality. The naive \`A extends B ? B extends A\` form reports two object types
+ * equal when one has an optional property the other lacks, which is the whole class of drift this
+ * exists to catch; the identity-function comparison does not.
+ */
+type Identical<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+	? true
+	: ["the emitted validator and the shared wire type describe different shapes"];
+
+/**
+ * \u26a0\ufe0f **The constraint is what fails the build.** \`Identical<A, B> & true\` merely produces an odd
+ * type when the two disagree, and a type alias to an odd type compiles fine \u2014 66 assertions that
+ * assert nothing. Only a constraint violation is an error.
+ */
+type MustHold<T extends true> = T;
+
+${assertions.join("\n")}
+`;
+}
+/**
+ * `vocabularies.gen.ts` — every vocabulary the surface reaches, as runtime tuples.
+ *
+ * Keyed by enum name rather than emitted as individually-named tuples, because the constant names a
+ * consumer wants are English plurals and some of them are irregular. An emitter that pluralises is an
+ * emitter that will one day invent `CAPACITYS` and silently create a second constant beside the real
+ * one. So the emitter states the fact and the consumer owns the naming.
+ */
+function renderVocabularies(vocabularies) {
+    const entries = [...vocabularies.entries()]
+        .toSorted(([a], [b]) => a.localeCompare(b))
+        .map(([name, values]) => `\t${name}: [${values.map((v) => JSON.stringify(v)).join(", ")}],`);
+    return `${GENERATED_BANNER}
+/**
+ * The spec's vocabularies — every enum the surface reaches, and what each one contains.
+ *
+ * \`as const\` so each is a readonly tuple of literals — the type every consumer derives with
+ * \`(typeof X)[number]\` keeps working unchanged.
+ */
+export const SPEC_VOCABULARIES = {
+${entries.join("\n")}
+} as const;
+`;
+}
+/** What the generated files import their runtime contract from when nothing says otherwise. */
+export const DEFAULT_RUNTIME_MODULE = "typespec-http-zod/runtime";
+/**
+ * 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 async function emitHttpZod(context, wrapper = {}) {
+    const options = context.options;
+    const defaultRuntimeModule = wrapper.defaultRuntimeModule ?? DEFAULT_RUNTIME_MODULE;
+    /**
+     * Each service already projected to the version it currently serves — see `versioning.ts`.
+     *
+     * ⚠️ **This used to be a bare `getAllHttpServices`, which is the UNION of every version.** A spec
+     * that removes an operation in v2 had it mounted anyway, and a spec that removed a property had it
+     * still required. Both while the document said otherwise.
+     */
+    const versioning = await resolveVersioningModule();
+    const snapshots = serviceSnapshots(context.program, versioning);
+    /**
+     * Resolved once, here, because the walk below is synchronous and this is not. `undefined` when the
+     * optional stream libraries are not installed, which is the normal case — see `streams.ts`.
+     */
+    const streamModule = await resolveStreamModule();
+    const emitted = [];
+    /**
+     * ⚠️ **One emission per `@service`, with its own registry and its own import collector.**
+     *
+     * Sharing either across services merges one surface's schemas and imports into the other's file —
+     * an unused import if you are lucky and a missing one if you are not, and a public document
+     * carrying internal models if you are not paying attention. It is invisible while there is one
+     * service, which is exactly why it is built this way before the second one lands rather than after.
+     */
+    for (const snapshot of snapshots) {
+        const service = snapshot.service;
+        const serviceName = service.namespace.name;
+        const perService = options.services?.[serviceName];
+        const outputDir = perService?.["output-dir"] ?? context.emitterOutputDir;
+        const resolved = {
+            contractsOutputDir: perService?.["contracts-output-dir"] ?? options["contracts-output-dir"],
+            contractsPackage: perService?.["contracts-package"] ?? options["contracts-package"],
+            sealObjectSchemas: perService?.["seal-object-schemas"] ?? options["seal-object-schemas"] ?? false,
+            keyVocabularies: perService?.["key-vocabularies"] ?? options["key-vocabularies"] ?? [],
+            runtimeModule: perService?.["runtime-module"] ?? options["runtime-module"] ?? defaultRuntimeModule,
+        };
+        const registry = new SchemaRegistry(context.program);
+        const { result: { routes }, imports: externals, vocabularies, } = collectExternalImports(() => withContractsPackage(resolved.contractsPackage, () => withSealedObjects(resolved.sealObjectSchemas, () => {
+            // Declarations first: a vocabulary is a fact about the contract, so it is collected from
+            // what the service DECLARES rather than from what the Zod walk happens to touch. An enum
+            // reachable only through an error body was silently absent otherwise.
+            noteDeclaredVocabularies(service.namespace.enums.values());
+            /**
+             * A closed key SET is a vocabulary too, and it cannot be an enum.
+             *
+             * TypeSpec has no key-constrained `Record`, so a model naming its permitted properties is
+             * how the document states one — and a generated type cannot be iterated, which leaves a
+             * consumer needing the set at run time with a hand-maintained copy. Naming the model in
+             * `key-vocabularies` writes the keys beside the types. A name matching nothing is
+             * reported rather than quietly emitting no tuple.
+             */
+            const emittedKeyVocabularies = noteKeyVocabularies(context.program, service.namespace.models.values(), resolved.keyVocabularies);
+            for (const name of resolved.keyVocabularies) {
+                if (emittedKeyVocabularies.includes(name))
+                    continue;
+                reportDiagnostic(context.program, {
+                    code: "unknown-key-vocabulary",
+                    target: service.namespace,
+                    format: { name, service: service.namespace.name },
+                });
+            }
+            /**
+             * The error body is registered INSIDE this walk, so its validator lands in
+             * `schemas.gen.ts` alongside every other declaration. Nothing else reaches it: the Zod
+             * walk follows success bodies and parameters, so without this a runtime would have no
+             * generated schema to check the documents it sends against.
+             *
+             * ⚠️ **Its expression is registered and then deliberately discarded.** It used to be
+             * returned and used as a fallback for any response arm whose own body could not be
+             * resolved, which meant every catch-all answered with whichever shape `errorBodyOf` had
+             * settled on rather than the one its own response declares. Each arm resolves its own
+             * body now; registering this one only ensures it is declared.
+             */
+            const errorBody = errorBodyOf(context.program, service);
+            if (errorBody !== undefined) {
+                withVisibility(context.program, Visibility.Read, () => registry.expressionFor(errorBody));
+            }
+            return {
+                routes: withStreamModule(streamModule, () => collectRoutes(context.program, registry, service)),
+            };
+        })));
+        /**
+         * ⚠️ **Named AFTER the walk and BEFORE the file is rendered.** Naming mints identifiers that
+         * `schemas.gen.ts` must declare, so it has to happen while the registry is complete and before
+         * anything is written — and it has to happen HERE rather than in a server emitter, or the
+         * validators it produces never reach this package's own output.
+         */
+        const { names, declarations } = nameRouteSchemas(routes);
+        await emitFile(context.program, {
+            path: resolvePath(outputDir, "schemas.gen.ts"),
+            content: renderSchemas(registry, externals, declarations, resolved.runtimeModule),
+        });
+        if (resolved.contractsOutputDir !== undefined) {
+            const types = new TypeRegistry(context.program);
+            const entries = collectRequestTypes(context.program, types, service);
+            const responses = collectResponseTypes(context.program, types, service);
+            await emitFile(context.program, {
+                path: resolvePath(resolved.contractsOutputDir, "requests.gen.ts"),
+                content: renderRequestTypes(entries, responses, types),
+            });
+            await emitFile(context.program, {
+                path: resolvePath(resolved.contractsOutputDir, "vocabularies.gen.ts"),
+                content: renderVocabularies(vocabularies),
+            });
+            const assertions = renderWireAssertions(registry, types, entries, resolved.contractsPackage);
+            if (assertions !== undefined) {
+                await emitFile(context.program, {
+                    path: resolvePath(outputDir, "wire-contract.gen.ts"),
+                    content: assertions,
+                });
+            }
+        }
+        emitted.push({ service, routes, schemaNames: names, outputDir, options: resolved });
+    }
+    return emitted;
+}