typespec-http-zod 0.1.0 → 0.3.0

package/dist/src/api.js

@@ -7,13 +7,13 @@ import { resolveStreamModule, streamedTypeOf, withStreamModule } from "./streams
 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
+ * `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
+ * 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.
@@ -22,9 +22,9 @@ import { collectExternalImports, noteDeclaredVocabularies, noteKeyVocabularies,
  * 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.
+ * them - `typespec-hono` is one.
  *
- * **Built on the stable 1.x surface only** — `$onEmit` plus `@typespec/http` — rather than on
+ * **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.
  */
@@ -33,15 +33,15 @@ 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
+ * **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.
+ * 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
+ * **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
@@ -53,7 +53,7 @@ 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
+ * **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.
  *
@@ -67,7 +67,7 @@ const GENERATED_BANNER = `// GENERATED by ${PACKAGE_NAME} from the TypeSpec serv
  * 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
+ * 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) {
@@ -93,19 +93,19 @@ export function successStatusesOf(operation) {
 /** 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.**
+ * What the document will key this response under - **openapi3's rule, copied, not re-derived.**
  *
- * ⚠️ **`HttpStatusCodesEntry` is `HttpStatusCodeRange | number | "*"`, and the third case was
+ * **`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`
+ * 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
+ * **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.
+ * `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.
  *
@@ -158,24 +158,24 @@ function isSuccessKey(status) {
 /**
  * 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
+ * **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
+ * **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
+ * 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
+ * **`"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 —
+ * 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) {
@@ -194,11 +194,11 @@ function errorArmsOf(program, operation, registry) {
 /**
  * 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
+ * **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
+ * 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) {
@@ -206,7 +206,7 @@ function statusPrecedenceOf(status) {
         return 2;
     return typeof status === "number" ? 0 : 1;
 }
-/** A response's own body, as an emitted Zod expression — `undefined` where it declares none. */
+/** 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")
@@ -218,11 +218,11 @@ function bodySchemaOf(response, registry) {
     return undefined;
 }
 /**
- * Whether the operation declares `@useAuth(NoAuth)` — no caller is established for it.
+ * 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.**
+ * **`@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
+ * - 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) {
@@ -231,13 +231,13 @@ function noAuthFor(program, operation) {
 /**
  * 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
+ * **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
+ * **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
@@ -245,7 +245,7 @@ function noAuthFor(program, operation) {
  *
  * 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
+ * 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) {
@@ -254,13 +254,13 @@ export function errorBodyOf(program, service) {
     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.
+             * `@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
+             * 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
+             * entirely - measured on a surface declaring an error on all
              * eleven operations and this found none of them.
              */
             if (!isErrorModel(program, response.type))
@@ -270,15 +270,15 @@ export function errorBodyOf(program, service) {
                 if (body?.bodyKind !== "single")
                     continue;
                 /**
-                 * ⚠️ **An error response can declare no body either.** `tsp-openapi3` renders a bare
+                 * **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
+                 * 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
+                // `"*"` 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);
             }
@@ -286,7 +286,7 @@ export function errorBodyOf(program, service) {
     }
     /**
      * 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
+     * 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)
@@ -295,7 +295,7 @@ export function errorBodyOf(program, service) {
     if (body !== undefined)
         return body;
     /**
-     * A service can decline to declare a catch-all and still have one error shape — ten specific
+     * 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.
@@ -305,10 +305,10 @@ export function errorBodyOf(program, service) {
 /**
  * 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
+ * **`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
+ * 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'`.
  */
@@ -318,16 +318,16 @@ function bodyTypeOf(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
+ * **`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`,
+ * 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
+ * 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) {
@@ -345,10 +345,10 @@ function successBodyOf(operation, status) {
 /**
  * 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
+ * **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
+ * 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.
@@ -365,17 +365,17 @@ function responseContentTypesOf(operation, status) {
     }
     return [...types];
 }
-/** Whether a type is an array — TypeSpec models one as a `Model` carrying an integer indexer. */
+/** 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
+ * **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.
+ * 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.
@@ -406,17 +406,17 @@ function alternateSchemaFor(operation, status, registry) {
 /**
  * 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
+ * **`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
+ * `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
+ * **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
+ * 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.
  */
@@ -424,7 +424,7 @@ 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.
+        // `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},`;
     });
@@ -432,13 +432,13 @@ function multipartSchemaOf(body, registry) {
     /**
      * 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.
+     * 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. */
+/** `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) {
@@ -458,18 +458,18 @@ function isBinaryPart(type) {
 /**
  * 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`
+ * **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
+ * 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
+ * **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`.
+ * counted and never compared - three positions in `encode/bytes`.
  */
 export function isRawBinaryMediaType(contentTypes) {
     if (contentTypes.length === 0)
@@ -483,13 +483,13 @@ function requestBodyOf(operation) {
 }
 /**
  * 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,
+ * 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
+ * **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`.
@@ -497,14 +497,14 @@ function requestBodyOf(operation) {
 /**
  * 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
+ * **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
+ * 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
+ * `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 = {
@@ -540,8 +540,8 @@ function collectionDelimiterOf(program, parameter) {
 /**
  * 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()`
+ * **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`:
  *
@@ -552,17 +552,17 @@ function collectionDelimiterOf(program, parameter) {
  * 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
+ * **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
+ * **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 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
@@ -577,7 +577,7 @@ function wireDecoded(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
+     * 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.
@@ -593,9 +593,9 @@ function wireDecoded(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
+ * **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
+ * `multipart/form-data; boundary=...` - and RFC 2046 section 5.1.1 makes that boundary MANDATORY, so the
  * validator rejected **every syntactically valid multipart request**. Measured under `wrangler dev`:
  *
  * ```
@@ -607,24 +607,24 @@ function wireDecoded(declared) {
  * `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
+ * **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
+ * 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
+ * Lowercased because RFC 9110 section 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
+     * **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
+     * `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.
      */
@@ -647,15 +647,15 @@ function parameterSchemasOf(program, operation, registry) {
             continue;
         }
         /**
-         * ⚠️ **`parameter.name` is the WIRE name; `parameter.param.name` is the TypeSpec one.** Headers
+         * **`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
+         * 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.
+         * 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);
@@ -663,7 +663,7 @@ function parameterSchemasOf(program, operation, registry) {
         /**
          * 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
+         * document publishes, so every constraint on the list - `minItems`, the element type - still
          * runs. Splitting in the handler instead would have left those unenforced.
          */
         /**
@@ -681,7 +681,7 @@ function parameterSchemasOf(program, operation, registry) {
         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
+         * **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
@@ -716,15 +716,15 @@ export function collectRoutes(program, registry, service) {
             const statusCode = successStatusOf(operation);
             if (statusCode === undefined)
                 continue;
-            // No body is a legitimate success — see `EmittedRoute.responseSchema`. Skipping here is what
+            // 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.**
+             * **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
+             * `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
@@ -734,7 +734,7 @@ export function collectRoutes(program, registry, service) {
             if (streamed !== undefined) {
                 withVisibility(program, Visibility.Read, () => registry.expressionFor(streamed));
             }
-            // `@requestVisibility` when the operation states one, otherwise the verb's default — the
+            // `@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);
@@ -753,11 +753,11 @@ export function collectRoutes(program, registry, service) {
                 operationId: resolveOperationId(program, operation.operation),
                 verb: operation.verb.toUpperCase(),
                 /**
-                 * The path TEMPLATE, exactly as the document publishes it — `/widgets/{widget-id}`.
+                 * 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
+                 * **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
+                 * 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
@@ -773,15 +773,15 @@ export function collectRoutes(program, registry, service) {
                 /**
                  * `@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
+                 * 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
+                 * **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.
@@ -810,7 +810,7 @@ export function collectRoutes(program, registry, service) {
                     : 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
+                     * already emits and what the document actually asserts - see
                      * {@link isRawBinaryMediaType}.
                      */
                     isBinaryPart(responseType) &&
@@ -820,7 +820,7 @@ export function collectRoutes(program, registry, service) {
                 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.
+                // 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"
@@ -830,11 +830,11 @@ export function collectRoutes(program, registry, service) {
                 noAuth: noAuthFor(program, operation),
                 statusBy: discriminator,
                 /**
-                 * ⚠️ **Each arm is validated against its OWN shape.**
+                 * **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.
+                 * shape - a 502 on a perfectly good 202.
                  */
                 alternateResponseSchema: discriminator === undefined
                     ? undefined
@@ -847,7 +847,7 @@ export function collectRoutes(program, registry, service) {
 /**
  * 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`
+ * 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.
@@ -867,21 +867,36 @@ function renderExternalImports(externals, ...bodies) {
  * 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
+ * **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 declarations = registry.declarations().map((d) => {
+        /**
+         * **A declaration on a CYCLE cannot take its type from `z.infer`, because that is the loop.**
+         * The ordinary form - `const x = ...; type X = z.infer<typeof x>` - is circular the moment `x`'s
+         * own initialiser depends on `X`, and TypeScript says so: `TS2456`, `TS2502`, `TS7022`. So a
+         * cyclic declaration carries the type written out, and the deferred one is annotated with it,
+         * which is the recipe Zod documents for exactly this. Everything else is unchanged, so a spec
+         * with no cycle emits byte-identical output to before.
+         */
+        if (d.structural === undefined) {
+            return `\nexport const ${d.identifier} = ${d.source};\nexport type ${d.typeName} = z.infer<typeof ${d.identifier}>;\n`;
+        }
+        const declared = d.structural.startsWith("{")
+            ? `export interface ${d.typeName} ${d.structural}`
+            : `export type ${d.typeName} = ${d.structural};`;
+        const annotation = d.annotated === true ? `: z.ZodType<${d.typeName}>` : "";
+        return `\n${declared}\nexport const ${d.identifier}${annotation} = ${d.source};\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
+     * 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.
      */
@@ -895,16 +910,16 @@ function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
     return parts.join("");
 }
 /**
- * The IDENTIFIER a schema can be referred to by, which `z.infer<typeof …>` requires.
+ * 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
+ * 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. */
+/** `[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 };
@@ -912,9 +927,9 @@ function namedSchema(operationId, suffix, 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
+     * **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.
@@ -927,10 +942,10 @@ function namedSchema(operationId, suffix, 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
+ * **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
+ * 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.
  */
@@ -948,16 +963,16 @@ function sharedSlots(routes) {
 /**
  * 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
+ * **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
+ * 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;
+ *    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.
  *
@@ -980,7 +995,7 @@ function nameRouteSchemas(routes) {
         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.
+        // 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);
@@ -1000,10 +1015,10 @@ function nameRouteSchemas(routes) {
     return { names, declarations };
 }
 /**
- * What an operation may answer with, as a literal — each declared status paired with the body the
+ * 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
+ * **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) {
@@ -1020,11 +1035,11 @@ function responseArmsOf(route, response, alternate) {
     /**
      * 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
+     * **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 —
+     * **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
@@ -1040,9 +1055,9 @@ 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
+ * **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
+ * 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.
  *
@@ -1060,28 +1075,48 @@ function collectRequestTypes(program, registry, service) {
             /**
              * Headers are part of the input too.
              *
-             * The webhook's three Standard-Webhooks headers are inside the MAC — they are not metadata
+             * 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));
+                /**
+                 * Named as the WIRE names it, which is what the emitted validator keys on.
+                 * `@header("x-thing") thing: string` is `"x-thing"` in `schemas.gen.ts`, so it has to be
+                 * `"x-thing"` here too: a consumer checking its handlers against these types otherwise
+                 * fails to typecheck against a server that is correct.
+                 */
+                .map((parameter) => registry.expressionForProperty(parameter.param, parameter.name));
             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.
+             * A `bytes` body reaches the use-case as a NAMED property holding the unparsed body, not as
+             * a bare value, so the wire type is `{ rawBody: ... }`, matching what a server actually
+             * builds. Referencing the scalar directly would type the whole input as that value and
+             * quietly drop the headers beside it.
              */
             const rawBody = body?.kind === "Scalar" && body.name === "bytes"
                 ? (operation.parameters.body?.property?.name ?? "body")
                 : undefined;
+            /**
+             * **Raw binary is `ArrayBuffer`; base64 inside a JSON payload is `string`.** The same
+             * `isRawBinaryMediaType` rule the response side and the multipart parts already follow,
+             * applied here for the first time.
+             *
+             * This type said `string` for every `bytes` body whatever it was served as. A server reading
+             * an `application/octet-stream` body hands the handler bytes, so a consumer checking its
+             * handlers against these types could not typecheck against a correct server. It is the
+             * request half of the corruption already fixed on the reader: decoding raw bytes as text
+             * replaces every byte outside ASCII, and typing them as text is what invites it.
+             */
+            const rawBodyType = isRawBinaryMediaType([...(operation.parameters.body?.contentTypes ?? [])])
+                ? "ArrayBuffer"
+                : "string";
             entries.push({
                 operationId: resolveOperationId(program, operation.operation),
                 bodyRef: rawBody !== undefined
-                    ? `{\n\t${rawBody}: string;\n}`
+                    ? `{\n\t${rawBody}: ${rawBodyType};\n}`
                     : body === undefined
                         ? undefined
                         : registry.expressionFor(body),
@@ -1094,7 +1129,7 @@ function collectRequestTypes(program, registry, service) {
 /**
  * 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
+ * **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
@@ -1119,7 +1154,7 @@ function collectResponseTypes(program, registry, service) {
     return entries;
 }
 /**
- * `requests.gen.ts` — the shape both sides are checked against.
+ * `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`
@@ -1144,13 +1179,13 @@ function renderRequestTypes(entries, responses, registry) {
         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` +
+        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
+     * 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.
@@ -1166,7 +1201,7 @@ function renderRequestTypes(entries, responses, registry) {
  * 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
+ * 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] } & {};
@@ -1175,7 +1210,7 @@ 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
+ * 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.
@@ -1186,7 +1221,7 @@ type Produced<T> = T extends readonly (infer Element)[]
 		? { 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. */
+/** Every operation's effective input, keyed by operation id - what both sides assert against. */
 export interface WireInputs {
 ${lookup}
 }
@@ -1194,9 +1229,9 @@ ${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
+ * **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
+ * 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 {
@@ -1207,23 +1242,23 @@ ${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
+ * 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
+ * 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
+ * `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
+    // 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;
@@ -1269,7 +1304,7 @@ ${assertions.join("\n")}
 `;
 }
 /**
- * `vocabularies.gen.ts` — every vocabulary the surface reaches, as runtime tuples.
+ * `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
@@ -1282,9 +1317,9 @@ function renderVocabularies(vocabularies) {
         .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.
+ * 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
+ * \`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 = {
@@ -1297,7 +1332,7 @@ 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
+ * **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
@@ -1309,9 +1344,9 @@ 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`.
+     * 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
+     * **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.
      */
@@ -1319,14 +1354,14 @@ export async function emitHttpZod(context, wrapper = {}) {
     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`.
+     * 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.**
+     * **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 —
+     * 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.
@@ -1353,7 +1388,7 @@ export async function emitHttpZod(context, wrapper = {}) {
              * 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
+             * 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.
@@ -1374,7 +1409,7 @@ export async function emitHttpZod(context, wrapper = {}) {
              * 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
+             * **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
@@ -1389,9 +1424,9 @@ export async function emitHttpZod(context, wrapper = {}) {
             };
         })));
         /**
-         * ⚠️ **Named AFTER the walk and BEFORE the file is rendered.** Naming mints identifiers that
+         * **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
+         * 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);