typespec-http-zod 0.26.0 → 0.28.0

package/dist/src/api.js

@@ -1,13 +1,16 @@
-import { emitFile, getDoc, getDocData, getEncode, getLocationContext, getSummary, isErrorModel, isNeverType, isVoidType, navigateProgram, NoTarget, resolveEncodedName, resolvePath, } from "@typespec/compiler";
+import { emitFile, getDoc, getDocData, getEncode, getLocationContext, getSummary, isErrorModel, isNeverType, isVoidType, navigateProgram, NoTarget, resolveEncodedName, resolvePath, walkPropertiesInherited, } from "@typespec/compiler";
 import { getAuthenticationForOperation, resolveRequestVisibility, Visibility, } from "@typespec/http";
 import { getOperationId, resolveOperationId } from "@typespec/openapi";
 import { reportDiagnostic } from "./lib.js";
 import { SchemaRegistry, TypeRegistry } from "./registry.js";
-import { typeToTs } from "./types.js";
+import { isJsonMediaType, isMediaRange, isTextualMediaType, mediaTypeEssenceOf, mediaTypeTypeOf, resultMembersOf, statusCodesOf, } from "./results.js";
+import { propertyTypeToTs } from "./types.js";
 import { resolveStreamModule, streamedTypeOf, withStreamModule } from "./streams.js";
 import { resolveVersioningModule, serviceSnapshots } from "./versioning.js";
 import { EXPLODED_QUERY_SOURCE, explodedQueryCall, needsExpansionDecoding, routeTemplateOf, URI_EXPANSION_SOURCE, uriExpansionCall, } from "./uri-template.js";
-import { collectExternalImports, noteDeclaredVocabularies, noteKeyVocabularies, objectKey, wireKindOf, withContractsPackage, withSealedObjects, withVisibility, } from "./zod.js";
+export { CONTENTLESS_STATUS_CODES, STATUS_CODES } from "./statuses.js";
+export { isJsonMediaType, isMediaRange, isTextualMediaType, mediaTypeEssenceOf, mediaTypeTypeOf, resultMembersOf, statusCodesOf, } from "./results.js";
+import { collectExternalImports, isPayloadProperty, noteDeclaredVocabularies, noteKeyVocabularies, objectKey, wireKindOf, 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.
@@ -154,10 +157,10 @@ let operationIds;
 /**
  * Establish a fresh id resolver for one service's emission.
  *
- * **Scoped per SERVICE rather than per walk, because the walks see different subsets.**
- * `collectRoutes` visits every operation with a success status; `collectRequestTypes` skips any with
- * no body and no parameters. Deduplicating independently would let the two assign a suffix to
- * different operations, and the artefacts would name one operation two ways.
+ * **Scoped per SERVICE rather than per walk, because every walk has to name an operation the same
+ * way.** `collectRoutes` and `collectRequestTypes` both visit every operation, but each is a separate
+ * walk; deduplicating independently would let a suffix depend on the order a walk happened to meet
+ * two operations in, and the artefacts would name one operation two ways.
  *
  * A reset rather than a wrapper, because the emission loop is `for (const snapshot of snapshots)`
  * and awaits each service to completion before the next begins. Nothing interleaves, so there is no
@@ -275,7 +278,7 @@ function statusKeysOf(program, response) {
     return keys;
 }
 /**
- * Every response the operation declares, one per status key, in OpenAPI's precedence order.
+ * Every response the operation declares, one per status key, in the order they were RESOLVED.
  *
  * **Each response's own body, headers and media types, and nothing borrowed from another.** The
  * failure arms used to be collected here separately from the success, and before that every failure
@@ -288,10 +291,23 @@ function statusKeysOf(program, response) {
  * Where two responses resolve to the same status the first body wins, which is what the document
  * does, and media types and headers are the union across them.
  *
- * Call inside `withVisibility(program, Visibility.Read, ...)`: a response is read at `Read`, and
- * resolving it under a request visibility declares components under the wrong suffix.
+ * Resolution order, not precedence order, because a renderer that declares components has to
+ * declare them in the order they were always declared; {@link inPrecedenceOrder} sorts.
+ *
+ * **Resolved once per operation, and every walk reads that record.** Resolving reports what the
+ * document cannot publish, such as a status range OpenAPI cannot key; the route walk and the contract
+ * walk each resolved the same operation, so with contracts emitted every such error was raised twice.
  */
-function responsesOf(program, operation, registry) {
+function resolvedResponsesOf(program, operation) {
+    const resolved = resolvedResponses.get(operation);
+    if (resolved !== undefined)
+        return resolved;
+    const fresh = resolveResponses(program, operation);
+    resolvedResponses.set(operation, fresh);
+    return fresh;
+}
+const resolvedResponses = new WeakMap();
+function resolveResponses(program, operation) {
     const byStatus = new Map();
     for (const response of operation.responses) {
         for (const status of statusKeysOf(program, response)) {
@@ -302,22 +318,28 @@ function responsesOf(program, operation, registry) {
                 contentTypes: new Set(),
                 headers: [],
                 streamed: false,
+                file: false,
             };
             for (const content of response.responses) {
                 if (entry.body === undefined && content.body?.bodyKind === "single") {
                     entry.body = bodyTypeOf(content.body.type);
                 }
+                /**
+                 * **An `Http.File` response's body is its contents, served as bytes.** The same reading
+                 * as a file request body: a media type and nothing to serialise. Read only for
+                 * `"single"`, every download in `type/file` declared `image/png` and was served empty.
+                 */
+                if (entry.body === undefined && content.body?.bodyKind === "file") {
+                    entry.body = content.body.contents.type;
+                    entry.file = true;
+                }
                 for (const contentType of content.body?.contentTypes ?? []) {
                     entry.contentTypes.add(contentType);
                 }
                 for (const [name, property] of Object.entries(content.headers ?? {})) {
                     if (entry.headers.some((existing) => existing.name === name))
                         continue;
-                    entry.headers.push({
-                        name,
-                        type: typeToTs(program, property.type),
-                        optional: property.optional,
-                    });
+                    entry.headers.push({ name, property });
                 }
             }
             if (streamedTypeOf(program, response.type) !== undefined)
@@ -325,27 +347,73 @@ function responsesOf(program, operation, registry) {
             byStatus.set(key, entry);
         }
     }
-    return [...byStatus.values()]
-        .map((entry) => {
+    return [...byStatus.values()].map((entry) => {
         const contentTypes = [...entry.contentTypes];
-        const binary = entry.body !== undefined && isBinaryPart(entry.body) && isRawBinaryMediaType(contentTypes);
         return {
             status: entry.status,
-            schema: entry.body === undefined
-                ? undefined
-                : binary
-                    ? "z.unknown()"
-                    : registry.expressionFor(entry.body),
+            body: entry.body,
             contentTypes,
             headers: entry.headers,
-            binary,
+            binary: entry.file ||
+                (entry.body !== undefined &&
+                    isBinaryPart(entry.body) &&
+                    isRawBinaryMediaType(contentTypes)),
             streamed: entry.streamed,
-            textual: entry.body !== undefined && isStringType(entry.body),
+            textual: !entry.file && entry.body !== undefined && isStringType(entry.body),
         };
-    })
-        .toSorted((a, b) => statusPrecedenceOf(a.status) - statusPrecedenceOf(b.status) ||
+    });
+}
+/** Responses in OpenAPI's precedence order: exact codes, then ranges, then `default`. */
+function inPrecedenceOrder(responses) {
+    return responses.toSorted((a, b) => statusPrecedenceOf(a.status) - statusPrecedenceOf(b.status) ||
         statusOrderOf(a.status) - statusOrderOf(b.status));
 }
+/**
+ * Every response the operation declares, rendered as Zod, in OpenAPI's precedence order.
+ *
+ * Every header is rendered before any body, and bodies in precedence order, which is the order this
+ * has always declared components in: the emitted files do not move because the resolution moved.
+ *
+ * Call inside `withVisibility(program, Visibility.Read, ...)`: a response is read at `Read`, and
+ * resolving it under a request visibility declares components under the wrong suffix.
+ */
+function responsesOf(program, operation, registry) {
+    const withHeaders = resolvedResponsesOf(program, operation).map((response) => ({
+        response,
+        headers: response.headers.map(({ name, property }) => ({
+            name,
+            /**
+             * **Encode-aware, as the schema beside it is.** `@encode(seconds, int32)` makes a `duration`
+             * an integer on the wire, and the header schema checks an integer; reading the declared type
+             * alone published `string`, so a handler satisfying its own result type was refused by its
+             * own header check and the arm could not be returned without a cast.
+             */
+            type: propertyTypeToTs(program, property),
+            /**
+             * **The Zod expression, which used to be discarded here.** Every REQUEST parameter goes
+             * through `expressionForProperty` a few hundred lines below; a response header went
+             * through `typeToTs` and nothing else, so the emitted arm carried a name and an
+             * optionality and no way to check a value. A response body that breaks its schema throws
+             * `ResponseContractError`; a header that breaks its own was served.
+             */
+            schema: registry.expressionForProperty(property),
+            optional: property.optional,
+        })),
+    }));
+    return inPrecedenceOrder(withHeaders.map(({ response, headers }) => ({ status: response.status, response, headers }))).map(({ response, headers }) => ({
+        status: response.status,
+        schema: response.body === undefined
+            ? undefined
+            : response.binary
+                ? "z.unknown()"
+                : registry.expressionFor(response.body),
+        contentTypes: response.contentTypes,
+        headers,
+        binary: response.binary,
+        streamed: response.streamed,
+        textual: response.textual,
+    }));
+}
 /**
  * Where an arm sits in OpenAPI's own precedence order.
  *
@@ -531,33 +599,6 @@ export function errorBodyOf(program, service) {
 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.
  *
@@ -793,7 +834,18 @@ function isBinaryPart(type) {
 export function isRawBinaryMediaType(contentTypes) {
     if (contentTypes.length === 0)
         return false;
-    return contentTypes.every((type) => !/^application\/(json|.*\+json)$/.test(type));
+    return contentTypes.every((type) => !isJsonMediaType(type));
+}
+/**
+ * A media type a server can parse a request body from into a value its schema can check: JSON and
+ * the `+json` suffix RFC 6839 defines, a URL-encoded form, and multipart. Anything else - XML, a
+ * vendor type - has no reading this emitter can derive from the document.
+ */
+function isParseableMediaType(type) {
+    const essence = mediaTypeEssenceOf(type);
+    return (isJsonMediaType(essence) ||
+        essence === "application/x-www-form-urlencoded" ||
+        essence.startsWith("multipart/"));
 }
 /** The declared request body type, if the operation takes one. */
 function requestBodyOf(operation) {
@@ -968,9 +1020,52 @@ function mediaTypeDecoded(declared) {
             .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})`;
+    /**
+     * **A declared media RANGE admits the types inside it, and a literal admits only itself.**
+     *
+     * \`@header contentType: "text/*"\` published \`z.literal("text/*")\`, so the only request that
+     * satisfied it was one sending the range itself as its \`Content-Type\`, which no client does.
+     * Measured before this existed: \`text/plain\` and \`text/html\` both answered 400 on a route whose
+     * document declares the whole \`text\` group.
+     *
+     * A template literal is the Zod counterpart of the TypeScript type the contract already uses for
+     * a range, so the validator and the handler's own type say the same thing.
+     */
+    const admitted = values.map((value) => {
+        /**
+         * **The full wildcard admits every media type, so there is nothing left to match on.**
+         *
+         * Spelled as a template literal it becomes the prefix `*` + `/`, which matches only a
+         * Content-Type whose text begins with the range's own first two characters. Measured on the
+         * emitted schema: `application/json`, `text/plain` and `image/png` were all REFUSED and the
+         * literal `*` + `/*` was the one value accepted, which is the defect the range branch exists
+         * to remove rather than to respell. A consumer declares this on a file upload that takes
+         * whatever the caller sends.
+         */
+        if (value === "*/*")
+            return "z.string()";
+        return isMediaRange(value)
+            ? `z.templateLiteral([${JSON.stringify(mediaTypeEssenceOf(value).slice(0, -1))}, z.string()])`
+            : `z.literal(${JSON.stringify(value)})`;
+    });
+    const schema = admitted.length === 1 ? (admitted[0] ?? declared) : `z.union([${admitted.join(", ")}])`;
+    const ranged = values.some(isMediaRange) ? schema : declared;
+    /**
+     * **The request's media type is reduced to its essence, and so is every declared one.** A value
+     * declared as its own essence - `application/json` - is the literal the essence is compared with.
+     * One declared with a parameter or in capitals - `application/json; charset=utf-8` - is restored
+     * from the essence, so the request is admitted and the handler is given the type as the document
+     * declares it, which is what its input type says. Compared as written, such a value refused every
+     * request: no request's essence carries a parameter.
+     */
+    const restored = values.filter((value) => !isMediaRange(value) && mediaTypeEssenceOf(value) !== value);
+    const essence = `(raw.split(";")[0] ?? "").trim().toLowerCase()`;
+    const decoded = restored.length === 0
+        ? essence
+        : `((essence) => ${restored
+            .map((value) => `essence === ${JSON.stringify(mediaTypeEssenceOf(value))} ? ${JSON.stringify(value)} : `)
+            .join("")}essence)(${essence})`;
+    return `z.preprocess((raw) => (typeof raw === "string" ? ${decoded} : raw), ${ranged})`;
 }
 function parameterSchemasOf(program, operation, registry, segments, 
 /** The names of a query string written into the route itself, which no parameter may gather. */
@@ -983,7 +1078,22 @@ literalQueryNames) {
         .filter((parameter) => parameter.type === "query")
         .map((parameter) => parameter.name);
     for (const parameter of operation.parameters.parameters) {
-        if (parameter.type !== "path" && parameter.type !== "query" && parameter.type !== "header") {
+        /**
+         * **`cookie` is here because `@typespec/http` puts it here**, and excluding it was silent.
+         * `HttpOperationParameter` discriminates on `"header" | "cookie" | "query" | "path"`, and this
+         * filter named three of the four, so a `@cookie` reached no validator, no handler input and no
+         * diagnostic while `@typespec/openapi3` published it as `in: cookie, required: true`. A
+         * requirement the document states and the server cannot see is the defect class this package
+         * exists to remove, and a cookie is where a session and a CSRF token normally live.
+         *
+         * The exclusion was by omission rather than by a `never` check, which is why TypeScript never
+         * objected; every other place that reads `parameter.type` handles an encoding question a cookie
+         * does not have, since `CookieOptions` carries only a name.
+         */
+        if (parameter.type !== "path" &&
+            parameter.type !== "query" &&
+            parameter.type !== "header" &&
+            parameter.type !== "cookie") {
             continue;
         }
         /**
@@ -1096,12 +1206,20 @@ literalQueryNames) {
             (byTarget["header-without-accept"] ??= []).push(entry);
         }
     }
+    const fileContentType = fileContentTypeOf(operation);
+    if (fileContentType !== undefined) {
+        // The same decoding a declared `Content-Type` header gets: parameters dropped, lowercased.
+        const entry = `\t${objectKey("Content-Type")}: ${mediaTypeDecoded(registry.expressionFor(fileContentType.type))},`;
+        (byTarget["header"] ??= []).push(entry);
+        (byTarget["header-without-accept"] ??= []).push(entry);
+    }
     const shape = (target) => {
         const entries = byTarget[target];
         return entries === undefined ? undefined : `z.object({\n${entries.join("\n")}\n})`;
     };
     const query = shape("query");
     return {
+        cookie: shape("cookie"),
         path: shape("path"),
         query: query === undefined
             ? undefined
@@ -1132,6 +1250,178 @@ function modelPropertiesOf(model) {
     }
     return chain.flatMap((current) => [...current.properties.values()]);
 }
+/**
+ * **The media type an `Http.File` body declares, as the input it is.** A file's `contentType` is the
+ * request's `Content-Type`: `Http.File<"image/png" | "image/jpeg">` accepts either and the handler has
+ * to know which arrived, exactly as it would from a declared `@header contentType`. `@typespec/http`
+ * keeps it on the file model rather than among the operation's parameters, so without this a
+ * handler for a two-type upload had the bytes and no way to tell what they were.
+ *
+ * `undefined` where the body is not a file, or where the operation already declares the header.
+ */
+function fileContentTypeOf(operation) {
+    const body = operation.parameters.body;
+    if (body?.bodyKind !== "file")
+        return undefined;
+    const declared = operation.parameters.parameters.some((parameter) => parameter.type === "header" && parameter.name.toLowerCase() === "content-type");
+    return declared ? undefined : body.contentTypeProperty;
+}
+/**
+ * Where a request body reaches a handler's input: spread into it, named under a property, or handed
+ * over unread.
+ *
+ * **One decision, read by every artefact that states an operation's input.** The server emitters
+ * render a handler's input from {@link EmittedRoute.bodyProperty}; the contract types in
+ * `requests.gen.ts` re-derived the input for themselves and always merged, so for every body this
+ * names - an indexer, an optional body, a scalar, enum or union - `WireInputs` described an input no
+ * handler receives.
+ */
+/**
+ * The keys a merged body would contribute to the handler's input: each property of the body SENT,
+ * at the operation's request visibility, under its wire name, or each named part of a multipart
+ * body. A read-only property is not sent, so it contributes nothing.
+ */
+function mergedBodyKeysOf(program, operation) {
+    const body = operation.parameters.body;
+    if (body?.bodyKind === "multipart") {
+        return body.parts.flatMap((part) => (part.name === undefined ? [] : [part.name]));
+    }
+    const type = requestBodyOf(operation);
+    if (type?.kind !== "Model")
+        return [];
+    return withVisibility(program, resolveRequestVisibility(program, operation.operation, operation.verb), () => [...walkPropertiesInherited(type)]
+        .filter((property) => isPayloadProperty(program, property))
+        .map((property) => resolveEncodedName(program, property, "application/json")));
+}
+function requestBodyPlacementOf(program, operation) {
+    const requestType = requestBodyOf(operation);
+    const bodyParameter = operation.parameters.body;
+    const contentTypes = [...(bodyParameter?.contentTypes ?? [])];
+    /**
+     * 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 bytes = requestType?.kind === "Scalar" && requestType.name === "bytes";
+    /**
+     * **A body declared only under media types nothing can parse into it is handed over raw.** A
+     * model as `application/xml` has no serialisation this emitter can derive, and the server has no
+     * reader for it; it used to get a header check and then call the handler with the body never
+     * read, while the warning beside it said such requests were refused. Handed over as it arrived,
+     * the handler parses it - exactly what the response side already asks of a handler serving a model
+     * as XML. It is the text under a textual media type and the bytes under any other
+     * (`rawBodyBinary`). A string body is not this: it IS text, and its schema still checks it
+     * (`requestTextual`).
+     */
+    const unparseable = bodyParameter?.bodyKind === "single" &&
+        requestType !== undefined &&
+        !bytes &&
+        !isStringType(requestType) &&
+        contentTypes.length > 0 &&
+        contentTypes.every((type) => !isParseableMediaType(type));
+    /**
+     * **An `Http.File` body is raw too: the file's contents ARE the body.** `@typespec/openapi3`
+     * publishes it as `content: { "image/png": { schema: { contentMediaType: "image/png" } } }` - a
+     * media type and no type, nothing to parse and nothing to validate - which is exactly a `bytes`
+     * body under that media type. `requestBodyOf` reads only `bodyKind === "single"`, so a file body
+     * reached no placement at all: the handler was passed `{}` and the upload was dropped, from a
+     * compile that reported success, on all four uploads in `type/file`.
+     */
+    const rawBodyProperty = bytes || bodyParameter?.bodyKind === "file" || unparseable
+        ? (bodyParameter?.property?.name ?? "body")
+        : undefined;
+    /**
+     * A body with an indexer is named rather than spread - see `bodyProperty`. Read from the
+     * resolved model's own indexer rather than from the emitted schema text, which would be a
+     * decision made by pattern-matching generated output.
+     */
+    /**
+     * **An OPTIONAL body is named for the same reason an indexed one is**: the merge cannot
+     * express "absent". See {@link EmittedRoute.optionalBody}.
+     */
+    const optionalBody = bodyParameter?.property?.optional === true;
+    /**
+     * **An optional MULTIPART body reaches the same rule by a second route, because
+     * `requestType` cannot see it.** `requestBodyOf` resolves a type only for
+     * `bodyKind === "single"`, so `requestType` is `undefined` for every multipart operation
+     * and the `optionalBody` disjunct above was unreachable however the document declared it.
+     *
+     * The emitted server for such an operation did not compile. Measured, and the mechanism is
+     * worth stating because it is not a union: spreading a value typed `Parts | undefined`
+     * makes every part OPTIONAL, so `{ file?: ...; pages?: ... }` was passed where
+     * `{ file: ...; pages: ... }` was required. `TS2345`, inside `app.gen.ts` itself.
+     *
+     * That is the failure {@link EmittedRoute.optionalBody} predicts in prose - a merge has no
+     * way to say "these properties are here only sometimes" without making every one of them
+     * optional, which is a weaker and different claim about the body that IS sent. So this is
+     * the stated rule reaching the one body kind it had never been applied to, not a new rule.
+     *
+     * **The REQUIRED arm is deliberately excluded.** The indexed reason does not apply to a
+     * parts model, so a required multipart body merges as safely as a required single one, and
+     * `typespec-hono/test/filepart/` compiles a handler that reads `input.file` directly.
+     * Widening this to "multipart is always named" would rewrite that directory for no defect.
+     *
+     * This is the third hole the `"single"` gate has produced, after `multipartSchemaOf` and
+     * `multipartTsOf`, both recorded above.
+     */
+    const optionalMultipartBody = bodyParameter?.bodyKind === "multipart" && optionalBody;
+    /**
+     * **A body that is not a MODEL has no properties to merge, and merging it anyway lost it.**
+     *
+     * `@body body: string` emitted a handler input of `Record<string, never>` and a call site of
+     * `{}`: the server validated the body and then never handed it to the handler, silently, from
+     * a compile that reported success. `@body body: SomeEnum` was the same rule failing loudly,
+     * `TS2698: Spread types may only be created from object types`, which is what
+     * `payload/media-type`, `type/enum/*`, `type/scalar` and `versioning/returnTypeChangedFrom`
+     * had been pinned on in the conformance corpus.
+     *
+     * A scalar, an enum, a union or a literal body is therefore NAMED, which is the treatment an
+     * indexed or optional body already gets and for the same reason: the merge cannot express it.
+     *
+     * **Except a `bytes` body**, which {@link EmittedRoute.rawBodyProperty} already names, and
+     * naming it twice would put the same value under two keys.
+     */
+    const unmergeableBody = requestType !== undefined && requestType.kind !== "Model" && rawBodyProperty === undefined;
+    /**
+     * **A body sharing a key with a parameter is named, because merged one value replaces the
+     * other.** `PUT /renames/{name}` with a body `{ name }` handed the handler one `name`, the body's,
+     * and the path's was lost with nothing reported - in `parameters/spread`'s composite request, and
+     * in any spec whose body repeats a path or query parameter. The document states the two
+     * separately; named, the handler is given both. A read-only property is not in the body sent, so
+     * `@path id` beside a model whose `id` is read-only collides with nothing and still merges.
+     */
+    const parameterNames = new Set(operation.parameters.parameters.map((parameter) => parameter.name));
+    const collides = rawBodyProperty === undefined &&
+        mergedBodyKeysOf(program, operation).some((key) => parameterNames.has(key));
+    const bodyProperty = (requestType?.kind === "Model" && (requestType.indexer !== undefined || optionalBody)) ||
+        optionalMultipartBody ||
+        unmergeableBody ||
+        collides
+        ? (bodyParameter?.property?.name ?? "body")
+        : undefined;
+    /**
+     * A file is handed over as a stream of bytes whatever its media type. `@typespec/http` lets an
+     * emitter represent a textual file "as strings or streams of textual characters", and one
+     * representation for every file is what lets a file declared `application/json` be told from a
+     * JSON body - which the media type alone cannot do.
+     *
+     * **A body nothing parses is bytes unless every type it is declared under is text.** Decoded as
+     * text, `application/octet-stream` lost every byte that is not valid UTF-8; see
+     * {@link isTextualMediaType}.
+     */
+    const rawBodyBinary = rawBodyProperty !== undefined &&
+        (unparseable
+            ? !contentTypes.every(isTextualMediaType)
+            : bodyParameter?.bodyKind === "file" || isRawBinaryMediaType(contentTypes));
+    return {
+        rawBodyProperty,
+        rawBodyBinary,
+        rawBodyUnvalidated: unparseable,
+        bodyProperty,
+        optionalBody,
+    };
+}
 export function collectRoutes(program, registry, service) {
     const routes = [];
     {
@@ -1161,73 +1451,7 @@ export function collectRoutes(program, registry, service) {
             // `@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);
-            /**
-             * 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;
-            /**
-             * A body with an indexer is named rather than spread - see `bodyProperty`. Read from the
-             * resolved model's own indexer rather than from the emitted schema text, which would be a
-             * decision made by pattern-matching generated output.
-             */
-            /**
-             * **An OPTIONAL body is named for the same reason an indexed one is**: the merge cannot
-             * express "absent". See {@link EmittedRoute.optionalBody}.
-             */
-            const optionalBody = bodyParameter?.property?.optional === true;
-            /**
-             * **An optional MULTIPART body reaches the same rule by a second route, because
-             * `requestType` cannot see it.** `requestBodyOf` resolves a type only for
-             * `bodyKind === "single"`, so `requestType` is `undefined` for every multipart operation
-             * and the `optionalBody` disjunct above was unreachable however the document declared it.
-             *
-             * The emitted server for such an operation did not compile. Measured, and the mechanism is
-             * worth stating because it is not a union: spreading a value typed `Parts | undefined`
-             * makes every part OPTIONAL, so `{ file?: ...; pages?: ... }` was passed where
-             * `{ file: ...; pages: ... }` was required. `TS2345`, inside `app.gen.ts` itself.
-             *
-             * That is the failure {@link EmittedRoute.optionalBody} predicts in prose - a merge has no
-             * way to say "these properties are here only sometimes" without making every one of them
-             * optional, which is a weaker and different claim about the body that IS sent. So this is
-             * the stated rule reaching the one body kind it had never been applied to, not a new rule.
-             *
-             * **The REQUIRED arm is deliberately excluded.** The indexed reason does not apply to a
-             * parts model, so a required multipart body merges as safely as a required single one, and
-             * `typespec-hono/test/filepart/` compiles a handler that reads `input.file` directly.
-             * Widening this to "multipart is always named" would rewrite that directory for no defect.
-             *
-             * This is the third hole the `"single"` gate has produced, after `multipartSchemaOf` and
-             * `multipartTsOf`, both recorded above.
-             */
-            const optionalMultipartBody = bodyParameter?.bodyKind === "multipart" && optionalBody;
-            /**
-             * **A body that is not a MODEL has no properties to merge, and merging it anyway lost it.**
-             *
-             * `@body body: string` emitted a handler input of `Record<string, never>` and a call site of
-             * `{}`: the server validated the body and then never handed it to the handler, silently, from
-             * a compile that reported success. `@body body: SomeEnum` was the same rule failing loudly,
-             * `TS2698: Spread types may only be created from object types`, which is what
-             * `payload/media-type`, `type/enum/*`, `type/scalar` and `versioning/returnTypeChangedFrom`
-             * had been pinned on in the conformance corpus.
-             *
-             * A scalar, an enum, a union or a literal body is therefore NAMED, which is the treatment an
-             * indexed or optional body already gets and for the same reason: the merge cannot express it.
-             *
-             * **Except a `bytes` body**, which {@link EmittedRoute.rawBodyProperty} already names, and
-             * naming it twice would put the same value under two keys.
-             */
-            const unmergeableBody = requestType !== undefined && requestType.kind !== "Model" && rawBodyProperty === undefined;
-            const bodyProperty = (requestType?.kind === "Model" && (requestType.indexer !== undefined || optionalBody)) ||
-                optionalMultipartBody ||
-                unmergeableBody
-                ? (bodyParameter?.property?.name ?? "body")
-                : undefined;
+            const { rawBodyProperty, rawBodyBinary, rawBodyUnvalidated, bodyProperty, optionalBody } = requestBodyPlacementOf(program, operation);
             const authentication = authenticationFor(program, operation);
             const template = routeTemplateOf(operation.uriTemplate, operation.parameters.parameters
                 .filter((parameter) => parameter.type === "path")
@@ -1299,6 +1523,7 @@ export function collectRoutes(program, registry, service) {
                 ...(() => {
                     const split = withVisibility(program, requestVisibility, () => parameterSchemasOf(program, operation, registry, template.segments, template.literalQuery.map(([name]) => name)));
                     return {
+                        cookieSchema: split.cookie,
                         pathSchema: split.path,
                         querySchema: split.query,
                         queryFieldsSchema: split.queryFields,
@@ -1315,6 +1540,8 @@ export function collectRoutes(program, registry, service) {
                  */
                 responses: withVisibility(program, Visibility.Read, () => responsesOf(program, operation, registry)),
                 rawBodyProperty,
+                rawBodyBinary,
+                rawBodyUnvalidated,
                 bodyProperty,
                 optionalBody,
                 scopes: authentication.scopes,
@@ -1452,13 +1679,30 @@ function renderSchemas(registry, externals, routeDeclarations, compileSchemas) {
          * parse - the walk captures the reference while it is still in the temporal dead zone, so the
          * failure surfaces at request time rather than at import.
          *
-         * **Keyed on `annotated`, the fact the registry already holds** - it is set exactly when the
-         * declaration is deferred, which is exactly when `z.lazy()` is written - rather than on the
-         * shape of the emitted text. A model on a cycle whose back edge sits on a GETTER is a different
-         * case and is compiled like any other: measured, it parses, because a getter is not resolved
-         * until something reads it.
+         * **CYCLE MEMBERSHIP decides this, not deferral, and that took a zod upgrade to learn.**
+         *
+         * It was keyed on `annotated` - set exactly when the declaration is deferred, which is exactly
+         * when `z.lazy()` is written - on the measurement that a model whose back edge sits on a GETTER
+         * compiled and parsed fine. That was true on zod 4.5.2 and is false on 4.6.5, which made the
+         * recursive parse state weak. The failure moved from the deferred declaration to the one that
+         * REFERENCES it, which was still being compiled:
+         *
+         * ```
+         * const branchSchema = z.lazy(() => z.union([nodeSchema, z.string()]));
+         * const nodeSchema = z.compile(z.strictObject({ ..., branch: branchSchema.exactOptional() }));
+         * nodeSchema.safeParse({ label: "a", attributes: {} });
+         * zod 4.5.2: true
+         * zod 4.6.5: TypeError: Cannot read properties of undefined (reading '_zod')
+         * ```
+         *
+         * Bisected: naming a compiled schema from inside a `z.lazy()` body is the whole trigger, and
+         * the self-referencing getter is not needed for it. So the same rule the registry already
+         * applies to structural types applies here - every member of the cycle, not only the deferred
+         * one - and `structural` is the fact it already holds for exactly that set.
+         *
+         * The peer range admits 4.6, so this reached a running server on the first parse.
          */
-        return `\n${declared}\nexport const ${d.identifier}${annotation} = ${compiled(d.source, compileSchemas && d.annotated !== true)};\n`;
+        return `\n${declared}\nexport const ${d.identifier}${annotation} = ${compiled(d.source, compileSchemas && d.structural === undefined)};\n`;
     });
     /**
      * **Written only when something in the file names it**, like the `ResponseArm` import below and for
@@ -1490,10 +1734,9 @@ function renderSchemas(registry, externals, routeDeclarations, compileSchemas) {
      * `p?: T` directly - at every depth, which a shallow mapped type never reached - so the narrowing
      * happens once, in the schema, and this helper has nothing left to do.
      *
-     * The contract types in `requests.gen.ts` still keep `?: T | undefined` on purpose: they are the
-     * floor a PRODUCER supplies, and `{ p: undefined }` serialises identically to omitting `p`, so
-     * refusing it there would cost every producer a conditional spread and buy the wire nothing.
-     * Narrowing THAT surface was tried in `0.19.0` and reverted - it broke `(ctx, input) => ok(input)`.
+     * The contract types in `requests.gen.ts` say the same since `0.28.0`: `?: T`, and
+     * `?: T | undefined` only where `.default()` accepts an explicit `undefined`. They had kept it
+     * everywhere on reasons that stopped holding once this schema moved - see `propertyToTs`.
      */
     const usesZod = new Set([...declarations, ...routeDeclarations].join("").match(/[A-Za-z_$][\w$]*/g) ?? []).has("z");
     const parts = [generatedBanner()];
@@ -1633,6 +1876,7 @@ function nameRouteSchemas(routes, compileSchemas) {
         const query = declare("Query", gathers && queryFields !== undefined && route.queryFieldsSchema !== undefined
             ? route.querySchema?.replace(route.queryFieldsSchema, queryFields)
             : route.querySchema);
+        const cookie = declare("Cookie", route.cookieSchema);
         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.
@@ -1643,13 +1887,28 @@ function nameRouteSchemas(routes, compileSchemas) {
          */
         const declaredBodies = new Map();
         const arms = route.responses.map((response) => {
-            if (response.schema === undefined)
-                return { status: response.status, schema: undefined };
+            const suffix = response.status === "default" ? "Default" : String(response.status);
+            /**
+             * The headers this status declares, as one object schema, so a server can check what it is
+             * about to send the way it already checks the body.
+             *
+             * **A plain `z.object`, which strips.** A response carries headers the document does not
+             * declare - `Content-Type` among them, which the server sets itself - and those are not a
+             * contract violation. What is checked is that every header the document DOES declare carries
+             * a value the document permits.
+             */
+            const headers = response.headers.length === 0
+                ? undefined
+                : declare(`Response${suffix}Headers`, `z.object({\n${response.headers
+                    .map((header) => `\t${objectKey(header.name)}: ${header.schema},`)
+                    .join("\n")}\n})`);
+            if (response.schema === undefined) {
+                return { status: response.status, schema: undefined, headers };
+            }
             if (!declaredBodies.has(response.schema)) {
-                const suffix = response.status === "default" ? "Default" : String(response.status);
                 declaredBodies.set(response.schema, declare(`Response${suffix}`, response.schema));
             }
-            return { status: response.status, schema: declaredBodies.get(response.schema) };
+            return { status: response.status, schema: declaredBodies.get(response.schema), headers };
         });
         const responses = schemaConst(route.operationId, "Responses");
         declarations.push(`export const ${responses} = ${responseArmsOf(route, arms)} satisfies readonly ResponseArm[];`);
@@ -1659,6 +1918,8 @@ function nameRouteSchemas(routes, compileSchemas) {
             query,
             queryFields: gathers ? queryFields : query,
             header,
+            selectedAccept: negotiating ? route.accept : undefined,
+            cookie,
             body,
             arms,
             responses,
@@ -1691,118 +1952,127 @@ function responseArmsOf(route, arms) {
     });
     return `[${rendered.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.
+ * Every operation's input, as TypeScript, exactly as a handler receives it.
+ *
+ * **One placement rule, the one the server emitters render from.** A model body is merged with the
+ * path, query, header and cookie parameters; a body the merge cannot express is named under its
+ * parameter's name, optional where the document lets it be absent; a `bytes` body is handed over
+ * unread. {@link requestBodyPlacementOf} decides all three, for this walk and for
+ * {@link EmittedRoute} alike. This walk used to merge every body, so for a union, an array, an
+ * indexed model, an optional body, a scalar or an enum, `WireInputs` described an input no handler is
+ * given - and one consumer carried a shim re-flattening the handler's input to reach a backend typed
+ * by it, after the divergence cost it 171 failing tests.
+ *
+ * **Every operation, whatever it takes and whatever it answers.** An operation with no input is
+ * `Record<string, never>`, which is what a handler for it is passed; one whose only success is a
+ * range is as much an operation as any other. Both used to be skipped, so `keyof WireInputs` could
+ * not enumerate a document's operations, and a consumer named the missing ones by hand.
  *
  * **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.
  */
+/** A body type the contract declares by name, rather than spells inline: a model, union or enum. */
+function declaresComponent(type) {
+    return type.kind === "Model" || type.kind === "Union" || type.kind === "Enum";
+}
 function collectRequestTypes(program, registry, service) {
     const entries = [];
-    {
-        for (const operation of service.operations) {
-            if (successStatusOf(operation) === undefined)
-                continue;
+    for (const operation of service.operations) {
+        /**
+         * **Walked at the operation's REQUEST visibility, which is the whole point of this file.**
+         *
+         * `resolveRequestVisibility` is `@typespec/http`'s own answer - POST is Create, PATCH is
+         * Update, PUT is CreateOrUpdate - and it is what the Zod walk already uses at the route level.
+         * Without it this walk ran at the default `Read`, so a POST body's contract type carried the
+         * canonical property set while the validator beside it accepted the create projection. A
+         * caller satisfying the published type sent read-only fields and a strict validator answered
+         * 400.
+         *
+         * It is also what keeps `metadataInfo` scoped: the predicates `propertyToTs` consults live
+         * behind `withVisibility`, and calling them outside one leaves a module-level singleton built
+         * for the wrong program.
+         */
+        withVisibility(program, resolveRequestVisibility(program, operation.operation, operation.verb), () => {
+            const body = requestBodyOf(operation);
+            const placement = requestBodyPlacementOf(program, operation);
+            /** The parts of a multipart body, which `requestBodyOf` deliberately does not return. */
+            const parameterBody = operation.parameters.body;
             /**
-             * **Walked at the operation's REQUEST visibility, which is the whole point of this file.**
-             *
-             * `resolveRequestVisibility` is `@typespec/http`'s own answer - POST is Create, PATCH is
-             * Update, PUT is CreateOrUpdate - and it is what the Zod walk already uses at the route
-             * level. Without it this walk ran at the default `Read`, so a POST body's contract type
-             * carried the canonical property set while the validator beside it accepted the create
-             * projection. A caller satisfying the published type sent read-only fields and a strict
-             * validator answered 400.
+             * Headers are part of the input too.
              *
-             * It is also what keeps `metadataInfo` scoped: the predicates `propertyToTs` consults live
-             * behind `withVisibility`, and calling them outside one leaves a module-level singleton
-             * built for the wrong program.
+             * 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.
              */
-            withVisibility(program, resolveRequestVisibility(program, operation.operation, operation.verb), () => {
-                const body = requestBodyOf(operation);
-                /** The parts of a multipart body, which `requestBodyOf` deliberately does not return. */
-                const multipartBody = operation.parameters.body;
-                const multipart = multipartBody?.bodyKind === "multipart" ? { parts: multipartBody.parts } : undefined;
+            const extraProperties = operation.parameters.parameters
+                .filter((parameter) => parameter.type === "path" ||
+                parameter.type === "query" ||
+                parameter.type === "header" ||
+                // The second half of the same omission: a validator with no matching type.
+                parameter.type === "cookie")
                 /**
-                 * 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.
+                 * 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.
                  */
-                const extraProperties = operation.parameters.parameters
-                    .filter((parameter) => parameter.type === "path" ||
-                    parameter.type === "query" ||
-                    parameter.type === "header")
-                    /**
-                     * 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));
-                // `return` rather than `continue`: this body is a callback now, and returning from it
-                // skips the operation exactly as the `continue` did.
-                if (body === undefined && extraProperties.length === 0)
-                    return;
+                .map((parameter) => registry.expressionForProperty(parameter.param, parameter.name));
+            const fileContentType = fileContentTypeOf(operation);
+            if (fileContentType !== undefined) {
+                extraProperties.push(`${objectKey("Content-Type")}: ${registry.expressionFor(fileContentType.type)};`);
+            }
+            const parts = [];
+            let streamsBody = false;
+            let bodyRef;
+            if (placement.rawBodyProperty !== undefined) {
                 /**
-                 * 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.
+                 * **A binary body is the unread stream, and is spelled as one without naming
+                 * `ReadableStream`.** The server hands it over unread, so a backend it is forwarded to
+                 * receives a stream; a contract saying `ArrayBuffer` made a gateway read a 25 MiB upload
+                 * into an isolate to satisfy it. See `BYTE_STREAM`. A `bytes` body under a JSON type is
+                 * the text a signature covers, and arrives as a string.
                  */
-                const rawBody = body?.kind === "Scalar" && body.name === "bytes"
-                    ? (operation.parameters.body?.property?.name ?? "body")
-                    : undefined;
+                streamsBody = placement.rawBodyBinary;
+                parts.push(`{\n\t${objectKey(placement.rawBodyProperty)}: ${streamsBody ? "ByteStream | null" : "string"};\n}`);
                 /**
-                 * **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.
+                 * **The model a body nothing parses names is still declared**, as the document declares
+                 * it, though the input is the text or the bytes that arrived. 0.27.0 declared it, and a
+                 * consumer importing it lost the import when the body became raw.
                  */
-                const rawBodyType = isRawBinaryMediaType([
-                    ...(operation.parameters.body?.contentTypes ?? []),
-                ])
-                    ? "ArrayBuffer"
-                    : "string";
-                entries.push({
-                    operationId: operationIdOf(program, operation.operation),
-                    bodyRef: rawBody !== undefined
-                        ? `{\n\t${rawBody}: ${rawBodyType};\n}`
-                        : multipart !== undefined
-                            ? multipartTsOf(multipart, registry)
-                            : body === undefined
-                                ? undefined
-                                : registry.expressionFor(body),
-                    extraProperties,
-                });
+                if (body !== undefined && declaresComponent(body))
+                    registry.expressionFor(body);
+            }
+            else {
+                const expression = parameterBody?.bodyKind === "multipart"
+                    ? multipartTsOf({ parts: parameterBody.parts }, registry)
+                    : body === undefined
+                        ? undefined
+                        : registry.expressionFor(body);
+                if (parameterBody?.bodyKind !== "multipart")
+                    bodyRef = expression;
+                if (expression !== undefined) {
+                    parts.push(placement.bodyProperty === undefined
+                        ? expression
+                        : `{\n\t${objectKey(placement.bodyProperty)}${placement.optionalBody ? "?" : ""}: ${expression.replaceAll("\n", "\n\t")};\n}`);
+                }
+            }
+            if (extraProperties.length > 0) {
+                parts.push(`{\n${extraProperties.map((line) => `\t${line}`).join("\n")}\n}`);
+            }
+            entries.push({
+                operationId: operationIdOf(program, operation.operation),
+                bodyRef,
+                input: parts.length === 0 ? "Record<string, never>" : `Simplify<${parts.join(" & ")}>`,
+                streamsBody,
             });
-        }
+        });
     }
     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 = [];
     /**
@@ -1815,20 +2085,135 @@ function collectResponseTypes(program, registry, service) {
      */
     withVisibility(program, Visibility.Read, () => {
         for (const operation of service.operations) {
-            const status = successStatusOf(operation);
-            if (status === undefined)
-                continue;
-            const body = successBodyOf(operation, status);
-            if (body === undefined)
-                continue;
+            /**
+             * **The same responses, and the same members, the server emitters render.** This walk used
+             * to ask for the lowest success status and its body, so an operation answering `200 Thing`
+             * or `201 Other` published `Thing`, one answering `200 Thing` or `204` published `Thing`,
+             * and one answering only `204` was absent - while the runtime beside it carried every arm.
+             */
+            const responses = inPrecedenceOrder(resolvedResponsesOf(program, operation));
+            const hasBody = (response) => response.body !== undefined;
+            let streams = false;
+            const bodyRefs = [];
+            /**
+             * **What a producer SUPPLIES for a body, which is what the server emitters accept for it.** A
+             * stream or a raw binary body is handed over as bytes and never parsed, so it is spelled as
+             * bytes - `ByteStream` rather than the platform stream, for the same reason as a request body.
+             * A model under a media type that is not JSON is what the producer serialised: text under a
+             * textual media type, bytes under any other. Everything else is the producer's view of the
+             * contract type.
+             */
+            const bodyOf = (member) => {
+                // A model a body served unvalidated names is declared all the same, as the request side
+                // declares one under a media type nothing parses: the document declares it either way.
+                if (member.unvalidated &&
+                    member.response.body !== undefined &&
+                    declaresComponent(member.response.body)) {
+                    registry.expressionFor(member.response.body);
+                }
+                switch (member.serving) {
+                    case "none":
+                        return undefined;
+                    case "stream":
+                        streams = true;
+                        return "ByteStream";
+                    case "binary":
+                        streams = true;
+                        return "ByteStream | Uint8Array<ArrayBuffer> | ArrayBuffer";
+                    case "unvalidated":
+                        return "string";
+                    default: {
+                        if (member.response.body === undefined)
+                            return undefined;
+                        const ref = registry.expressionFor(member.response.body);
+                        bodyRefs.push(ref);
+                        return `Produced<${ref}>`;
+                    }
+                }
+            };
+            const members = resultMembersOf(responses, hasBody).map((member) => {
+                const body = bodyOf(member);
+                const codes = statusCodesOf(member.response, responses, hasBody);
+                const fields = [`readonly status: ${codes.length === 0 ? "never" : codes.join(" | ")}`];
+                if (member.choosesMediaType && member.mediaType !== undefined) {
+                    fields.push(`readonly contentType: ${mediaTypeTypeOf(member.mediaType)}`);
+                }
+                fields.push(body === undefined ? "readonly body?: undefined" : `readonly body: ${body}`);
+                const headers = member.response.headers;
+                if (headers.length > 0) {
+                    /**
+                     * Keyed by the WIRE name, as the document publishes it. `headers` is optional only when
+                     * every header in it is, and an optional header admits an explicit `undefined`, because
+                     * a server drops one before it checks and sends the rest.
+                     */
+                    const every = headers.every(({ property }) => property.optional);
+                    const rendered = headers
+                        .map(({ name, property }) => property.optional
+                        ? `readonly ${objectKey(name)}?: ${propertyTypeToTs(program, property)} | undefined`
+                        : `readonly ${objectKey(name)}: ${propertyTypeToTs(program, property)}`)
+                        .join("; ");
+                    fields.push(`readonly headers${every ? "?" : ""}: { ${rendered} }`);
+                }
+                return { member, body, text: `{ ${fields.join("; ")} }` };
+            });
+            /**
+             * A success is a `2xx` or `3xx` outcome, exact or ranged, as {@link successStatusesOf} holds.
+             * `default` is not one: it is every status nothing else declares, which is mostly failures.
+             */
+            const outputs = [
+                ...new Set(members
+                    .filter(({ member }) => isSuccessStatus(member.response.status))
+                    .map(({ body }) => body ?? "undefined")),
+            ];
             entries.push({
                 operationId: operationIdOf(program, operation.operation),
-                ref: registry.expressionFor(body),
+                output: outputs.length === 0 ? "never" : outputs.join(" | "),
+                result: members.map(({ text }) => text),
+                streams,
+                bodyRefs,
             });
         }
     });
     return entries;
 }
+/** A `2xx` or `3xx` status, exact or as a range: an outcome a handler returns rather than a failure. */
+function isSuccessStatus(status) {
+    if (typeof status === "number")
+        return status >= 200 && status < 400;
+    return status === "2XX" || status === "3XX";
+}
+/**
+ * **A stream of bytes, spelled as the reader every stream has rather than as `ReadableStream`.**
+ *
+ * The server hands a binary request body over unread, so the contract has to say "stream" - a
+ * contract saying `ArrayBuffer` made a gateway read a 25 MiB upload into an isolate just to satisfy
+ * a backend's type. But `requests.gen.ts` is framework-free, and a contracts package compiled under
+ * `lib: ["ES2024"]` and no `types` cannot name `ReadableStream` at all (`TS2304`); only lib.dom,
+ * lib.webworker, `@cloudflare/workers-types` and `@types/node` declare it.
+ *
+ * **This is the part of a stream every one of those declares, and nothing else.** Measured: a platform
+ * `ReadableStream<Uint8Array> | null` is assignable to it under the default libs, lib.dom,
+ * lib.webworker, workers-types and `@types/node`, on TypeScript 5.9.3 and 7.0.2, while an
+ * `ArrayBuffer` is refused. `AsyncIterable<Uint8Array>`, the obvious alternative, is NOT satisfied
+ * by lib.dom's stream on TypeScript 5.9 unless `dom.asynciterable` is also listed - which the usual
+ * `["ES2020", "DOM", "DOM.Iterable"]` does not.
+ *
+ * The same precedent as a multipart file part: a type only an ambient library declares is spelled
+ * structurally, so the emitted output compiles wherever it lands.
+ */
+const BYTE_STREAM = `
+/**
+ * A stream of bytes, as every platform's \`ReadableStream<Uint8Array>\` satisfies it - spelled
+ * structurally so this file needs no DOM or runtime library to name it.
+ */
+export interface ByteStream {
+	getReader(): {
+		read(): Promise<{ readonly done: boolean; readonly value?: Uint8Array | undefined }>;
+		releaseLock(): void;
+		cancel?(reason?: unknown): Promise<void>;
+	};
+}
+`;
 /**
  * `requests.gen.ts` - the shape both sides are checked against.
  *
@@ -1861,29 +2246,29 @@ function renderRequestTypes(entries, responses, registry) {
             ? `\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`);
-    });
+    const responseLookup = responses
+        .map((entry) => `\t/** Every success body \`${entry.operationId}\` declares. */\n\t${entry.operationId}: ${entry.output};`)
+        .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.
+     * **One member per declared response and media type, each pairing a status with its own body.**
+     * The union a server emitter's handlers return, stated with nothing to import: a backend reached
+     * over a service binding returns `WireResults[op]`, and a handler can hand it straight on.
      */
-    const responseLookup = responses
-        .map((entry) => `\t${entry.operationId}: Produced<${entry.ref}>;`)
+    const resultLookup = responses
+        .map((entry) => `\t/** Every response \`${entry.operationId}\` declares. */\n\t${entry.operationId}:${entry.result.length === 0 ? " never" : entry.result.map((member) => `\n\t\t| ${member}`).join("")};`)
         .join("\n");
+    /**
+     * **Keyed by operation id, and the only name an operation's input has.**
+     *
+     * Each input used to be declared a second time as an alias, `CreateUserInput` for `createUser`,
+     * and this lookup referenced the aliases. That is a name a spec may well give its own request
+     * model, so the two declarations collided (`TS2300`) and `requests.gen.ts` did not
+     * compile for an operation as ordinary as `createUser(@body body: CreateUserInput)`. A type
+     * exported under a name this emitter invents is a name a spec author can already be using.
+     * `WireInputs["createUser"]` is the same type, and nothing a spec declares can collide with it.
+     */
     const lookup = entries
-        .map((entry) => `\t${entry.operationId}: ${upperFirst(entry.operationId)}Input;`)
+        .map((entry) => `\t/** The input for \`${entry.operationId}\`, as its handler receives it. */\n\t${entry.operationId}: ${entry.input.replaceAll("\n", "\n\t")};`)
         .join("\n");
     /**
      * **Emitted only where an operation has something to flatten.**
@@ -1895,9 +2280,9 @@ function renderRequestTypes(entries, responses, registry) {
      * `TS6196: 'Simplify' is declared but never used.` Third of its kind, after the unconditional
      * `zValidator` and `z` imports.
      *
-     * Decided from the aliases actually rendered rather than by searching the output for the name.
+     * Decided from the inputs actually rendered rather than by searching the output for the name.
      */
-    const simplifyHelper = inputs.length === 0
+    const simplifyHelper = !entries.some((entry) => entry.input.startsWith("Simplify<"))
         ? ""
         : `/**
  * Flattens an intersection into a single object type.
@@ -1933,14 +2318,19 @@ export type Produced<T> = T extends readonly (infer 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. */
+${entries.some((entry) => entry.streamsBody) || responses.some((entry) => entry.streams) ? BYTE_STREAM : ""}${declarations.join("")}
+/**
+ * Every operation's input, keyed by operation id: what its handler receives, and what a caller of a
+ * backend typed by it hands over. An operation that takes nothing is \`Record<string, never>\`.
+ */
 export interface WireInputs {
 ${lookup}
 }
 
 /**
- * Every operation's success response, keyed by operation id.
+ * Every operation's success bodies, keyed by operation id: the body of each \`2xx\` and \`3xx\` response it
+ * declares, \`undefined\` for one with no body, and \`never\` where it declares no success at all. Which
+ * status goes with which body is \`WireResults\`.
  *
  * **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
@@ -1950,6 +2340,15 @@ ${lookup}
 export interface WireOutputs {
 ${responseLookup}
 }
+
+/**
+ * Every operation's result, keyed by operation id: one member per response it declares, each pairing
+ * a status with that status's body and headers. A status no response declares does not compile, and
+ * a \`4XX\` or \`default\` response is the codes it stands for, written out.
+ */
+export interface WireResults {
+${resultLookup}
+}
 `;
 }
 /**
@@ -1987,16 +2386,25 @@ ${responseLookup}
  * `Equals` here, not assignability: the two describe one shape, and a property present on one side
  * and absent from the other is exactly the drift this exists to catch.
  */
-function renderWireAssertions(schemas, types, entries, contractsPackage) {
+function renderWireAssertions(schemas, types, entries, responses, 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));
+    /**
+     * **Every model a body names, the responses' as well as the requests'.** This paired request
+     * bodies only, so a model that is only ever SENT was compared with nothing; that was harmless
+     * while the contract types described a single success body and nothing consumed it, and is not now
+     * that `WireResults` states every response a backend returns.
+     */
+    const bodyModels = new Set([
+        ...entries.map((entry) => entry.bodyRef).filter((ref) => ref !== undefined),
+        ...responses.flatMap((entry) => entry.bodyRefs),
+    ]);
     const paired = [];
     for (const declaration of types.declarations()) {
-        if (!requestModels.has(declaration.name))
+        if (!bodyModels.has(declaration.name))
             continue;
         const schema = schemas
             .declarations()
@@ -2057,26 +2465,6 @@ type Identical<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends
  * dropped from a shape that has other keys, and kept - with its value type still mapped - from one
  * that does not.
  */
-/**
- * \u26a0\ufe0f **An optional property is \`?: T\` here and \`?: T | undefined\` in the contract type, and that is
- * deliberate on both sides.**
- *
- * The validator emits \`.exactOptional()\`, so what ARRIVES is absent or a value - JSON cannot carry an
- * \`undefined\` and the document says exactly that by leaving the property out of \`required\`. The
- * contract type is the floor a PRODUCER supplies, and \`{ p: undefined }\` serialises identically to
- * omitting \`p\`, so refusing it would cost every producer a conditional spread and buy the wire
- * nothing. Narrowing THAT surface was tried in \`0.19.0\` and reverted: it broke
- * \`(ctx, input) => ok(input)\`.
- *
- * So the two disagree on exactly one axis, on purpose, and this widens the inferred side to the
- * producer floor before comparing - the same job \`Declared\` does for openness, in the same pass
- * rather than a second deep one. Every other kind of drift still fails: a property that changes type,
- * appears, disappears or changes optionality is untouched by this.
- */
-type Supplied<T, K extends keyof T> = {} extends Pick<T, K>
-	? Declared<T[K]> | undefined
-	: Declared<T[K]>;
-
 type DeclaredKeyOf<T> = keyof {
 	[K in keyof T as string extends K
 		? never
@@ -2105,9 +2493,8 @@ type Declared<T> = T extends (...args: never[]) => unknown
 						// equate a real dictionary with an empty object: a dictionary whose values are
 						// \`never\` accepts nothing either.
 						{}
-					: // A shape with no declared keys is a dictionary: it has no optional property to
-						// widen, and an index signature satisfies \`{} extends Pick<T, K>\` for every
-						// value type.
+					: // A shape with no declared keys is a dictionary: its index signature is kept and
+						// its value type mapped.
 						{ [K in keyof T]: Declared<T[K]> }
 				: {
 						[K in keyof T as string extends K
@@ -2116,13 +2503,13 @@ type Declared<T> = T extends (...args: never[]) => unknown
 								? never
 								: symbol extends K
 									? never
-									: K]: Supplied<T, K>;
+									: K]: Declared<T[K]>;
 					}
 			: T;
 
 /**
- * \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
+ * **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 - 66 assertions that
  * assert nothing. Only a constraint violation is an error.
  */
 type MustHold<T extends true> = T;
@@ -2251,6 +2638,8 @@ export async function emitHttpZod(context) {
      * there means a server emitter follows without knowing this rule exists.
      */
     const distinctServices = new Set(snapshots.map((snapshot) => snapshot.service.namespace.name));
+    /** The services writing to the top-level `contracts-output-dir`: every one not naming its own. */
+    const sharingContracts = [...distinctServices].filter((name) => options.services?.[name]?.["contracts-output-dir"] === undefined);
     /**
      * **Every service must seal the same way, because `@typespec/openapi3` has no per-service
      * options.**
@@ -2295,8 +2684,22 @@ export async function emitHttpZod(context) {
             (distinctServices.size > 1
                 ? resolvePath(context.emitterOutputDir, serviceName)
                 : context.emitterOutputDir);
+        /**
+         * **Split where two services would write one file, and nowhere else.** A shared contracts
+         * directory was written once per service to one path, so the second service's
+         * `requests.gen.ts` replaced the first's and a whole surface lost its contracts with no
+         * diagnostic. Counted over the services that WRITE there: one service falling back to the
+         * shared directory, beside others that name their own, collides with nothing, and splitting
+         * it moved contracts a project already imported. A relative `contracts-package` is resolved
+         * from each service's own `wire-contract.gen.ts`, so it names that service's contracts; a
+         * package specifier has to be set per service.
+         */
+        const sharedContractsDir = options["contracts-output-dir"];
         const resolved = {
-            contractsOutputDir: perService?.["contracts-output-dir"] ?? options["contracts-output-dir"],
+            contractsOutputDir: perService?.["contracts-output-dir"] ??
+                (sharedContractsDir !== undefined && sharingContracts.length > 1
+                    ? resolvePath(sharedContractsDir, serviceName)
+                    : sharedContractsDir),
             contractsPackage: perService?.["contracts-package"] ?? options["contracts-package"],
             sealObjectSchemas: perService?.["seal-object-schemas"] ?? options["seal-object-schemas"] ?? false,
             compileSchemas: perService?.["compile-schemas"] ?? options["compile-schemas"] ?? false,
@@ -2362,8 +2765,15 @@ export async function emitHttpZod(context) {
         });
         if (resolved.contractsOutputDir !== undefined) {
             const types = new TypeRegistry(context.program);
-            const entries = collectRequestTypes(context.program, types, service);
-            const responses = collectResponseTypes(context.program, types, service);
+            /**
+             * **Inside the same stream scope as the route walk**, because both read the same response
+             * records: outside it `streamedTypeOf` cannot see `@typespec/streams`, so an SSE body was
+             * stated as the string the document describes rather than the stream a server sends.
+             */
+            const { entries, responses } = withStreamModule(streamModule, () => ({
+                entries: collectRequestTypes(context.program, types, service),
+                responses: collectResponseTypes(context.program, types, service),
+            }));
             await emitFile(context.program, {
                 path: resolvePath(resolved.contractsOutputDir, "requests.gen.ts"),
                 content: renderRequestTypes(entries, responses, types),
@@ -2372,7 +2782,7 @@ export async function emitHttpZod(context) {
                 path: resolvePath(resolved.contractsOutputDir, "vocabularies.gen.ts"),
                 content: renderVocabularies(vocabularies),
             });
-            const assertions = renderWireAssertions(registry, types, entries, resolved.contractsPackage);
+            const assertions = renderWireAssertions(registry, types, entries, responses, resolved.contractsPackage);
             if (assertions !== undefined) {
                 await emitFile(context.program, {
                     path: resolvePath(outputDir, "wire-contract.gen.ts"),
@@ -2380,7 +2790,12 @@ export async function emitHttpZod(context) {
                 });
             }
         }
-        emitted.push({ service, routes, schemaNames: names, outputDir, options: resolved });
+        // Still inside this service's id scope, so each operation resolves to the id its route carries.
+        const operations = new Map(service.operations.map((operation) => [
+            operationIdOf(context.program, operation.operation),
+            operation,
+        ]));
+        emitted.push({ service, routes, schemaNames: names, operations, outputDir, options: resolved });
     }
     return emitted;
 }