typespec-http-zod 0.30.0 → 0.32.0

package/dist/src/api.js

@@ -1,17 +1,20 @@
-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 { emitFile, getDiscriminatedUnion, getDiscriminator, getDoc, getDocData, getEncode, getLocationContext, getSummary, getTypeName, isErrorModel, isNeverType, isVoidType, navigateProgram, NoTarget, resolvePath, } from "@typespec/compiler";
+import { getAuthenticationForOperation, getVisibilitySuffix, isOrExtendsHttpFile, Visibility, } from "@typespec/http";
 import { getOperationId, resolveOperationId } from "@typespec/openapi";
+import { firstReportOf } from "./constraints.js";
 import { reportDiagnostic } from "./lib.js";
+import { openApiVersionsOf, publishesOpenApi30AndLater } from "./openapi-versions.js";
 import { literal } from "./literal.js";
-import { SchemaRegistry, TypeRegistry } from "./registry.js";
+import { beginServiceView, parameterVisibilityOf, publishedComponents, publishedTypes, requestVisibilityOf, unreachedTypes, withServiceView, } from "./published.js";
+import { isSingleObjectLiteral, SchemaRegistry, TypeRegistry } from "./registry.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 { EXPLODED_QUERY_SOURCE, explodedQueryCall, eachReader, NO_READERS, needsExpansionDecoding, routeTemplateOf, URI_EXPANSION_SOURCE, uriExpansionCall, WIRE_READ_OBJECT_SOURCE, WIRE_READ_AS_SOURCE, WIRE_READ_SOURCE, WIRE_ITSELF_SOURCE, WIRE_READERS_SOURCE, wireItselfCall, wireReadObjectCall, } from "./uri-template.js";
 export { CONTENTLESS_STATUS_CODES, STATUS_CODES } from "./statuses.js";
 export { isJsonMediaType, isMediaRange, isTextualMediaType, mediaTypeEssenceOf, mediaTypeTypeOf, resultMembersOf, statusCodesOf, } from "./results.js";
-import { collectExternalImports, encodedTypeOf, isPayloadProperty, noteDeclaredVocabularies, noteKeyVocabularies, objectKey, wireKindOf, withContractsPackage, withSealedObjects, withVisibility, } from "./zod.js";
+import { collectExternalImports, encodedTypeOf, externalReferenceOf, holdsRawBytes, isExclusive, isTypelessMember, nullableInnerOf, noteDeclaredVocabularies, noteKeyVocabularies, objectKey, objectOfModel, reachesItselfThroughUnions, refuseExternalReference, refuseSelfReachingUnion, atItem, bindingIndexerOf, currentVisibility, dispatchedSubtypesOf, readsFromText, renderedVisibilityOf, rootVisibilityOf, withContractsPackage, withSealedObjects, withMetadataAnnotationsIgnored, requiredReadOnlyIn, reportUnpublishable, withRequestReading, withMultipartBinary, withParameterPosition, UNREPRESENTABLE, 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.
@@ -322,15 +325,18 @@ function resolveResponses(program, operation) {
             const entry = byStatus.get(key) ?? {
                 status,
                 body: undefined,
+                ignoresMetadata: false,
                 contentTypes: new Set(),
                 headers: [],
                 streamed: false,
                 file: false,
             };
             for (const content of response.responses) {
+                reportNeverBody(program, operation, content.body, `${key} response`);
                 const body = presentBody(content.body);
                 if (entry.body === undefined && body?.bodyKind === "single") {
                     entry.body = body.type;
+                    entry.ignoresMetadata = ignoresMetadata(body);
                 }
                 /**
                  * **An `Http.File` response's body is its contents, served as bytes.** The same reading
@@ -360,11 +366,12 @@ function resolveResponses(program, operation) {
         return {
             status: entry.status,
             body: entry.body,
+            ignoresMetadata: entry.ignoresMetadata,
             contentTypes,
             headers: entry.headers,
             binary: entry.file ||
                 (entry.body !== undefined &&
-                    isBinaryPart(entry.body) &&
+                    isBinaryPart(program, entry.body) &&
                     isRawBinaryMediaType(contentTypes)),
             streamed: entry.streamed,
             textual: !entry.file && entry.body !== undefined && isStringType(entry.body),
@@ -376,13 +383,17 @@ function inPrecedenceOrder(responses) {
     return responses.toSorted((a, b) => statusPrecedenceOf(a.status) - statusPrecedenceOf(b.status) ||
         statusOrderOf(a.status) - statusOrderOf(b.status));
 }
+/** A response header's contract type: a header, as a parameter is - see `withParameterPosition`. */
+function headerTypeOf(program, property) {
+    return withParameterPosition(true, () => propertyTypeToTs(program, property));
+}
 /**
  * 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
+ * Call inside `withVisibility(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) {
@@ -396,7 +407,7 @@ function responsesOf(program, operation, registry) {
              * 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),
+            type: headerTypeOf(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
@@ -414,7 +425,7 @@ function responsesOf(program, operation, registry) {
             ? undefined
             : response.binary
                 ? "z.unknown()"
-                : registry.expressionFor(response.body),
+                : withMetadataAnnotationsIgnored(response.ignoresMetadata, () => registry.expressionFor(response.body, true)),
         contentTypes: response.contentTypes,
         headers,
         binary: response.binary,
@@ -607,6 +618,54 @@ export function errorBodyOf(program, service) {
 function bodyTypeOf(type) {
     return isVoidType(type) || isNeverType(type) ? undefined : type;
 }
+/**
+ * **A body declared `never` is refused**, as `never-body`, once per declaration.
+ *
+ * `never` has no values, so the body cannot exist - and `@typespec/openapi3`, whose body paths test
+ * only for `void`, publishes it as `content: { "application/json": { schema: {} } }`: any value. A
+ * validator can agree with that or with the spec, not both, so the declaration is refused the way
+ * `undeclared-discriminator` refuses a discriminator the document cannot state. `void` says "no
+ * body", and openapi3 publishes it as none.
+ */
+/**
+ * **A request holding a required read-only property, where openapi3 publishes 3.0 and a later
+ * version** - see `ambiguous-read-only`. The 3.0 document lets the request leave it out and the later
+ * one does not, so no request validator agrees with both.
+ */
+function reportAmbiguousReadOnly(program, type, requested) {
+    if (!publishesOpenApi30AndLater(program))
+        return;
+    const property = requiredReadOnlyIn(program, type, rootVisibilityOf(program, type, requested), new Set());
+    if (property === undefined || !firstReportOf(program, "ambiguous-read-only", type))
+        return;
+    reportDiagnostic(program, {
+        code: "ambiguous-read-only",
+        target: type,
+        format: {
+            type: getTypeName(type),
+            property: property.model === undefined
+                ? property.name
+                : `${getTypeName(property.model)}.${property.name}`,
+            later: openApiVersionsOf(program)
+                .filter((version) => !version.startsWith("3.0."))
+                .map((version) => `OpenAPI ${version}`)
+                .join(" and "),
+            view: `${getVisibilitySuffix(requested, Visibility.Read)}<${getTypeName(property.model ?? type)}>`,
+        },
+    });
+}
+function reportNeverBody(program, operation, body, position) {
+    if (body?.bodyKind !== "single" || !isNeverType(body.type))
+        return;
+    const target = body.property ?? operation.operation;
+    if (!firstReportOf(program, "never-body", target))
+        return;
+    reportDiagnostic(program, {
+        code: "never-body",
+        target,
+        format: { operationId: operationIdOf(program, operation.operation), position },
+    });
+}
 /**
  * A declared body as the wire carries it: `undefined` where it is `void` or `never`, so no media
  * type is listed for it either.
@@ -616,9 +675,8 @@ function bodyTypeOf(type) {
  * the media types off it, so a 409 with no body was published as `contentTypes:
  * ["application/json"]` and `schema: undefined`, which a consumer reads as a body it cannot validate,
  * and a `void` request body reached the Zod walk and refused the compile. openapi3 publishes no
- * `content` for `void`. For `never` it publishes `schema: {}` - any value - because its body paths
- * test only for `void`, while it omits a `never` PROPERTY from every schema; a type with no values is
- * no body here, and `reference.md` records the divergence.
+ * `content` for `void`. A `never` body is refused, as `never-body`, so no artefact states a body the
+ * document publishes as any value; see {@link reportNeverBody}.
  */
 function presentBody(body) {
     return body?.bodyKind === "single" && bodyTypeOf(body.type) === undefined ? undefined : body;
@@ -627,6 +685,19 @@ function presentBody(body) {
 function requestBodyParameterOf(operation) {
     return presentBody(operation.parameters.body);
 }
+/**
+ * **The operation's parameters as the document publishes them: every one but a `never`.** openapi3
+ * leaves a parameter of type `never` out of the operation (`getParameterOrRef`), required or not and
+ * wherever it is, so `?a=1` beside `@query a?: never` is an extra parameter the document accepts.
+ * Read whole, each was validated as `z.never()`, which refused it, was typed `a?: never` in the
+ * handler's input, and was reported as `unsupported-type` at `<unknown location>:1:1` under a remedy
+ * saying a `never` could not get there. A `never` body property is dropped the same way - see
+ * `publishedPropertiesOf`. A `never` sharing its wire name with another parameter leaves the name
+ * to that one, which is the one the document publishes.
+ */
+function publishedParametersOf(operation) {
+    return operation.parameters.parameters.filter((parameter) => !isNeverType(parameter.param.type));
+}
 /**
  * The media types this operation's success response can be served as.
  *
@@ -661,18 +732,21 @@ function responseContentTypesOf(operation, status) {
  * expanded reads this type, so none of them can disagree with the schema it feeds.
  */
 function encodedParameterType(program, property) {
-    return encodedTypeOf(program, property) ?? property.type;
+    const type = encodedTypeOf(program, property) ?? property.type;
+    /**
+     * **A parameter cannot carry `null` on the wire, so `T | null` arrives as a `T`.** Read as the
+     * union, `?ids=1,2` for `ids?: int32[] | null` was never split or decoded, and a form-exploded
+     * `filter?: Filter | null` was never gathered, so its keys were stripped.
+     */
+    return nullableInnerOf(type) ?? type;
 }
 /**
- * The wire kind of an ARRAY parameter's elements, or `undefined` where it is not such an array.
+ * An ARRAY parameter's element type, or `undefined` where it is not such an array.
  *
- * `?ids=1,2,3` splits into strings, so each element needs the same decoding a lone scalar would.
+ * `?ids=1,2,3` splits into strings, so each element is read from text as a lone scalar is.
  */
-function elementKindOf(program, type) {
-    if (!isArrayType(type) || type.kind !== "Model")
-        return undefined;
-    const element = type.indexer?.value;
-    return element === undefined ? undefined : wireKindOf(program, element);
+function elementOf(type) {
+    return isArrayType(type) && type.kind === "Model" ? type.indexer?.value : undefined;
 }
 /** Whether a type is an array - TypeSpec models one as a `Model` carrying an integer indexer. */
 function isArrayType(type) {
@@ -708,25 +782,42 @@ function isArrayType(type) {
  * {@link multipartSchemaOf} part for part, including `multi` as an array, `optional`, and a binary
  * part as `unknown`, is what makes the two agree by construction rather than by coincidence.
  */
-function multipartTsOf(body, registry) {
+function multipartTsOf(program, body, registry) {
     const entries = body.parts.map((part) => {
         const type = part.body?.type;
         const inner = type === undefined
             ? "unknown"
-            : isFilePart(type)
+            : isFilePart(program, type)
                 ? MULTIPART_FILE
-                : isBinaryPart(type)
+                : isBinaryPart(program, type)
                     ? "unknown"
-                    : registry.expressionFor(type);
+                    : withMetadataAnnotationsIgnored(ignoresMetadata(part.body), () => withMultipartBinary(holdsRawBytes(program, type), () => registry.expressionFor(type, true)));
         const value = part.multi === true ? `(${inner})[]` : inner;
         const optional = part.optional === true ? "?" : "";
         return `\t${objectKey(part.name ?? "")}${optional}: ${value};`;
     });
-    return entries.length === 0 ? "{}" : `{\n${entries.join("\n")}\n}`;
+    const shape = entries.length === 0 ? "{}" : `{\n${entries.join("\n")}\n}`;
+    // Declared under the component's name, as its validator is - see `multipartSchemaOf`.
+    const name = multipartNameOf(body);
+    return name === undefined || body.type === undefined
+        ? shape
+        : registry.declareNamed(name, () => shape, body.type);
+}
+/** The component openapi3 publishes a multipart body as: its model's name, where it has one. */
+function multipartNameOf(body) {
+    const named = body.type;
+    return named !== undefined && named.kind === "Model" && named.name !== ""
+        ? named.name
+        : undefined;
 }
 function multipartSchemaOf(program, body, registry) {
     const entries = body.parts.map((part) => {
         const type = part.body?.type;
+        // `.exactOptional()` for the same reason as a model property: `parseBody` yields present keys
+        // only, so an absent part is an absent key rather than an explicit `undefined`.
+        const entry = (value) => `\t${objectKey(part.name ?? "")}: ${part.optional === true ? `${value}.exactOptional()` : value},`;
+        if (isJsonListPart(program, part))
+            return entry(jsonListDecoded(jsonListOf(registry, part)));
         /**
          * **A form carries text, so a part that means a number or a boolean is decoded first**, by the
          * same rule {@link wireDecoded} applies to path, query and header values: `"0.5"` becomes
@@ -737,18 +828,31 @@ function multipartSchemaOf(program, body, registry) {
          */
         const inner = type === undefined
             ? "z.unknown()"
-            : isFilePart(type)
+            : isFilePart(program, type)
                 ? `z.unknown().refine(${MULTIPART_FILE_REFINEMENT})`
-                : isBinaryPart(type)
+                : isBinaryPart(program, type)
                     ? "z.unknown()"
-                    : isJsonPart(part)
-                        ? jsonTextDecoded(registry.expressionFor(type))
-                        : wireDecoded(registry.expressionFor(type), wireKindOf(program, type), elementKindOf(program, type));
-        // `multi` is `HttpPart<T>[]` - the same part repeated, which arrives as an array.
-        const value = part.multi === true ? `z.array(${inner})` : inner;
-        // `.exactOptional()` for the same reason as a model property: `parseBody` yields present keys
-        // only, so an absent part is an absent key rather than an explicit `undefined`.
-        return `\t${objectKey(part.name ?? "")}: ${part.optional === true ? `${value}.exactOptional()` : value},`;
+                    : holdsRawBytes(program, type)
+                        ? /**
+                             * Any value but what its other members refuse, and no text to read - unless the
+                             * document publishes the part as JSON alone, `HttpPart<bytes | null>`, where its
+                             * text is JSON and `x` is refused.
+                             */
+                            withMultipartBinary(true, () => isJsonPart(part)
+                                ? jsonTextDecoded(registry.expressionFor(type, true))
+                                : registry.expressionFor(type, true))
+                        : withMetadataAnnotationsIgnored(ignoresMetadata(part.body), () => isJsonPart(part)
+                            ? jsonTextDecoded(registry.expressionFor(type, true))
+                            : isJsonOrTextPart(part)
+                                ? jsonOrTextDecoded(registry.expressionFor(type, true), textPartDecoded(program, registry, type))
+                                : textPartDecoded(program, registry, type));
+        if (part.multi !== true)
+            return entry(inner);
+        // `multi` is `HttpPart<T>[]` - the same part repeated, which the document publishes as a list,
+        // and one whose text may be JSON is that list in JSON as well - see `mayBeJsonList`.
+        return entry(isJsonOrTextPart(part)
+            ? jsonOrTextDecoded(jsonListOf(registry, part), `z.array(${inner})`)
+            : `z.array(${inner})`);
     });
     const shape = entries.length === 0 ? "z.object({})" : `z.object({\n${entries.join("\n")}\n})`;
     /**
@@ -756,9 +860,124 @@ function multipartSchemaOf(program, body, registry) {
      * for it. Emitted inline the schema is correct and the component still has no validator, which the
      * differential reports - rightly - as a contract the runtime cannot check.
      */
-    const named = body.type;
-    const name = named !== undefined && named.kind === "Model" && named.name !== "" ? named.name : undefined;
-    return name === undefined ? shape : registry.declareNamed(name, () => shape);
+    const name = multipartNameOf(body);
+    return name === undefined || body.type === undefined
+        ? shape
+        : registry.declareNamed(name, () => shape, body.type);
+}
+/**
+ * **What a text part's value is read as: never `null`, which text does not spell**, so `T | null`
+ * is read as a `T`, as a parameter's is - see `encodedParameterType`. Read as the union, `h=1&h=2`
+ * for `int32[] | null` under `text/plain` reached `z.array(z.int32())` as `["1", "2"]` unread, and
+ * was refused where the document reads `[1, 2]`.
+ */
+function asText(type) {
+    return nullableInnerOf(type) ?? type;
+}
+/** The parts read from text - see {@link EmittedRoute.textParts}. */
+function textPartsOf(program, body) {
+    return body.parts.flatMap((part) => {
+        const type = part.body?.type;
+        if (part.name === undefined || type === undefined)
+            return [];
+        if (isFilePart(program, type) || isBinaryPart(program, type) || holdsRawBytes(program, type)) {
+            return [];
+        }
+        return [{ name: part.name, json: isJsonPart(part) }];
+    });
+}
+/**
+ * **A text part of a union holding a list is one value, or several sent as as many parts**, read as a
+ * URL-encoded form's field is - see `readerOf`: `int32 | int32[]` under `text/plain` is `5` sent
+ * once and `[1, 2]` sent as `1` and `2`, and `int32 | string[]` reads a lone `a` as the list `["a"]`.
+ * Read against the whole union, as one text is, the parts reached it unread and were refused where
+ * the document reads `[1, 2]`. Rendered as a part's schema is, where a parameter's refuses a tuple.
+ */
+function textPartDecoded(program, registry, type) {
+    const declared = registry.expressionFor(type, true);
+    const inner = asText(type);
+    const forms = inner.kind === "Union" ? wireFormsOf(inner) : [];
+    const lists = forms.filter((each) => elementOf(each) !== undefined);
+    if (lists.length === 0)
+        return wireDecoded(program, registry, declared, inner);
+    const each = lists.map((list) => atItem(program, list, () => registry.expressionFor(elementOf(list), true)));
+    const one = forms.some((form) => elementOf(form) === undefined) ? declared : undefined;
+    return `z.preprocess((raw) => wireReadAs(raw, ${eachReader(each, one, declared)}), ${declared})`;
+}
+/**
+ * **A part the document publishes as a list under a media type that is not JSON alone is that many
+ * parts**, one per element, however the spec declared it: `HttpPart<{ @header contentType:
+ * "text/plain"; @body body: int32[] }>` is published exactly as `HttpPart<int32>[]` is, `{ type:
+ * array, items: int32 }` with `contentType: text/plain`, and text spells no list. Read as one part,
+ * a lone `5` reached `z.array` as `"5"` and was refused, where the same part declared repeated read
+ * it as `[5]`. A JSON part's text may spell the whole list as well - see {@link isJsonListPart}.
+ */
+function repeatsAsText(part) {
+    const type = part.body?.type;
+    return (part.multi !== true &&
+        type !== undefined &&
+        !isJsonPart(part) &&
+        isArrayType(nullableInnerOf(type) ?? type));
+}
+/**
+ * **A JSON part the document publishes as a list is one list or its elements, however it is
+ * declared.** `HttpPart<int32[]>` and `HttpPart<{ @header contentType: "application/json"; @body
+ * body: int32 }>[]` are published alike, `{ type: array, items: int32 }` with `contentType:
+ * application/json`, and OAS 3.1 does not say whether such a part is sent once, as the list's JSON,
+ * or once per element, each element's. So the document admits both: `[1,2]` is the list, and `5`,
+ * or `1` and `2` sent as two parts, its elements. Read as declared, the first refused `5` and the
+ * two parts, and the second `[1,2]`. A file or raw bytes is no JSON to read.
+ */
+function isJsonListPart(program, part) {
+    const type = part.body?.type;
+    return (type !== undefined &&
+        isJsonPart(part) &&
+        !isFilePart(program, type) &&
+        !isBinaryPart(program, type) &&
+        !holdsRawBytes(program, type) &&
+        (part.multi === true || isArrayType(nullableInnerOf(type) ?? type)));
+}
+/**
+ * Whether one text of a part the document publishes as a list may be the whole list in JSON: a JSON
+ * list part, or one that is text or JSON, published as a list - declared repeated, or as a list under
+ * a media type that is not JSON alone. See {@link isJsonListPart} and {@link repeatsAsText}.
+ */
+function mayBeJsonList(program, part) {
+    return (isJsonListPart(program, part) ||
+        (isJsonOrTextPart(part) && (part.multi === true || repeatsAsText(part))));
+}
+/** The schema of the list a part is published as, read from JSON: a repeated part's, its elements'. */
+function jsonListOf(registry, part) {
+    const declared = withMetadataAnnotationsIgnored(ignoresMetadata(part.body), () => registry.expressionFor(part.body.type, true));
+    return part.multi === true ? `z.array(${declared})` : declared;
+}
+/**
+ * **A repeated part sent once is the one-element list the document describes**, and a form hands it
+ * over as the one value: `parseBody({ all: true })` makes a list only of a repeated key, so one file
+ * sent to a multi-file field reached `z.array` as a file and was refused. Boxed for the request
+ * only - the component stays the document's schema, where a lone value is no list - and only what a
+ * form delivers for one part, text or a file, so a value no form sends is judged as it is.
+ *
+ * A part repeats where the document says it does: declared `HttpPart<T>[]`, or published as a list
+ * under a text media type - see {@link repeatsAsText}. **One whose text may be JSON is boxed only
+ * where its text is not the JSON list the part accepts** - see {@link mayBeJsonList}: `[1,2]` is
+ * that list, and `5` the one element.
+ */
+function multipartRequestOf(program, registry, body, schema) {
+    const named = body.parts.filter((part) => part.name !== undefined);
+    const jsonOrText = named.filter((part) => mayBeJsonList(program, part));
+    const boxed = named.filter((part) => !mayBeJsonList(program, part) && (part.multi === true || repeatsAsText(part)));
+    if (boxed.length === 0 && jsonOrText.length === 0)
+        return schema;
+    const one = `typeof value === "string" || (value !== null && typeof value === "object" && !Array.isArray(value) && "arrayBuffer" in value)`;
+    const always = boxed.length === 0
+        ? ""
+        : ` for (const key of ${literal(boxed.map((part) => part.name))}) { const value = boxed[key]; if (${one}) boxed[key] = [value]; }`;
+    const lists = jsonOrText.map((part) => `[${literal(part.name)}, ${jsonListOf(registry, part)}]`);
+    const unlessJson = lists.length === 0
+        ? ""
+        : ` for (const [key, list] of [${lists.join(", ")}] as const) { const value = boxed[key]; if (typeof value === "string") { try { if (list.safeParse(JSON.parse(value)).success) continue; } catch { /* text, one element */ } } if (${one}) boxed[key] = [value]; }`;
+    return `z.preprocess((raw) => { if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return raw; const boxed: globalThis.Record<string, unknown> = { ...raw };${always}${unlessJson} return boxed; }, ${schema})`;
 }
 /**
  * The shape a multipart file part actually arrives as, spelled structurally.
@@ -773,7 +992,7 @@ function multipartSchemaOf(program, body, registry) {
  * of the wire assertion, and a mapped type turns a method into a function-typed property, so
  * spelling it this way on both sides is what keeps the two identical.
  */
-const MULTIPART_FILE = "{ name: string; type: string; arrayBuffer: () => Promise<ArrayBuffer> }";
+const MULTIPART_FILE = "{ name: string; type: string; arrayBuffer: () => globalThis.Promise<ArrayBuffer> }";
 /**
  * The check that makes {@link MULTIPART_FILE} established rather than asserted.
  *
@@ -805,14 +1024,9 @@ const MULTIPART_FILE_REFINEMENT = `(value): value is ${MULTIPART_FILE} => typeof
  * string. Widening this to cover `bytes` would refuse payloads that pass today, on an inference the
  * spec never made.
  */
-function isFilePart(type) {
-    if (type.kind !== "Model")
-        return false;
-    for (let model = type; model !== undefined; model = model.baseModel) {
-        if (model.name === "File")
-            return true;
-    }
-    return false;
+function isFilePart(program, type) {
+    // `Http.File` as `@typespec/http` decides it - a spec's own `model File` is a JSON part.
+    return type.kind === "Model" && isOrExtendsHttpFile(program, type);
 }
 /** `bytes`, or a model built on `File` - the parts openapi3 publishes as an empty schema. */
 /**
@@ -833,10 +1047,413 @@ function isJsonPart(part) {
  * string passed on, so a part whose schema admits a string still refuses malformed JSON. A value that
  * is not text is left alone for the schema to judge.
  */
+/**
+ * **A part whose type mixes text with JSON** - `HttpPart<int32 | Address>` - which the document
+ * publishes with `contentType: "text/plain, application/json"`: the client chooses per request, and
+ * the form hands over the text either way. JSON is read where the text is JSON the schema accepts, and
+ * the text is read as text otherwise; read as text alone, `{"city":"x"}` reached `Address` as a
+ * string and was refused. Any JSON value, not an object alone: `"all"`, quoted, is the JSON string
+ * `HttpPart<Nums | "all">` accepts, and ` 1` the number.
+ */
+function isJsonOrTextPart(part) {
+    const contentTypes = part.body?.contentTypes ?? [];
+    const json = (contentType) => /^application\/(?:[\w.+-]+\+)?json$/i.test(contentType);
+    return contentTypes.some(json) && !contentTypes.every(json);
+}
+/**
+ * **A body sent as a URL-encoded form, read from the text it carries** - see
+ * {@link EmittedRoute.formRequestSchema}. A form holds text, `n=5&b=true`, and the document's schema
+ * describes the values it spells, so each field is read against its own schema as a parameter's is,
+ * and a key sent more than once is the list it stands for. `only` where the form is the one media
+ * type the body is declared under. `undefined` where no form is, or nothing in the body reads.
+ *
+ * **Each object the body can be is one reading of the form, and the body's whole schema judges
+ * every reading**, as the document does: it accepts a form where some reading of its text is a value
+ * of the schema it publishes. Read member by member against each member's own schema, a union was
+ * rebuilt here beside the one the document publishes, and only a plain union of models ever was:
+ * `DU` with no envelope, `DU | null`, `{ DA, string }`, `{ PU, DB }` and `DA | DB | DU` were
+ * validated as JSON, so `kind=a&n=5` was refused, "expected number, received string", where the
+ * document reads `{ kind: "a", n: 5 }`. A `@oneOf` judged member by member counted differently too:
+ * `x=5` against `PA { x?: int32 }` and `PB { x?: string }` matched both, each by its own reading, and
+ * was refused where each reading the document takes matches exactly one.
+ */
+function formBodyOf(program, registry, operation, body, type, declared) {
+    const contentTypes = body?.contentTypes ?? [];
+    const form = (contentType) => mediaTypeEssenceOf(contentType) === "application/x-www-form-urlencoded";
+    if (!contentTypes.some(form))
+        return undefined;
+    const only = contentTypes.every(form);
+    const readings = formReadingsOf(program, registry, type);
+    if (!readings.some(readsText))
+        return undefined;
+    const ambiguous = ambiguousFormKeyOf(program, type);
+    if (ambiguous !== undefined) {
+        reportDiagnostic(program, {
+            code: "ambiguous-form-reading",
+            target: ambiguous.target,
+            format: {
+                operation: operation.operation.name,
+                union: getTypeName(ambiguous.union),
+                member: getTypeName(ambiguous.member),
+                other: getTypeName(ambiguous.other),
+                key: ambiguous.key,
+                first: ambiguous.first,
+                second: ambiguous.second,
+            },
+        });
+        return { schema: UNREPRESENTABLE, only };
+    }
+    /**
+     * **A reading that reads nothing is the form as sent, and stays one**: `kind=c&n=5` is a `DC`
+     * whose `n` is a string, and read only as `DA` reads it - `n` the number `5` - it was refused by
+     * `DC | DA`, which accepts it as text.
+     */
+    const read = [
+        ...new Set(readings.map((readers) => readsText(readers) ? `z.preprocess(${wireReadObjectCall(readers)}, ${declared})` : declared)),
+    ];
+    return {
+        schema: read.length === 1 ? read[0] : `z.union([${read.join(", ")}])`,
+        only,
+    };
+}
+/**
+ * **Where a `@oneOf` sent as a URL-encoded form depends on a reading no validator can choose.** The
+ * document accepts a form where some reading of its text matches exactly one member: each key sent
+ * once is a value its text spells - a number, a boolean, the text itself - or the one-element list of
+ * one. A member reads each key as the first of those its schema accepts, and the whole union judges
+ * that reading - see `formBodyOf`. That agrees with the document unless a member reads a key one way
+ * that another member accepts, while accepting another reading the other refuses, and the other's
+ * own reading of the form leaves a rival matching too: then which reading matches one member alone
+ * depends on every other key and member. `x=5` against `M { x?: int32 | string }` and
+ * `N { x?: int32 }` is `{ x: "5" }`, `M` alone, but read as `5` it matched both and was refused;
+ * open, `x=all` against `A { x?: int32 | "all" }` and `B { y?: boolean }` is `{ x: ["all"] }`, `B`
+ * alone. Finding that reading means trying every combination of every key's readings, exponential in
+ * the keys, and a record's keys are the sender's to choose - so the body is refused instead, as
+ * `ambiguous-form-reading`. Where no member tells another's readings apart, or the other's reading
+ * rules every rival out by a key the rival requires - a `kind` literal - some member's reading is
+ * the document's, and the body is validated. See {@link tellsApart}.
+ *
+ * A discriminated union is no such `oneOf`: its members' discriminators differ, so no reading
+ * matches two of them. Nor is a union a form cannot be more than one object of.
+ */
+function ambiguousFormKeyOf(program, type) {
+    const visit = (each, via) => {
+        if (each.kind !== "Union" || via.has(each))
+            return undefined;
+        const members = [...each.variants.values()].map((variant) => variant.type);
+        if (isExclusive(program, each) && getDiscriminatedUnion(program, each)[0] === undefined) {
+            const groups = members
+                .map((member) => modelsOf(member, new Set()).map((model) => keyReadingsOf(program, model)))
+                .filter((group) => group.length > 0);
+            for (const [i, group] of groups.entries()) {
+                for (const [j, other] of groups.entries()) {
+                    if (i === j)
+                        continue;
+                    const rivals = groups.filter((_, k) => k !== j).flat();
+                    for (const first of group) {
+                        for (const second of other) {
+                            const found = tellsApart(first, second, rivals);
+                            if (found !== undefined)
+                                return { union: each, ...found };
+                        }
+                    }
+                }
+            }
+        }
+        for (const member of members) {
+            const found = visit(member, new Set([...via, each]));
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    };
+    return visit(type, new Set());
+}
+/** The objects a member of a union is: itself, or each a union of them reaches. */
+function modelsOf(type, seen) {
+    if (type.kind === "Model")
+        return isArrayType(type) ? [] : [type];
+    if (type.kind !== "Union" || seen.has(type))
+        return [];
+    seen.add(type);
+    return [...type.variants.values()].flatMap((variant) => modelsOf(variant.type, seen));
+}
+const SPELLED = 1;
+const ITSELF = 2;
+const SPELLED_LIST = 4;
+const ITSELF_LIST = 8;
+const NO_READING = { numeric: 0, boolean: 0, other: 0 };
+const EVERY_READING = { numeric: 15, boolean: 15, other: ITSELF | ITSELF_LIST };
+/** Each class of text, and the value a text of it spells. */
+const TEXT_CLASSES = [
+    ["numeric", "number"],
+    ["boolean", "boolean"],
+    ["other", ""],
+];
+/** A model's reading of a key: its own, or every undeclared key's. */
+function keyOf(readings, key) {
+    return (key === undefined ? undefined : readings.keys.get(key)) ?? readings.rest;
+}
+/**
+ * The reading a model's reader takes of a text of one class: the first its schema accepts - see
+ * `wireRead` - or the text as sent where it reads none. `0` where the reader takes one the schema
+ * refuses, which nothing here relies on.
+ */
+function choiceOf(reading, kind) {
+    return reading.read ? lowestBit(reading.readings[kind]) : ITSELF;
+}
+/**
+ * **A key `member` reads one way where `other` accepts that reading and refuses another `member`
+ * accepts** - and `other`'s own reading of the form no rival of it accepts, so the validator reads
+ * the form only as the two do - see {@link ambiguousFormKeyOf}. Where every rival requires a key
+ * whose reading by `other` it refuses, `other`'s reading matches `other` alone, and the form is
+ * accepted as the document accepts it.
+ */
+function tellsApart(member, other, rivals) {
+    const rescued = rivals.every((rival) => [...rival.keys].some(([key, reading]) => reading.required &&
+        TEXT_CLASSES.every(([kind]) => {
+            const choice = choiceOf(keyOf(other, key), kind);
+            return (reading.readings[kind] === 0 ||
+                (choice !== 0 && (reading.readings[kind] & choice) === 0));
+        })));
+    if (rescued)
+        return undefined;
+    const keys = [...new Set([...member.keys.keys(), ...other.keys.keys()])];
+    for (const key of [...keys, undefined]) {
+        const mine = keyOf(member, key);
+        const yours = keyOf(other, key);
+        for (const [kind, spelled] of TEXT_CLASSES) {
+            const accepted = mine.readings[kind];
+            const choice = choiceOf(mine, kind) & accepted;
+            const refused = accepted & ~yours.readings[kind];
+            if (choice === 0 || (yours.readings[kind] & choice) === 0 || refused === 0)
+                continue;
+            return {
+                member: member.model,
+                other: other.model,
+                target: mine.property ?? yours.property ?? member.model,
+                key: key === undefined ? "a key neither declares" : `'${key}'`,
+                first: describeReading(choice, spelled),
+                second: describeReading(lowestBit(refused), spelled),
+            };
+        }
+    }
+    return undefined;
+}
+function lowestBit(mask) {
+    return mask & -mask;
+}
+function describeReading(bit, spelled) {
+    switch (bit) {
+        case SPELLED:
+            return `the ${spelled} it spells`;
+        case ITSELF:
+            return "itself";
+        case SPELLED_LIST:
+            return `the list of the ${spelled} it spells`;
+        default:
+            return "the list of itself";
+    }
+}
+/** Each key a model declares, read as its validator holds it, and every other key's reading. */
+function keyReadingsOf(program, model) {
+    return withVisibility(renderedVisibilityOf(program, model, currentVisibility()), () => {
+        const object = objectOfModel(program, model);
+        const keys = new Map();
+        const none = { readings: NO_READING, read: false, required: false };
+        if (object.kind !== "object")
+            return { model, keys, rest: none };
+        for (const member of object.members) {
+            if (member.property === undefined)
+                continue;
+            keys.set(member.key, {
+                readings: formReadingsOfType(program, encodedParameterType(program, member.property)),
+                read: true,
+                required: member.property.optional !== true,
+                property: member.property,
+            });
+        }
+        const rest = object.rest;
+        return {
+            model,
+            keys,
+            rest: rest === "sealed"
+                ? none
+                : typeof rest === "string"
+                    ? { readings: EVERY_READING, read: false, required: false }
+                    : rest.kind === "type"
+                        ? { readings: formReadingsOfType(program, rest.type), read: true, required: false }
+                        : rest.kind === "never"
+                            ? none
+                            : { readings: EVERY_READING, read: true, required: false },
+        };
+    });
+}
+/**
+ * **The readings of a key's text a value of `type` accepts** - see {@link FormReadings}. A string
+ * accepts any text as itself; a string literal its own text; a number or a boolean the value a text
+ * spells; a list the one-element list of what its element accepts; a value of any type every
+ * reading. A scalar that reads no number or boolean - a date, `bytes` - is text, as a string is.
+ */
+function formReadingsOfType(program, type) {
+    let numeric = 0;
+    let boolean = 0;
+    let other = 0;
+    const seen = new Set();
+    // A literal's own text, in the class of text it is.
+    const literalText = (value, itself) => {
+        if (/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/.test(value))
+            numeric |= itself;
+        else if (value === "true" || value === "false")
+            boolean |= itself;
+        else
+            other |= itself;
+    };
+    const visit = (each, list) => {
+        if (seen.has(each))
+            return;
+        seen.add(each);
+        const [spelled, itself] = list ? [SPELLED_LIST, ITSELF_LIST] : [SPELLED, ITSELF];
+        if (each.kind === "UnionVariant")
+            return visit(each.type, list);
+        if (each.kind === "Union") {
+            for (const variant of each.variants.values())
+                visit(variant.type, list);
+            return;
+        }
+        const element = elementOf(each);
+        if (element !== undefined) {
+            // A list of lists is no text a key spells.
+            if (!list)
+                visit(element, true);
+            return;
+        }
+        if (isTypelessMember(program, each)) {
+            numeric |= spelled | itself;
+            boolean |= spelled | itself;
+            other |= itself;
+            return;
+        }
+        switch (each.kind) {
+            case "String":
+                return literalText(each.value, itself);
+            case "Number":
+                numeric |= spelled;
+                return;
+            case "Boolean":
+                boolean |= spelled;
+                return;
+            case "Enum":
+                for (const member of each.members.values())
+                    visit(member, list);
+                return;
+            case "EnumMember":
+                if (typeof each.value === "number")
+                    numeric |= spelled;
+                else
+                    literalText(each.value ?? each.name, itself);
+                return;
+            case "Scalar":
+                if (readsFromText(program, each)) {
+                    if (isBooleanScalar(each))
+                        boolean |= spelled;
+                    else
+                        numeric |= spelled;
+                }
+                else {
+                    numeric |= itself;
+                    boolean |= itself;
+                    other |= itself;
+                }
+                return;
+            default:
+                return;
+        }
+    };
+    visit(type, false);
+    return { numeric, boolean, other };
+}
+/** Whether a scalar is `boolean`, or declared on it. */
+function isBooleanScalar(scalar) {
+    for (let each = scalar; each !== undefined; each = each.baseScalar) {
+        if (each.name === "boolean")
+            return true;
+    }
+    return false;
+}
+/** Whether readers read anything, or leave every value the text it is. */
+function readsText(readers) {
+    return readers.values !== null || readers.fields !== null || readers.by !== undefined;
+}
+/**
+ * **Every object a URL-encoded form can stand for in a body of this type, as the readers of its
+ * text**: a model's own, and each model a union reaches, a union nested in it included. A member that
+ * is no object - `string` or `int32` beside a model, a list, `null` - is never what a form is, so it
+ * adds no reading, and its schema refuses the object as the document's does. A form is never `null`.
+ */
+function formReadingsOf(program, registry, type) {
+    if (type.kind === "Model") {
+        return isArrayType(type)
+            ? []
+            : [withParameterPosition(true, () => readersOf(program, registry, type, true))];
+    }
+    if (type.kind !== "Union")
+        return [];
+    const variants = [...type.variants.values()].map((variant) => variant.type);
+    const [discriminated] = getDiscriminatedUnion(program, type);
+    if (discriminated === undefined) {
+        return variants.flatMap((variant) => formReadingsOf(program, registry, variant));
+    }
+    /**
+     * **A discriminated union is read as the variant its discriminator names**, as a discriminated
+     * base is - see `readersOf` - so a key two variants declare differently is read as the one sent.
+     * With no envelope the variant is the object. With one, the object is its envelope, `{ kind, value
+     * }`, and `value` is read as the variant: `kind=i&value=5` is `{ kind: "i", value: 5 }` where the
+     * variant is an `int32`, and `value=5` under `kind=l` the list `[5]`.
+     */
+    const { envelope, discriminatorPropertyName, envelopePropertyName } = discriminated.options;
+    const byVariant = [...discriminated.variants].map(([value, variant]) => {
+        if (envelope === "none") {
+            return [value, formReadingsOf(program, registry, variant)[0] ?? NO_READERS];
+        }
+        const reader = readerOf(program, registry, variant, undefined, true);
+        return [
+            value,
+            reader === null ? NO_READERS : { values: null, fields: { [envelopePropertyName]: reader } },
+        ];
+    });
+    /**
+     * A variant that is a discriminated base dispatches on a discriminator of its own, which one
+     * dispatch does not reach: each variant is then a reading of its own, judged by the whole union.
+     */
+    if (byVariant.some(([, readers]) => readers.by !== undefined)) {
+        return variants.flatMap((variant) => formReadingsOf(program, registry, variant));
+    }
+    if (!byVariant.some(([, readers]) => readsText(readers)))
+        return [NO_READERS];
+    return [
+        {
+            values: null,
+            fields: null,
+            by: { property: discriminatorPropertyName, readers: Object.fromEntries(byVariant) },
+        },
+    ];
+}
+function jsonOrTextDecoded(declared, asText) {
+    return `z.preprocess((raw) => { if (typeof raw !== "string") return raw; try { const parsed: unknown = JSON.parse(raw); if (${declared}.safeParse(parsed).success) return parsed; } catch { /* text, read as text */ } return raw; }, ${asText})`;
+}
+/**
+ * **A JSON list part, decoded from one text as the whole list or from several as its elements** -
+ * see {@link isJsonListPart}. A lone text is the list here, as the component publishes it; the
+ * request boxes one that is not into the one element it is, before this applies.
+ */
+function jsonListDecoded(declared) {
+    return `z.preprocess((raw, ctx) => { try { if (typeof raw === "string") return JSON.parse(raw); if (Array.isArray(raw)) return raw.map((each: unknown) => (typeof each === "string" ? JSON.parse(each) : each)); } catch { ctx.addIssue({ code: "custom", message: "Invalid JSON in a multipart part" }); return z.NEVER; } return raw; }, ${declared})`;
+}
 function jsonTextDecoded(declared) {
     return `z.preprocess((raw, ctx) => { if (typeof raw !== "string") return raw; try { return JSON.parse(raw); } catch { ctx.addIssue({ code: "custom", message: "Invalid JSON in a multipart part" }); return z.NEVER; } }, ${declared})`;
 }
-function isBinaryPart(type) {
+function isBinaryPart(program, type) {
     if (type.kind === "Scalar") {
         for (let scalar = type; scalar !== undefined; scalar = scalar.baseScalar) {
             if (scalar.name === "bytes")
@@ -844,13 +1461,7 @@ function isBinaryPart(type) {
         }
         return false;
     }
-    if (type.kind !== "Model")
-        return false;
-    for (let model = type; model !== undefined; model = model.baseModel) {
-        if (model.name === "File")
-            return true;
-    }
-    return false;
+    return type.kind === "Model" && isOrExtendsHttpFile(program, type);
 }
 /**
  * Whether a body served under these media types is RAW BINARY rather than a JSON value.
@@ -884,6 +1495,17 @@ function isParseableMediaType(type) {
         essence === "application/x-www-form-urlencoded" ||
         essence.startsWith("multipart/"));
 }
+/**
+ * Whether a body is rendered with its metadata annotations ignored, as openapi3 renders it: an
+ * explicit `@body` whose type carries them - see `withMetadataAnnotationsIgnored`.
+ */
+function ignoresMetadata(body) {
+    return (body !== undefined &&
+        "isExplicit" in body &&
+        body.isExplicit === true &&
+        "containsMetadataAnnotations" in body &&
+        body.containsMetadataAnnotations === true);
+}
 /** The declared request body type, if the operation takes one. */
 function requestBodyOf(operation) {
     const body = requestBodyParameterOf(operation);
@@ -923,6 +1545,11 @@ const COLLECTION_DELIMITERS = {
     "ArrayEncoding.commaDelimited": ",",
     "ArrayEncoding.newlineDelimited": "\n",
 };
+/** A parameter's array encoding - the `style` openapi3 publishes for it - or `undefined`. */
+function arrayEncodingOf(program, property) {
+    const encoding = getEncode(program, property)?.encoding;
+    return encoding !== undefined && encoding in COLLECTION_DELIMITERS ? encoding : undefined;
+}
 /**
  * Whether the parameter crosses the wire as a list, which is what makes a delimiter meaningful.
  *
@@ -932,8 +1559,34 @@ const COLLECTION_DELIMITERS = {
  * schema, so every request was refused. Only a query parameter keeps its list under an array
  * encoding, and only there is a split undone.
  */
-function isCollectionParameter(program, property) {
-    return isArrayType(encodedParameterType(program, property));
+function isCollectionParameter(wire) {
+    return isArrayType(wire);
+}
+/**
+ * **The forms a parameter's text can take: one per shape its type's members have.** A union of a
+ * scalar and a list - `int32 | string[]` - is `5` or `a,b` on the wire, and each is undone its own
+ * way: the scalar members read as text, each list split, each record or model expanded. Undone only
+ * as the scalar it might be, `a,b` was refused. A type of one shape is one form, itself.
+ */
+function wireFormsOf(type) {
+    if (type.kind !== "Union")
+        return [type];
+    const members = [];
+    const visit = (each) => {
+        if (each.kind === "UnionVariant")
+            return visit(each.type);
+        if (each.kind === "Union")
+            return [...each.variants.values()].forEach((v) => visit(v.type));
+        if (!(each.kind === "Intrinsic" && each.name === "null"))
+            members.push(each);
+    };
+    visit(type);
+    const shaped = members.filter((member) => expansionShapeOf(member) !== "scalar");
+    if (shaped.length === 0)
+        return [type];
+    const scalar = members.some((member) => expansionShapeOf(member) === "scalar");
+    // The union itself stands for its scalar members: a scalar's form, read against the whole schema.
+    return [...(scalar ? [type] : []), ...shaped];
 }
 /**
  * Whether the values arrive one per OCCURRENCE (RFC 6570 explode) rather than joined into one.
@@ -944,10 +1597,16 @@ function isCollectionParameter(program, property) {
  * refused a conformant request while accepting the same list sent twice, which no document
  * describes. Found by the first consumer's `?topics=ip` (#1).
  */
-function isExplodedCollection(program, parameter) {
-    return (isCollectionParameter(program, parameter.param) &&
-        (parameter.type === "query" || parameter.type === "header") &&
-        parameter.explode === true);
+function isExplodedCollection(program, parameter, wire) {
+    /**
+     * **A query only.** A header is `simple` style, which joins a list with commas exploded or not -
+     * explode changes how a `simple` OBJECT is written, never a list - so an exploded header list
+     * boxed whole was `["1,2"]`, refused where the document reads `[1, 2]`.
+     */
+    return (isCollectionParameter(wire) &&
+        parameter.type === "query" &&
+        parameter.explode === true &&
+        arrayEncodingOf(program, parameter.param) === undefined);
 }
 /**
  * The delimiter a parameter's values were joined with, or `undefined` when they were not joined.
@@ -956,17 +1615,24 @@ function isExplodedCollection(program, parameter) {
  * `form` style, which OpenAPI joins with a comma, and a header list is `simple` style, also comma.
  * Those are the two that looked correct because the document and the validator agreed.
  */
-function collectionDelimiterOf(program, parameter) {
-    if (!isCollectionParameter(program, parameter.param))
-        return undefined;
-    if (parameter.type !== "query" && parameter.type !== "header")
+function collectionDelimiterOf(program, parameter, wire) {
+    if (!isCollectionParameter(wire))
         return undefined;
-    if (parameter.explode === true)
+    // A cookie is `form` with `explode: false` in the document, which joins a list with commas.
+    if (parameter.type !== "query" && parameter.type !== "header" && parameter.type !== "cookie") {
         return undefined;
-    const encoding = getEncode(program, parameter.param)?.encoding;
-    if (encoding !== undefined && encoding in COLLECTION_DELIMITERS) {
-        return COLLECTION_DELIMITERS[encoding];
     }
+    /**
+     * **An array encoding is a `style`, and it wins over `explode`.** openapi3 writes the encoding's
+     * style - `pipeDelimited` - and writes `explode: true` only by leaving it out, which for every
+     * style but `form` means NOT exploded. So the document joins the list with the encoding's
+     * delimiter, `?xp=1|2`, explode or not; boxed as one occurrence, that was refused.
+     */
+    const encoding = arrayEncodingOf(program, parameter.param);
+    if (encoding !== undefined)
+        return COLLECTION_DELIMITERS[encoding];
+    if (parameter.type === "query" && parameter.explode === true)
+        return undefined;
     return ",";
 }
 /**
@@ -997,26 +1663,25 @@ function collectionDelimiterOf(program, parameter) {
  * the document justifies. Same rule as the collection split above - decode the wire form, then apply
  * the document's schema to the result, never instead of it.
  *
- * Derived from the emitted expression rather than a restated list of scalar names: `SCALARS` in
- * `zod.ts` decides what becomes `z.number()`, and a second copy of that list here would stop agreeing
- * with it silently.
- */
-function wireDecoded(declared, kind, elementKind) {
-    const NUMBER = '(raw) => (typeof raw === "string" && raw.trim() !== "" && Number.isFinite(Number(raw)) ? Number(raw) : raw)';
-    const BOOLEAN = '(raw) => (raw === "true" ? true : raw === "false" ? false : raw)';
-    if (kind === "number")
-        return `z.preprocess(${NUMBER}, ${declared})`;
-    if (kind === "boolean")
-        return `z.preprocess(${BOOLEAN}, ${declared})`;
+ * **Read against the schema, not by a kind decided from the type** - see `WIRE_READ_SOURCE`. A
+ * kind could not say `int32 | boolean`, a numeric enum, or `int32 | "all"`, where `"5"` is `5` and
+ * `"all"` is text; each of them refused a value the document accepts. Only a type with a value text
+ * cannot be read at all - every string - is left without a reader, and its validator is unchanged.
+ */
+function wireDecoded(program, registry, declared, type) {
+    if (readsFromText(program, type)) {
+        return `z.preprocess((raw) => wireRead(raw, ${declared}), ${declared})`;
+    }
     /**
-     * A list whose ELEMENTS are numeric or boolean - `?ids=1,2,3` after the collection split, or a
-     * repeated `?id=1&id=2`. The elements are strings for exactly the same reason the scalar is, so
-     * the same decoder applies per element. A non-array value is left alone; the split that produces
-     * the array runs outside this and may not have happened.
+     * A list whose ELEMENTS are read from text - `?ids=1,2,3` after the collection split, or a
+     * repeated `?id=1&id=2` - each against the element's own schema, as a lone scalar is. A non-array
+     * value is left alone; the split that produces the array runs outside this and may not have
+     * happened.
      */
-    if (elementKind !== undefined) {
-        const decoder = elementKind === "number" ? NUMBER : BOOLEAN;
-        return `z.preprocess((raw) => (Array.isArray(raw) ? raw.map(${decoder}) : raw), ${declared})`;
+    const element = elementOf(type);
+    if (element !== undefined && readsFromText(program, element)) {
+        const schema = atItem(program, type, () => registry.expressionFor(element));
+        return `z.preprocess((raw) => (Array.isArray(raw) ? raw.map((item) => wireRead(item, ${schema})) : raw), ${declared})`;
     }
     return declared;
 }
@@ -1122,10 +1787,11 @@ literalQueryNames) {
     let accept;
     /** Form-exploded records and models, gathered back under their names around the query object. */
     const gathered = [];
-    const queryNames = operation.parameters.parameters
+    const parameters = publishedParametersOf(operation);
+    const queryNames = parameters
         .filter((parameter) => parameter.type === "query")
         .map((parameter) => parameter.name);
-    for (const parameter of operation.parameters.parameters) {
+    for (const parameter of parameters) {
         /**
          * **`cookie` is here because `@typespec/http` puts it here**, and excluding it was silent.
          * `HttpOperationParameter` discriminates on `"header" | "cookie" | "query" | "path"`, and this
@@ -1157,113 +1823,198 @@ literalQueryNames) {
          * The TypeSpec property name is an authoring convenience that does not survive to the contract.
          */
         /**
-         * **Two parameters of one location and one wire name are one value on the wire**, and both
-         * declarations apply to it: their schemas are intersected and the value is decoded once, by
-         * the first declaration's wire form, so each judges the same decoded value. Decoded by each
-         * and then intersected, `@query("x") a: string` beside `@query("x") b: int32` would hand Zod
-         * `"1"` and `1` to merge, which it does not refuse but throws on. An object literal cannot
-         * hold the key twice either. `shared-input-key` reports it.
+         * **Two parameters of one location and one wire name are one value on the wire, and the
+         * document publishes the first.** openapi3 writes one parameter per name and location, so
+         * `@query("x") a: string` beside `@query("x") b: int32` is published as `x: string`, and `?x=abc`
+         * is valid. Intersected, as both declarations, it was refused. `shared-input-key` reports it.
          */
-        const sharing = operation.parameters.parameters.filter((other) => other.type === parameter.type && other.name === parameter.name);
-        if (sharing[0] !== parameter)
+        const first = parameters.find((other) => sameWireName(other, parameter));
+        if (first !== parameter)
             continue;
-        const delimiter = collectionDelimiterOf(program, parameter);
-        const declared = sharing
-            .map((other) => registry.expressionForProperty(other.param))
-            .reduce((first, other) => `${first}.and(${other})`);
-        /**
-         * The wire form is decoded before it is validated, never instead of it. `z.preprocess` undoes
-         * exactly the flattening the document's `style` describes and then applies the schema the
-         * document publishes, so every constraint on the list - `minItems`, the element type - still
-         * runs. Splitting in the handler instead would have left those unenforced.
-         */
+        // A header another one names in other case is refused, as `never` - see `headerCaseCollisionOf`.
+        if (headerCaseCollisionOf(program, operation, parameter)) {
+            const refused = parameter.param.optional ? "z.never().exactOptional()" : "z.never()";
+            add(parameter.type, parameter.name, refused);
+            add("header-without-accept", parameter.name, refused);
+            continue;
+        }
         /**
-         * Decoded BEFORE the split is wrapped around it, so the two nest in wire order: the outer
-         * preprocess turns `"1,2,3"` into `["1","2","3"]`, the inner one turns those into numbers, and
-         * the document's schema then validates the result. Wrapping the other way round would hand the
-         * element decoder an unsplit string.
+         * A parameter published as a reference to another document states no schema - openapi3 writes
+         * the reference and nothing else - and is refused, as a type published so is.
          */
-        const decoded = parameter.type === "header" && parameter.name.toLowerCase() === "content-type"
-            ? mediaTypeDecoded(declared)
-            : wireDecoded(declared, 
+        const external = externalReferenceOf(parameter.param);
+        if (external !== undefined) {
+            const refused = refuseExternalReference(program, parameter.param, external);
+            const value = parameter.param.optional ? `${refused}.exactOptional()` : refused;
+            add(parameter.type, parameter.name, value);
+            if (parameter.type === "header")
+                add("header-without-accept", parameter.name, value);
+            continue;
+        }
+        // At the visibility its shared component is published at - see `parameterVisibilityOf`.
+        withVisibility(parameterVisibilityOf(parameter.param) ?? currentVisibility(), () => {
+            const declared = registry.expressionForProperty(parameter.param);
             /**
-             * `@encode` on the PROPERTY changes what crosses the wire, so the encoded type is
-             * the one to read. `@encode("unixTimestamp", int32) value: utcDateTime` is a number
-             * on the wire and a date in the spec, and reading the declared type alone stopped
-             * eighteen such parameters being decoded.
+             * Each form the value can take, undone its own way and validated against the WHOLE schema - see
+             * `wireFormsOf`. The first form the schema accepts is the value, as the first reading `wireRead`
+             * finds is.
              */
-            wireKindOf(program, encodedParameterType(program, parameter.param)), elementKindOf(program, encodedParameterType(program, parameter.param)));
-        /**
-         * The boxing half of the same principle: an exploded array's single occurrence arrives as a
-         * bare string, so it is boxed into the one-element array the document describes before the
-         * schema runs - every constraint on the list still applies to the result. Several
-         * occurrences arrive already an array and pass through untouched, exactly as the delimiter
-         * arm leaves a pre-split value alone.
-         */
-        const boxedOrSplit = isExplodedCollection(program, parameter)
-            ? `z.preprocess((raw) => (typeof raw === "string" ? [raw] : raw), ${decoded})`
-            : delimiter === undefined
-                ? decoded
-                : `z.preprocess((raw) => (typeof raw === "string" ? raw.split(${literal(delimiter)}) : raw), ${decoded})`;
-        /**
-         * **An RFC 6570 expansion is undone OUTSIDE everything above**, because it is the first thing the
-         * wire did: `array.a.b` becomes `["a", "b"]`, then the element decoder and the document's schema
-         * run on that. See {@link uriExpansionCall}.
-         */
-        const wire = encodedParameterType(program, parameter.param);
-        const shape = expansionShapeOf(wire);
-        const values = recordValuesOf(program, wire);
-        let expression = boxedOrSplit;
-        if (parameter.type === "path") {
-            const segment = decodedSegmentOf(program, parameter, segments);
-            if (segment !== undefined) {
-                expression = `z.preprocess(${uriExpansionCall({ ...segment, name: parameter.name, shape, values })}, ${decoded})`;
-            }
-        }
-        else if (parameter.type === "query" && shape === "record") {
-            if (parameter.explode === true) {
+            /**
+             * `@encode` on the PROPERTY changes what crosses the wire, so the encoded type is the one to
+             * read - see below.
+             */
+            const wires = wireFormsOf(encodedParameterType(program, parameter.param));
+            // The members a form-exploded query gathers back under its name - see `formOf`.
+            const objectForms = parameter.type === "query" && parameter.explode === true
+                ? wires.filter((wire) => expansionShapeOf(wire) === "record")
+                : [];
+            /**
+             * **A list or a scalar beside them is the parameter sent as itself**, `?x=1&x=2`, which the
+             * objects' gatherer would take as a key of its own - see `WIRE_ITSELF_SOURCE`. Then, as for a
+             * union of models, the query is gathered once and each member reads it its own way.
+             */
+            const itself = objectForms.length > 0 && wires.length > objectForms.length;
+            const gatheredOnce = objectForms.length > 1 || itself;
+            const gatheredOthers = [
+                ...queryNames.filter((name) => name !== parameter.name),
+                ...literalQueryNames,
+            ];
+            const formOf = (wire) => {
+                const delimiter = collectionDelimiterOf(program, parameter, wire);
+                /**
+                 * The wire form is decoded before it is validated, never instead of it. `z.preprocess` undoes
+                 * exactly the flattening the document's `style` describes and then applies the schema the
+                 * document publishes, so every constraint on the list - `minItems`, the element type - still
+                 * runs. Splitting in the handler instead would have left those unenforced.
+                 */
+                /**
+                 * Decoded BEFORE the split is wrapped around it, so the two nest in wire order: the outer
+                 * preprocess turns `"1,2,3"` into `["1","2","3"]`, the inner one turns those into numbers, and
+                 * the document's schema then validates the result. Wrapping the other way round would hand the
+                 * element decoder an unsplit string.
+                 */
+                const decoded = parameter.type === "header" && parameter.name.toLowerCase() === "content-type"
+                    ? mediaTypeDecoded(declared)
+                    : wireDecoded(program, registry, declared, wire);
                 /**
-                 * `{?param*}` over an object expands to the object's own keys, so there is no `param` key for
-                 * this entry to read; the gatherer around the query object puts one back.
+                 * The boxing half of the same principle: an exploded array's single occurrence arrives as a
+                 * bare string, so it is boxed into the one-element array the document describes before the
+                 * schema runs - every constraint on the list still applies to the result. Several
+                 * occurrences arrive already an array and pass through untouched, exactly as the delimiter
+                 * arm leaves a pre-split value alone.
                  */
-                const model = wire.kind === "Model" && wire.indexer === undefined ? wire : undefined;
-                const properties = model === undefined ? [] : modelPropertiesOf(model);
+                const boxedOrSplit = isExplodedCollection(program, parameter, wire)
+                    ? `z.preprocess((raw) => (typeof raw === "string" ? [raw] : raw), ${decoded})`
+                    : delimiter === undefined
+                        ? decoded
+                        : `z.preprocess((raw) => (typeof raw === "string" ? raw.split(${literal(delimiter)}) : raw), ${decoded})`;
+                /**
+                 * **An RFC 6570 expansion is undone OUTSIDE everything above**, because it is the first thing the
+                 * wire did: `array.a.b` becomes `["a", "b"]`, then the element decoder and the document's schema
+                 * run on that. See {@link uriExpansionCall}.
+                 */
+                const shape = expansionShapeOf(wire);
+                // A key repeats only in a form-exploded query - see `readersOf`.
+                const readers = readersOf(program, registry, wire, false);
+                let expression = boxedOrSplit;
+                if (parameter.type === "path") {
+                    const segment = decodedSegmentOf(program, parameter, segments, wire);
+                    if (segment !== undefined) {
+                        // A value of any type is the shape its expansion spells - see `URI_EXPANSION_SOURCE`.
+                        const any = shape === "scalar" && takesAnyValue(program, wire);
+                        expression = `z.preprocess(${uriExpansionCall({
+                            ...segment,
+                            name: parameter.name,
+                            shape: any ? "any" : shape,
+                            readers: any ? { values: "z.unknown()", fields: null } : readers,
+                        })}, ${decoded})`;
+                    }
+                }
+                else if ((parameter.type === "header" || parameter.type === "cookie") &&
+                    shape === "record") {
+                    /**
+                     * **A header or a cookie carries a record or a model as text too**, and nothing read it: the
+                     * validator met `"a,1,b,2"` where the document's schema describes `{a: 1, b: 2}`, and refused
+                     * every value. A header is `simple` style - `a,1,b,2`, or `a=1,b=2` exploded - and a cookie is
+                     * `form` without explode, as openapi3 publishes it: the same expansion as a query's, undone
+                     * the same way.
+                     */
+                    const explode = parameter.type === "header" && parameter.explode === true;
+                    expression = `z.preprocess(${uriExpansionCall({ prefix: "", suffix: "", operator: "", name: parameter.name, explode, shape, readers })}, ${decoded})`;
+                }
+                else if (parameter.type === "query" && shape === "record") {
+                    if (parameter.explode === true) {
+                        /**
+                         * `{?param*}` over an object expands to the object's own keys, so there is no `param` key for
+                         * this entry to read; the gatherer around the query object puts one back. A union of
+                         * models is gathered once, below, and each member reads the gathered values its own way.
+                         */
+                        const repeated = readersOf(program, registry, wire, true);
+                        if (gatheredOnce) {
+                            expression = `z.preprocess(${wireReadObjectCall(repeated)}, ${expression})`;
+                        }
+                        else {
+                            const model = wire.kind === "Model" && wire.indexer === undefined ? wire : undefined;
+                            gathered.push(explodedQueryCall({
+                                name: parameter.name,
+                                others: gatheredOthers,
+                                keys: model === undefined ? undefined : explodedKeysOf(program, model),
+                                itself: false,
+                                readers: repeated,
+                            }));
+                        }
+                    }
+                    else {
+                        expression = `z.preprocess(${uriExpansionCall({ prefix: "", suffix: "", operator: "", name: parameter.name, explode: false, shape, readers })}, ${decoded})`;
+                    }
+                }
+                else if (itself) {
+                    // What arrived under the name, where the objects' gatherer took the query.
+                    expression = `z.preprocess(${wireItselfCall()}, ${expression})`;
+                }
+                return expression;
+            };
+            /**
+             * `@encode` on the PROPERTY changes what crosses the wire, so the encoded type is the one to
+             * read. `@encode("unixTimestamp", int32) value: utcDateTime` is a number on the wire and a date
+             * in the spec, and reading the declared type alone stopped eighteen such parameters being
+             * decoded.
+             */
+            const forms = wires.map(formOf);
+            if (gatheredOnce) {
+                // One gatherer for every member, over every key one of them declares - see `formOf`.
+                const keyed = objectForms.map((wire) => wire.kind === "Model" && wire.indexer === undefined
+                    ? explodedKeysOf(program, wire)
+                    : undefined);
                 gathered.push(explodedQueryCall({
                     name: parameter.name,
-                    others: [...queryNames.filter((name) => name !== parameter.name), ...literalQueryNames],
-                    keys: model === undefined
+                    others: gatheredOthers,
+                    keys: keyed.includes(undefined)
                         ? undefined
-                        : properties.map((property) => resolveEncodedName(program, property, "application/json")),
-                    numbers: properties
-                        .filter((property) => wireKindOf(program, encodedParameterType(program, property)) === "number")
-                        .map((property) => resolveEncodedName(program, property, "application/json")),
-                    booleans: properties
-                        .filter((property) => wireKindOf(program, encodedParameterType(program, property)) === "boolean")
-                        .map((property) => resolveEncodedName(program, property, "application/json")),
-                    values,
+                        : [...new Set(keyed.flatMap((keys) => keys ?? []))],
+                    itself,
+                    readers: NO_READERS,
                 }));
             }
-            else {
-                expression = `z.preprocess(${uriExpansionCall({ prefix: "", suffix: "", operator: "", name: parameter.name, explode: false, shape, values })}, ${decoded})`;
+            const expression = forms.length === 1 ? forms[0] : `z.union([${forms.join(", ")}])`;
+            add(parameter.type, parameter.name, expression);
+            /**
+             * **On a route several operations share, `accept` SELECTS the operation - it is not a
+             * constraint on one of them.** Each member declares its own literal, so validating against any
+             * single member's would 400 every request asking for one of the others, and 400 is the wrong
+             * answer twice over: the request is well-formed, and the contract's answer to "I cannot serve
+             * what you asked for" is 406. `selectContentType` decides it instead, so the negotiated route
+             * validates every OTHER header and leaves this one to the negotiation.
+             */
+            if (parameter.type === "header" && parameter.name.toLowerCase() === "accept") {
+                const declared = parameter.param.type;
+                if (declared.kind === "String")
+                    accept = { name: parameter.name, value: declared.value };
             }
-        }
-        add(parameter.type, parameter.name, expression);
-        /**
-         * **On a route several operations share, `accept` SELECTS the operation - it is not a
-         * constraint on one of them.** Each member declares its own literal, so validating against any
-         * single member's would 400 every request asking for one of the others, and 400 is the wrong
-         * answer twice over: the request is well-formed, and the contract's answer to "I cannot serve
-         * what you asked for" is 406. `selectContentType` decides it instead, so the negotiated route
-         * validates every OTHER header and leaves this one to the negotiation.
-         */
-        if (parameter.type === "header" && parameter.name.toLowerCase() === "accept") {
-            const declared = parameter.param.type;
-            if (declared.kind === "String")
-                accept = { name: parameter.name, value: declared.value };
-        }
-        else if (parameter.type === "header") {
-            add("header-without-accept", parameter.name, expression);
-        }
+            else if (parameter.type === "header") {
+                add("header-without-accept", parameter.name, expression);
+            }
+        });
     }
     const fileContentType = fileContentTypeOf(operation);
     if (fileContentType !== undefined) {
@@ -1300,32 +2051,159 @@ literalQueryNames) {
  * string`, and validated by `z.string()`; shaped from the declared list it was expanded into
  * `["a", "b"]` first, and every request was refused.
  */
-function decodedSegmentOf(program, parameter, segments) {
+function decodedSegmentOf(program, parameter, segments, wire) {
     const segment = segments.find((candidate) => candidate.kind === "expression" && candidate.parameter === parameter.name);
-    return segment !== undefined &&
-        needsExpansionDecoding(segment, expansionShapeOf(encodedParameterType(program, parameter.param)))
+    if (segment === undefined)
+        return undefined;
+    // Decoded where any form the value can take is - see `wireFormsOf`.
+    const forms = wire === undefined ? wireFormsOf(encodedParameterType(program, parameter.param)) : [wire];
+    return forms.some((form) => needsExpansionDecoding(segment, expansionShapeOf(form)))
         ? segment
         : undefined;
 }
+/**
+ * **Whether a value of the type may be anything**: `unknown`, a scalar with no standard base, or a
+ * union holding one - published as `{}` or with `{}` among its members - so its text may spell a list
+ * or an object as well as a scalar.
+ */
+function takesAnyValue(program, type) {
+    if (type.kind === "UnionVariant")
+        return takesAnyValue(program, type.type);
+    if (type.kind === "Union") {
+        return [...type.variants.values()].some((variant) => takesAnyValue(program, variant.type));
+    }
+    return isTypelessMember(program, type);
+}
 /** What a parameter's value decodes into once its expansion is undone. */
 function expansionShapeOf(type) {
     if (isArrayType(type))
         return "list";
     return type.kind === "Model" ? "record" : "scalar";
 }
-/** How a record's values decode, read from its indexer the way a scalar's kind is read. */
-function recordValuesOf(program, type) {
-    if (type.kind !== "Model" || isArrayType(type) || type.indexer === undefined)
-        return "";
-    return wireKindOf(program, type.indexer.value) ?? "";
-}
-/** A model's properties, its base model's first, as the document lists them. */
-function modelPropertiesOf(model) {
-    const chain = [];
-    for (let current = model; current !== undefined; current = current.baseModel) {
-        chain.unshift(current);
+/**
+ * The schemas a record's or a model's values are read from text against - see `wireRead`: every
+ * value of a record against its indexer's, each key of a model against its property's. A value
+ * text cannot spell anything else, a string, needs none.
+ *
+ * `repeats` says whether a key may arrive more than once, a list as its repeated values: a
+ * form-exploded query object, and a URL-encoded form. There a lone occurrence is boxed into the list
+ * it stands for. Anywhere else a value is one piece of text, which spells no list: boxed in a header,
+ * a cookie, a path or a non-exploded query, `l,1` was `{ l: [1] }` where the document reads
+ * `{ l: "1" }` and refuses it, and `l,1,l,2` dropped the first value.
+ */
+function readersOf(program, registry, type, repeats) {
+    if (type.kind !== "Model" || isArrayType(type))
+        return NO_READERS;
+    /**
+     * **Every key no member names is read as the indexer that holds it, the topmost in the chain** -
+     * see `bindingIndexerOf`. Read as the model's own, an inherited `...Record<int32>` read nothing and
+     * a subtype's narrower indexer read what the base's, which the validator enforces, accepts.
+     */
+    const binding = bindingIndexerOf(type);
+    const values = binding === undefined || isNeverType(binding.value)
+        ? null
+        : readerOf(program, registry, binding.value, undefined, repeats);
+    /**
+     * **Each key is read as the validator holds it**: the object the model is rendered as, each member
+     * its most derived declaration at its position. Read first-wins from the base down, `Sub { x?:
+     * string }` under `Base { x?: int32 | string }` read `"5"` as `5`, and `Sub` refused it.
+     *
+     * **Where an indexer reads every key, a declared key is read as its own property says** - text
+     * included, so `s?: string` beside `...Record<int32 | string>` stays `"5"` rather than taking the
+     * indexer's reading and becoming `5`.
+     */
+    const fields = {};
+    withVisibility(renderedVisibilityOf(program, type, currentVisibility()), () => {
+        const object = objectOfModel(program, type);
+        if (object.kind !== "object")
+            return;
+        for (const member of object.members) {
+            if (member.property === undefined)
+                continue;
+            const reader = readerOf(program, registry, encodedParameterType(program, member.property), { property: member.property, position: member.position }, repeats, values !== null);
+            if (reader !== null)
+                fields[member.key] = reader;
+        }
+    });
+    /**
+     * **A discriminated base is read as the subtype its discriminator names**: a header `Snake`
+     * carrying `kind,cobra,length,5` is a `Cobra`, whose `length` is a number, and `Pet` carrying
+     * `kind,cat,x,5` a `Cat`, whose `x` is a string though `Dog`'s is a number. Read by one table for
+     * every subtype, a key two of them declare was read as the first's.
+     */
+    const discriminator = getDiscriminator(program, type);
+    const dispatched = dispatchedSubtypesOf(program, type);
+    return {
+        values,
+        fields: Object.keys(fields).length === 0 ? null : fields,
+        ...(discriminator === undefined || dispatched.length === 0
+            ? {}
+            : {
+                by: {
+                    property: discriminator.propertyName,
+                    readers: Object.fromEntries(dispatched.map(([value, subtype]) => [
+                        value,
+                        readersOf(program, registry, subtype, repeats),
+                    ])),
+                },
+            }),
+    };
+}
+/**
+ * The reader for one value of a record or a model, or `null` for none: a list boxed and read element
+ * by element where a key repeats, a value text can spell as something else read against its schema -
+ * the member's, at its position, where there is one - and text, which needs no reading unless
+ * `always`.
+ */
+function readerOf(program, registry, type, member, repeats, always = false) {
+    const whole = () => member === undefined
+        ? withParameterPosition(true, () => registry.expressionFor(type))
+        : registry.expressionForProperty(member.property, member.position);
+    // Text is never `null`, so a `| null` beside a list leaves the list to read.
+    const inner = nullableInnerOf(type) ?? type;
+    const element = elementOf(inner);
+    if (element !== undefined) {
+        // One piece of text spells no list, so it is left to the schema to refuse.
+        if (!repeats)
+            return always ? whole() : null;
+        return eachReader(atItem(program, inner, () => withParameterPosition(true, () => registry.expressionFor(element))));
     }
-    return chain.flatMap((current) => [...current.properties.values()]);
+    /**
+     * **A union holding a list is one value or several**: `e?: int32 | int32[]` arrives as `?e=1` or
+     * `?e=1&e=2`. Several are read as the list's elements; one is read against the whole type, which
+     * takes it as the one value. Read as text alone, the repeated key reached the schema unread and was
+     * refused where the document reads `[1, 2]`. Where a key does not repeat, it is only ever one.
+     */
+    const forms = inner.kind === "Union" ? wireFormsOf(inner) : [];
+    const lists = forms.filter((each) => elementOf(each) !== undefined);
+    if (lists.length > 0) {
+        if (!repeats)
+            return whole();
+        /**
+         * **Every list member's elements, and the whole value to choose by**: `int32[] | string[]`
+         * reads `?ll=1&ll=x` as the strings, the reading the whole accepts, where its first member's
+         * elements made it `[1, "x"]`, and refused. One value is the one value only where a member is
+         * not a list; `?ll=x` is the list `["x"]`.
+         */
+        const each = lists.map((list) => atItem(program, list, () => withParameterPosition(true, () => registry.expressionFor(elementOf(list)))));
+        const one = forms.some((each) => elementOf(each) === undefined) ? whole() : undefined;
+        return eachReader(each, one, whole());
+    }
+    if (!always && !readsFromText(program, type))
+        return null;
+    return whole();
+}
+/**
+ * **The keys a form-exploded model is gathered by: the members its validator declares**, at the
+ * visibility it is rendered at. Every property was a key, so `?secret=x` on a GET gathered a
+ * create-only property the document does not publish there, and a sealed model refused the request
+ * the document reads as `{}`.
+ */
+function explodedKeysOf(program, model) {
+    return withVisibility(renderedVisibilityOf(program, model, currentVisibility()), () => {
+        const object = objectOfModel(program, model);
+        return object.kind === "object" ? object.members.map((member) => member.key) : [];
+    });
 }
 /**
  * **The media type an `Http.File` body declares, as the input it is.** A file's `contentType` is the
@@ -1340,7 +2218,7 @@ function fileContentTypeOf(operation) {
     const body = requestBodyParameterOf(operation);
     if (body?.bodyKind !== "file")
         return undefined;
-    const declared = operation.parameters.parameters.some((parameter) => parameter.type === "header" && parameter.name.toLowerCase() === "content-type");
+    const declared = publishedParametersOf(operation).some((parameter) => parameter.type === "header" && parameter.name.toLowerCase() === "content-type");
     return declared ? undefined : body.contentTypeProperty;
 }
 /**
@@ -1354,9 +2232,14 @@ function fileContentTypeOf(operation) {
  * 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.
+ * The keys a merged body would contribute to the handler's input: each key of the object the body's
+ * validator declares, under its wire name, or each named part of a multipart body.
+ *
+ * **Read from that object, at the visibility and in the context it is rendered in**, so the two
+ * cannot disagree. A read-only property is one openapi3 shares into a request that has nothing else
+ * request-specific, as `readOnly` and still required under OAS 3.1's reading: read at the request
+ * visibility it dropped out, so `@path accountId` beside a body requiring `accountId` was merged with
+ * it and one of the two lost.
  */
 function mergedBodyKeysOf(program, operation) {
     const body = requestBodyParameterOf(operation);
@@ -1366,9 +2249,55 @@ function mergedBodyKeysOf(program, operation) {
     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")));
+    const requested = requestVisibilityOf(program, operation);
+    return withVisibility(rootVisibilityOf(program, type, requested), () => withMetadataAnnotationsIgnored(ignoresMetadata(body), () => {
+        const object = objectOfModel(program, type);
+        return object.kind === "object" ? object.members.map((member) => member.key) : [];
+    }));
+}
+/**
+ * **Whether two parameters name one value on the wire**: one location and one name - a header's name
+ * read without its case, as HTTP reads it (RFC 9110 section 5.1).
+ */
+function sameWireName(one, other) {
+    return (one.type === other.type &&
+        (one.type === "header"
+            ? one.name.toLowerCase() === other.name.toLowerCase()
+            : one.name === other.name));
+}
+/**
+ * **Two headers whose names differ only in case are one header**, and openapi3 publishes them as two
+ * parameters of the one value - `x-foo: int32` and `X-Foo: string` - which every value has to
+ * satisfy at once and a server hands over once. `header-case-collision`, an error, reported once per
+ * pair, and both validate nothing; validated as the last, `X-Foo: abc` was served where the
+ * document refuses it.
+ */
+const headerCaseCollisionsReported = new WeakMap();
+function headerCaseCollisionOf(program, operation, parameter) {
+    if (parameter.type !== "header")
+        return false;
+    const other = publishedParametersOf(operation).find((each) => each.type === "header" &&
+        each.name !== parameter.name &&
+        each.name.toLowerCase() === parameter.name.toLowerCase());
+    if (other === undefined)
+        return false;
+    const names = [parameter.name, other.name].toSorted();
+    const reported = headerCaseCollisionsReported.get(program) ?? new Set();
+    headerCaseCollisionsReported.set(program, reported);
+    const key = `${operation.operation.name}\u0000${names.join("\u0000")}`;
+    if (!reported.has(key)) {
+        reported.add(key);
+        reportDiagnostic(program, {
+            code: "header-case-collision",
+            target: parameter.param,
+            format: {
+                operation: operation.operation.name,
+                first: names[0] ?? "",
+                second: names[1] ?? "",
+            },
+        });
+    }
+    return true;
 }
 const INPUT_LOCATION_NOUNS = {
     path: "path parameter",
@@ -1395,7 +2324,7 @@ function sharedInputKeysOf(program, operation) {
     if (resolved !== undefined)
         return resolved;
     const inputs = [];
-    for (const parameter of operation.parameters.parameters) {
+    for (const parameter of publishedParametersOf(operation)) {
         if (parameter.type === "path" ||
             parameter.type === "query" ||
             parameter.type === "header" ||
@@ -1440,7 +2369,13 @@ function sharedInputKeysOf(program, operation) {
         if (reported.has(said))
             return;
         reported.add(said);
-        reportDiagnostic(program, { code: "shared-input-key", target: input.target, format });
+        reportDiagnostic(program, {
+            code: "shared-input-key",
+            // One location, one value on the wire: the document publishes the first declaration.
+            messageId: first.location === input.location ? "repeated" : "default",
+            target: input.target,
+            format,
+        });
     });
     sharedInputKeys.set(operation, shared);
     return shared;
@@ -1448,6 +2383,7 @@ function sharedInputKeysOf(program, operation) {
 const sharedInputKeys = new WeakMap();
 const sharedInputKeysReported = new WeakMap();
 function requestBodyPlacementOf(program, operation) {
+    reportNeverBody(program, operation, operation.parameters.body, "request");
     const requestType = requestBodyOf(operation);
     const bodyParameter = requestBodyParameterOf(operation);
     const contentTypes = [...(bodyParameter?.contentTypes ?? [])];
@@ -1457,7 +2393,7 @@ function requestBodyPlacementOf(program, operation) {
      * 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";
+    const bytes = requestType?.kind === "Scalar" && program.checker.isStdType(requestType, "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
@@ -1542,10 +2478,11 @@ function requestBodyPlacementOf(program, operation) {
      * 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.
+     * separately; named, the handler is given both. The body's keys are the keys its validator
+     * declares - see `mergedBodyKeysOf` - so a read-only `id` shared into the request, still required
+     * under OAS 3.1's reading, collides with `@path id` as any other key does.
      */
-    const parameterNames = new Set(operation.parameters.parameters.map((parameter) => parameter.name));
+    const parameterNames = new Set(publishedParametersOf(operation).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)) ||
@@ -1577,7 +2514,11 @@ function requestBodyPlacementOf(program, operation) {
     };
 }
 export function collectRoutes(program, registry, service) {
+    return withServiceView(program, service.namespace, () => collectServiceRoutes(program, registry, service));
+}
+function collectServiceRoutes(program, registry, service) {
     const routes = [];
+    reportUnpublishable(program, service.namespace);
     {
         for (const operation of service.operations) {
             /**
@@ -1600,14 +2541,16 @@ export function collectRoutes(program, registry, service) {
              */
             const streamed = streamedTypeOf(program, operation.operation.returnType);
             if (streamed !== undefined) {
-                withVisibility(program, Visibility.Read, () => registry.expressionFor(streamed));
+                withVisibility(Visibility.Read, () => registry.expressionFor(streamed));
             }
             // `@requestVisibility` when the operation states one, otherwise the verb's default - the
             // same resolution `@typespec/openapi3` performs before emitting a request schema.
-            const requestVisibility = resolveRequestVisibility(program, operation.operation, operation.verb);
+            const requestVisibility = requestVisibilityOf(program, operation);
             const { rawBodyProperty, rawBodyBinary, rawBodyUnvalidated, bodyProperty, optionalBody } = requestBodyPlacementOf(program, operation);
             const authentication = authenticationFor(program, operation);
-            const template = routeTemplateOf(operation.uriTemplate, operation.parameters.parameters
+            const template = routeTemplateOf(operation.uriTemplate, 
+            // Every path parameter, a `never` included: the template still holds its expression.
+            operation.parameters.parameters
                 .filter((parameter) => parameter.type === "path")
                 .map((parameter) => ({
                 name: parameter.name,
@@ -1641,7 +2584,7 @@ export function collectRoutes(program, registry, service) {
                     .map((parameter) => parameter.name),
                 pathSegments: template.segments,
                 sharedInputKeys: sharedInputKeysOf(program, operation),
-                decodedPathParameters: operation.parameters.parameters
+                decodedPathParameters: publishedParametersOf(operation)
                     .filter((parameter) => decodedSegmentOf(program, parameter, template.segments) !== undefined)
                     .map((parameter) => parameter.name),
                 literalQuery: template.literalQuery,
@@ -1669,17 +2612,29 @@ export function collectRoutes(program, registry, service) {
                  * one and not the other, and `@visibility` can add or remove properties outright. Walking
                  * both at one visibility gives whichever was seen first to both.
                  */
-                requestSchema: withVisibility(program, requestVisibility, () => {
+                ...withVisibility(requestVisibility, () => withRequestReading(program, requestVisibility, () => {
                     // Multipart first: its body has no single type to walk, and skipping it left every
                     // such route mounted with nothing checking the request at all.
                     const parameterBody = requestBodyParameterOf(operation);
                     if (parameterBody?.bodyKind === "multipart") {
-                        return multipartSchemaOf(program, parameterBody, registry);
+                        return {
+                            requestSchema: multipartRequestOf(program, registry, parameterBody, multipartSchemaOf(program, parameterBody, registry)),
+                            textParts: textPartsOf(program, parameterBody),
+                        };
                     }
-                    return requestType === undefined ? undefined : registry.expressionFor(requestType);
-                }),
+                    if (requestType === undefined)
+                        return { requestSchema: undefined };
+                    reportAmbiguousReadOnly(program, requestType, requestVisibility);
+                    const declared = withMetadataAnnotationsIgnored(ignoresMetadata(parameterBody), () => registry.expressionFor(requestType, true));
+                    const form = formBodyOf(program, registry, operation, parameterBody, requestType, declared);
+                    return form === undefined
+                        ? { requestSchema: declared }
+                        : form.only
+                            ? { requestSchema: form.schema }
+                            : { requestSchema: declared, formRequestSchema: form.schema };
+                })),
                 ...(() => {
-                    const split = withVisibility(program, requestVisibility, () => parameterSchemasOf(program, operation, registry, template.segments, template.literalQuery.map(([name]) => name)));
+                    const split = withVisibility(requestVisibility, () => parameterSchemasOf(program, operation, registry, template.segments, template.literalQuery.map(([name]) => name)));
                     return {
                         cookieSchema: split.cookie,
                         pathSchema: split.path,
@@ -1696,7 +2651,7 @@ export function collectRoutes(program, registry, service) {
                  * visibility declared six components under the wrong suffix - measured:
                  * type/model/visibility gained six divergences.
                  */
-                responses: withVisibility(program, Visibility.Read, () => responsesOf(program, operation, registry)),
+                responses: withVisibility(Visibility.Read, () => responsesOf(program, operation, registry)),
                 rawBodyProperty,
                 rawBodyBinary,
                 rawBodyUnvalidated,
@@ -1911,7 +2866,8 @@ function renderSchemas(registry, externals, routeDeclarations, compileSchemas) {
         if (d.structural === undefined) {
             return `\nexport const ${d.identifier} = ${compiled(d.source, compileSchemas)};\nexport type ${d.typeName} = z.infer<typeof ${d.identifier}>;\n`;
         }
-        const declared = d.structural.startsWith("{")
+        // One object literal is an interface; a union of them - an envelope's wrappers - is not.
+        const declared = isSingleObjectLiteral(d.structural)
             ? `export interface ${d.typeName} ${d.structural}`
             : `export type ${d.typeName} = ${d.structural};`;
         /**
@@ -2033,11 +2989,27 @@ function renderSchemas(registry, externals, routeDeclarations, compileSchemas) {
      * reason `z` is imported only when used: an unused declaration fails the lint a generated file has
      * to pass. Declared rather than imported, so this file still depends on no runtime.
      */
-    const referenced = identifiersIn(routeDeclarations.join(""));
+    const referenced = identifiersIn([...declarations, ...routeDeclarations].join(""));
+    // Both decoders read their values through `wireRead`, so it is declared beside either.
+    const expands = referenced.has("uriExpansion") ||
+        referenced.has("explodedQuery") ||
+        referenced.has("wireReadObject");
+    // And `wireReadAs` reads through `wireRead`, which a multipart text part calls on its own.
+    const readsAs = expands || referenced.has("wireReadAs");
+    if (readsAs || referenced.has("wireRead"))
+        parts.push(WIRE_READ_SOURCE);
+    if (readsAs)
+        parts.push(WIRE_READ_AS_SOURCE);
+    if (expands)
+        parts.push(WIRE_READERS_SOURCE);
     if (referenced.has("uriExpansion"))
         parts.push(URI_EXPANSION_SOURCE);
     if (referenced.has("explodedQuery"))
         parts.push(EXPLODED_QUERY_SOURCE);
+    if (referenced.has("wireReadObject"))
+        parts.push(WIRE_READ_OBJECT_SOURCE);
+    if (referenced.has("wireItself"))
+        parts.push(WIRE_ITSELF_SOURCE);
     if (routeDeclarations.length > 0) {
         parts.push(`
 /** One declared response: its status key, its body's schema, its media types and its headers. */
@@ -2063,14 +3035,55 @@ type ResponseArm = {
  * 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 identifier a route's validator is exported under: the operation's id and the part it checks.
+ *
+ * **Never one of the helpers the module declares beside it.** An operation named `exploded` has a
+ * query validator called `explodedQuery`, which is also the name of the function that gathers an
+ * exploded query object, and the module did not parse. Such a name takes a trailing `_`, as a model
+ * named after an emitted helper does.
+ */
+const schemaConst = (operationId, suffix, taken) => {
+    /**
+     * **And always an identifier, and never one already taken.** `@operationId("get-widget")` is a
+     * valid id and not a valid name: `export const get-widgetQuery` did not parse. Each character no
+     * identifier may hold becomes `_`, and a name another operation already took - `get_widget`
+     * beside `get-widget` - takes one more.
+     */
+    let name = `${operationId.replace(/[^\w$]/g, "_").replace(/^(\d)/, "_$1")}${suffix}`;
+    while (EMITTED_FUNCTIONS.has(name) || taken.has(name))
+        name = `${name}_`;
+    taken.add(name);
+    return name;
+};
+/**
+ * Text written inside a block comment, which `*\/` would end: `@operationId("list*\/items")` is a
+ * valid id, and the comment naming it closed early and left the rest of the line as code.
+ */
+function commentSafe(text) {
+    // And printable ASCII, as every generated file is: a letter outside it is written as its escape.
+    return text
+        .replaceAll("*/", "*\\/")
+        .replace(/[^\x20-\x7e]/gu, (each) => `\\u{${(each.codePointAt(0) ?? 0).toString(16)}}`);
+}
+/** The functions a schemas module may declare for itself - see `helperSources`. */
+const EMITTED_FUNCTIONS = new Set([
+    "uriExpansion",
+    "explodedQuery",
+    "wireRead",
+    "wireReadAs",
+    "wireReaderOf",
+    "wireReadObject",
+    "wireItself",
+    "wireSentAsItself",
+]);
 /** `[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, compileSchemas) {
+function namedSchema(operationId, suffix, expression, compileSchemas, taken) {
     if (expression === undefined)
         return { name: undefined, declaration: undefined };
     if (isIdentifier(expression))
         return { name: expression, declaration: undefined };
-    const name = schemaConst(operationId, suffix);
+    const name = schemaConst(operationId, suffix, taken);
     /**
      * **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,
@@ -2127,10 +3140,11 @@ function sharedSlots(routes) {
 function nameRouteSchemas(routes, compileSchemas) {
     const shared = sharedSlots(routes);
     const declarations = [];
+    const taken = new Set();
     const names = new Map();
     for (const route of routes) {
         const declare = (suffix, expression) => {
-            const resolved = namedSchema(route.operationId, suffix, expression, compileSchemas);
+            const resolved = namedSchema(route.operationId, suffix, expression, compileSchemas, taken);
             if (resolved.declaration !== undefined)
                 declarations.push(resolved.declaration);
             return resolved.name;
@@ -2151,6 +3165,9 @@ function nameRouteSchemas(routes, compileSchemas) {
         const header = declare("Header", negotiating ? route.negotiatedHeaderSchema : route.headerSchema);
         // A raw body is read as text, never parsed, so it has no validator - the bytes are the contract.
         const body = route.rawBodyProperty === undefined ? declare("Body", route.requestSchema) : undefined;
+        const formBody = route.rawBodyProperty === undefined
+            ? declare("FormBody", route.formRequestSchema)
+            : undefined;
         /**
          * One identifier per distinct body, suffixed by the status that first carries it. Two statuses
          * sharing one inline body share its declaration rather than emitting it twice.
@@ -2180,7 +3197,7 @@ function nameRouteSchemas(routes, compileSchemas) {
             }
             return { status: response.status, schema: declaredBodies.get(response.schema), headers };
         });
-        const responses = schemaConst(route.operationId, "Responses");
+        const responses = schemaConst(route.operationId, "Responses", taken);
         declarations.push(`export const ${responses} = ${responseArmsOf(route, arms)} satisfies readonly ResponseArm[];`);
         names.set(route.operationId, {
             operationId: route.operationId,
@@ -2191,6 +3208,7 @@ function nameRouteSchemas(routes, compileSchemas) {
             selectedAccept: negotiating ? route.accept : undefined,
             cookie,
             body,
+            ...(formBody === undefined ? {} : { formBody }),
             arms,
             responses,
         });
@@ -2262,11 +3280,10 @@ function collectRequestTypes(program, registry, service) {
          * 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.
+         * The predicates `propertyToTs` consults read the visibility `withVisibility` sets, and outside
+         * one they read `Read`.
          */
-        withVisibility(program, resolveRequestVisibility(program, operation.operation, operation.verb), () => {
+        withVisibility(requestVisibilityOf(program, operation), () => withRequestReading(program, requestVisibilityOf(program, operation), () => {
             const body = requestBodyOf(operation);
             const placement = requestBodyPlacementOf(program, operation);
             /** The parts of a multipart body, which `requestBodyOf` deliberately does not return. */
@@ -2278,7 +3295,7 @@ function collectRequestTypes(program, registry, service) {
              * 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
+            const extraProperties = publishedParametersOf(operation)
                 .filter((parameter) => parameter.type === "path" ||
                 parameter.type === "query" ||
                 parameter.type === "header" ||
@@ -2290,9 +3307,16 @@ function collectRequestTypes(program, registry, service) {
                  * `"x-thing"` here too: a consumer checking its handlers against these types otherwise
                  * fails to typecheck against a server that is correct.
                  */
+                // One value per name and location, as the document publishes the first declaration.
+                .filter((parameter, index, all) => all.findIndex((other) => sameWireName(other, parameter)) === index)
                 .map((parameter) => ({
                 key: parameter.name,
-                line: registry.expressionForProperty(parameter.param, parameter.name),
+                // At the visibility its shared component is published at - see `parameterVisibilityOf`.
+                // Refused as `never`, as its validator is - a header case collision, or a `@useRef`.
+                line: headerCaseCollisionOf(program, operation, parameter) ||
+                    externalReferenceOf(parameter.param) !== undefined
+                    ? `${objectKey(parameter.name)}${parameter.param.optional ? "?" : ""}: never;`
+                    : withVisibility(parameterVisibilityOf(parameter.param) ?? currentVisibility(), () => registry.expressionForProperty(parameter.param, parameter.name)),
             }));
             const fileContentType = fileContentTypeOf(operation);
             if (fileContentType !== undefined) {
@@ -2326,15 +3350,16 @@ function collectRequestTypes(program, registry, service) {
                  * 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.
                  */
-                if (body !== undefined && declaresComponent(body))
-                    registry.expressionFor(body);
+                if (body !== undefined && declaresComponent(body)) {
+                    withMetadataAnnotationsIgnored(ignoresMetadata(parameterBody), () => registry.expressionFor(body));
+                }
             }
             else {
                 const expression = parameterBody?.bodyKind === "multipart"
-                    ? multipartTsOf({ parts: parameterBody.parts }, registry)
+                    ? multipartTsOf(program, parameterBody, registry)
                     : body === undefined
                         ? undefined
-                        : registry.expressionFor(body);
+                        : withMetadataAnnotationsIgnored(ignoresMetadata(parameterBody), () => registry.expressionFor(body, true));
                 if (parameterBody?.bodyKind !== "multipart")
                     bodyRef = expression;
                 if (expression !== undefined) {
@@ -2351,10 +3376,12 @@ function collectRequestTypes(program, registry, service) {
             entries.push({
                 operationId: operationIdOf(program, operation.operation),
                 bodyRef,
-                input: parts.length === 0 ? "Record<string, never>" : `Simplify<${parts.join(" & ")}>`,
+                input: parts.length === 0
+                    ? "globalThis.Record<string, never>"
+                    : `Simplify<${parts.join(" & ")}>`,
                 streamsBody,
             });
-        });
+        }));
     }
     return entries;
 }
@@ -2368,7 +3395,7 @@ function collectResponseTypes(program, registry, service) {
      * components under the wrong suffix. Saying it here rather than relying on the default is what
      * makes that impossible from either direction.
      */
-    withVisibility(program, Visibility.Read, () => {
+    withVisibility(Visibility.Read, () => {
         for (const operation of service.operations) {
             /**
              * **The same responses, and the same members, the server emitters render.** This walk used
@@ -2394,7 +3421,8 @@ function collectResponseTypes(program, registry, service) {
                 if (member.unvalidated &&
                     member.response.body !== undefined &&
                     declaresComponent(member.response.body)) {
-                    registry.expressionFor(member.response.body);
+                    const declared = member.response.body;
+                    withMetadataAnnotationsIgnored(member.response.ignoresMetadata, () => registry.expressionFor(declared));
                 }
                 switch (member.serving) {
                     case "none":
@@ -2408,9 +3436,10 @@ function collectResponseTypes(program, registry, service) {
                     case "unvalidated":
                         return "string";
                     default: {
-                        if (member.response.body === undefined)
+                        const declared = member.response.body;
+                        if (declared === undefined)
                             return undefined;
-                        const ref = registry.expressionFor(member.response.body);
+                        const ref = withMetadataAnnotationsIgnored(member.response.ignoresMetadata, () => registry.expressionFor(declared, true));
                         bodyRefs.push(ref);
                         return `Produced<${ref}>`;
                     }
@@ -2434,8 +3463,8 @@ function collectResponseTypes(program, registry, service) {
                     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)}`)
+                        ? `readonly ${objectKey(name)}?: ${headerTypeOf(program, property)} | undefined`
+                        : `readonly ${objectKey(name)}: ${headerTypeOf(program, property)}`)
                         .join("; ");
                     fields.push(`readonly headers${every ? "?" : ""}: { ${rendered} }`);
                 }
@@ -2493,9 +3522,9 @@ const BYTE_STREAM = `
  */
 export interface ByteStream {
 	getReader(): {
-		read(): Promise<{ readonly done: boolean; readonly value?: Uint8Array | undefined }>;
+		read(): globalThis.Promise<{ readonly done: boolean; readonly value?: Uint8Array | undefined }>;
 		releaseLock(): void;
-		cancel?(reason?: unknown): Promise<void>;
+		cancel?(reason?: unknown): globalThis.Promise<void>;
 	};
 }
 `;
@@ -2532,7 +3561,7 @@ function renderRequestTypes(entries, responses, registry) {
             : `\nexport type ${declaration.name} = ${declaration.source};\n`;
     });
     const responseLookup = responses
-        .map((entry) => `\t/** Every success body \`${entry.operationId}\` declares. */\n\t${entry.operationId}: ${entry.output};`)
+        .map((entry) => `\t/** Every success body \`${commentSafe(entry.operationId)}\` declares. */\n\t${objectKey(entry.operationId)}: ${entry.output};`)
         .join("\n");
     /**
      * **One member per declared response and media type, each pairing a status with its own body.**
@@ -2540,7 +3569,7 @@ function renderRequestTypes(entries, responses, registry) {
      * over a service binding returns `WireResults[op]`, and a handler can hand it straight on.
      */
     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("")};`)
+        .map((entry) => `\t/** Every response \`${commentSafe(entry.operationId)}\` declares. */\n\t${objectKey(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.**
@@ -2553,7 +3582,7 @@ function renderRequestTypes(entries, responses, registry) {
      * `WireInputs["createUser"]` is the same type, and nothing a spec declares can collide with it.
      */
     const lookup = entries
-        .map((entry) => `\t/** The input for \`${entry.operationId}\`, as its handler receives it. */\n\t${entry.operationId}: ${entry.input.replaceAll("\n", "\n\t")};`)
+        .map((entry) => `\t/** The input for \`${commentSafe(entry.operationId)}\`, as its handler receives it. */\n\t${objectKey(entry.operationId)}: ${entry.input.replaceAll("\n", "\n\t")};`)
         .join("\n");
     /**
      * **Emitted only where an operation has something to flatten.**
@@ -2598,8 +3627,9 @@ type Simplify<T> = { [K in keyof T]: T[K] } & {};
  * one service: 2 contract methods returning \`readonly T[]\` and 35 readonly array properties, none
  * of them expressible against the published shape.
  */
-export type Produced<T> = T extends readonly (infer Element)[]
-	? readonly Produced<Element>[]
+export type Produced<T> = T extends readonly unknown[]
+	? // Mapped over the list itself, so a tuple keeps its positions: \`[A?, ...unknown[]]\`.
+		{ readonly [K in keyof T]: Produced<T[K]> }
 	: T extends object
 		? { readonly [K in keyof T]: Produced<T[K]> }
 		: T;
@@ -2700,7 +3730,7 @@ function renderWireAssertions(schemas, types, entries, responses, contractsPacka
     }
     if (paired.length === 0)
         return undefined;
-    const assertions = paired.map((pair) => `export type Assert${pair.name} = MustHold<Identical<Declared<z.input<typeof ${pair.identifier}>>, Contracts.${pair.name}>>;`);
+    const assertions = paired.map((pair) => `export type Assert${pair.name} = MustHold<Identical<Declared<z.input<typeof ${pair.identifier}>>, Flat<Contracts.${pair.name}>>>;`);
     return `${generatedBanner()}
 import type { z } from "zod";
 import type * as Contracts from "${contractsPackage}";
@@ -2762,10 +3792,9 @@ type DeclaredKeyOf<T> = keyof {
 
 type Declared<T> = T extends (...args: never[]) => unknown
 	? T
-	: T extends readonly (infer Element)[]
-		? T extends Element[]
-			? Declared<Element>[]
-			: readonly Declared<Element>[]
+	: T extends readonly unknown[]
+		? // Mapped over the list itself: a tuple keeps its positions, and \`readonly\` is kept as it is.
+			{ [K in keyof T]: Declared<T[K]> }
 		: T extends object
 			? [DeclaredKeyOf<T>] extends [never]
 				? [T[keyof T]] extends [never]
@@ -2792,6 +3821,24 @@ type Declared<T> = T extends (...args: never[]) => unknown
 					}
 			: T;
 
+/**
+ * **The contract type with its intersections written out**, as \`Declared\` writes out the validator's:
+ * \`(A) & (Inner)\` - a redeclaration merged with a \`@oneOf\` union it cannot be merged into key by key
+ * - and the one object type a mapping makes of it are one shape, which the identity check below tells
+ * apart by spelling. Mapped and nothing dropped, so an index signature the contract states is still
+ * compared.
+ */
+type Flat<T> = T extends (...args: never[]) => unknown
+	? T
+	: T extends object
+		? [keyof T] extends [never]
+			? // **Every object with no key is the one \`{}\`**, as \`Declared\` writes an empty object: an
+				// empty interface beside an empty literal, \`M1 | {}\`, is otherwise two members where
+				// the validator's side is one.
+				{}
+			: { [K in keyof T]: Flat<T[K]> }
+		: T;
+
 /**
  * **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
@@ -2963,124 +4010,190 @@ export async function emitHttpZod(context) {
     for (const snapshot of snapshots) {
         beginOperationIds();
         const service = snapshot.service;
-        const serviceName = service.namespace.name;
-        const perService = options.services?.[serviceName];
-        const outputDir = perService?.["output-dir"] ??
-            (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.
+         * **Rendered whole before anything is written.** This service's view, its operation ids and
+         * its banner are module state, and an `await` while they are in force lets another compile in
+         * the same process run in between: the contract types were walked after `schemas.gen.ts` was
+         * written, and with three fixtures compiled at once in one suite, one walked them under
+         * another program's view - its components unsuffixed, `DerivedK` declared twice, its wire
+         * contract unable to pair a validator with its type. Written after the scope closes, nothing
+         * awaits inside it.
          */
-        const sharedContractsDir = options["contracts-output-dir"];
-        const resolved = {
-            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,
-            keyVocabularies: perService?.["key-vocabularies"] ?? options["key-vocabularies"] ?? [],
-            regenerateHint: perService?.["regenerate-hint"] ?? options["regenerate-hint"],
-        };
-        beginBanner(resolved.regenerateHint);
-        const registry = new SchemaRegistry(context.program);
-        const { result: { routes }, imports: externals, vocabularies, } = collectExternalImports(() => withContractsPackage(resolved.contractsPackage, () => withSealedObjects(resolved.sealObjectSchemas, () => {
-            // Declarations first: a vocabulary is a fact about the contract, so it is collected from
-            // what the service DECLARES rather than from what the Zod walk happens to touch. An enum
-            // reachable only through an error body was silently absent otherwise.
-            noteDeclaredVocabularies(service.namespace.enums.values());
+        const writes = [];
+        // Named and written as openapi3 names and writes this service's components - see `published.ts`.
+        const restoreView = beginServiceView(context.program, service.namespace);
+        try {
             /**
-             * A closed key SET is a vocabulary too, and it cannot be an enum.
-             *
-             * TypeSpec has no key-constrained `Record`, so a model naming its permitted properties is
-             * how the document states one - and a generated type cannot be iterated, which leaves a
-             * consumer needing the set at run time with a hand-maintained copy. Naming the model in
-             * `key-vocabularies` writes the keys beside the types. A name matching nothing is
-             * reported rather than quietly emitting no tuple.
+             * **A union that reaches itself through unions alone is refused before anything is walked,
+             * and the service emits nothing.** Every other refusal is reported and walked past, so one
+             * compile names them all; this one cannot be walked past, because every reading of it - the
+             * schema, the type, a parameter's forms - recurses without end. The rest of the service is
+             * read once the cycle is broken. See `reachesItselfThroughUnions`.
              */
-            const emittedKeyVocabularies = noteKeyVocabularies(context.program, service.namespace.models.values(), resolved.keyVocabularies);
-            for (const name of resolved.keyVocabularies) {
-                if (emittedKeyVocabularies.includes(name))
-                    continue;
-                reportDiagnostic(context.program, {
-                    code: "unknown-key-vocabulary",
-                    target: service.namespace,
-                    format: { name, service: service.namespace.name },
-                });
-            }
+            const selfReaching = [...publishedTypes()].filter((type) => type.kind === "Union" &&
+                type.name !== undefined &&
+                reachesItselfThroughUnions(context.program, type));
+            for (const union of selfReaching)
+                refuseSelfReachingUnion(context.program, union);
+            if (selfReaching.length > 0)
+                continue;
+            const serviceName = service.namespace.name;
+            const perService = options.services?.[serviceName];
+            const outputDir = perService?.["output-dir"] ??
+                (distinctServices.size > 1
+                    ? resolvePath(context.emitterOutputDir, serviceName)
+                    : context.emitterOutputDir);
             /**
-             * The error body is registered INSIDE this walk, so its validator lands in
-             * `schemas.gen.ts` alongside every other declaration. Nothing else reaches it: the Zod
-             * walk follows success bodies and parameters, so without this a runtime would have no
-             * generated schema to check the documents it sends against.
-             *
-             * **Its expression is registered and then deliberately discarded.** It used to be
-             * returned and used as a fallback for any response arm whose own body could not be
-             * resolved, which meant every catch-all answered with whichever shape `errorBodyOf` had
-             * settled on rather than the one its own response declares. Each arm resolves its own
-             * body now; registering this one only ensures it is declared.
+             * **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 errorBody = errorBodyOf(context.program, service);
-            if (errorBody !== undefined) {
-                withVisibility(context.program, Visibility.Read, () => registry.expressionFor(errorBody));
-            }
-            return {
-                routes: withStreamModule(streamModule, () => collectRoutes(context.program, registry, service)),
+            const sharedContractsDir = options["contracts-output-dir"];
+            const resolved = {
+                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,
+                keyVocabularies: perService?.["key-vocabularies"] ?? options["key-vocabularies"] ?? [],
+                regenerateHint: perService?.["regenerate-hint"] ?? options["regenerate-hint"],
             };
-        })));
-        /**
-         * **Named AFTER the walk and BEFORE the file is rendered.** Naming mints identifiers that
-         * `schemas.gen.ts` must declare, so it has to happen while the registry is complete and before
-         * anything is written - and it has to happen HERE rather than in a server emitter, or the
-         * validators it produces never reach this package's own output.
-         */
-        const { names, declarations } = nameRouteSchemas(routes, resolved.compileSchemas);
-        await emitFile(context.program, {
-            path: resolvePath(outputDir, "schemas.gen.ts"),
-            content: renderSchemas(registry, externals, declarations, resolved.compileSchemas),
-        });
-        if (resolved.contractsOutputDir !== undefined) {
-            const types = new TypeRegistry(context.program);
+            beginBanner(resolved.regenerateHint);
+            const registry = new SchemaRegistry(context.program);
+            const { result: { routes }, imports: externals, vocabularies, } = collectExternalImports(() => withContractsPackage(resolved.contractsPackage, () => withSealedObjects(resolved.sealObjectSchemas, () => {
+                // Declarations first: a vocabulary is a fact about the contract, so it is collected from
+                // what the service DECLARES rather than from what the Zod walk happens to touch. An enum
+                // reachable only through an error body was silently absent otherwise.
+                noteDeclaredVocabularies(service.namespace.enums.values());
+                /**
+                 * A closed key SET is a vocabulary too, and it cannot be an enum.
+                 *
+                 * TypeSpec has no key-constrained `Record`, so a model naming its permitted properties is
+                 * how the document states one - and a generated type cannot be iterated, which leaves a
+                 * consumer needing the set at run time with a hand-maintained copy. Naming the model in
+                 * `key-vocabularies` writes the keys beside the types. A name matching nothing is
+                 * reported rather than quietly emitting no tuple.
+                 */
+                const emittedKeyVocabularies = noteKeyVocabularies(context.program, service.namespace.models.values(), resolved.keyVocabularies);
+                for (const name of resolved.keyVocabularies) {
+                    if (emittedKeyVocabularies.includes(name))
+                        continue;
+                    reportDiagnostic(context.program, {
+                        code: "unknown-key-vocabulary",
+                        target: service.namespace,
+                        format: { name, service: service.namespace.name },
+                    });
+                }
+                /**
+                 * The error body is registered INSIDE this walk, so its validator lands in
+                 * `schemas.gen.ts` alongside every other declaration. Nothing else reaches it: the Zod
+                 * walk follows success bodies and parameters, so without this a runtime would have no
+                 * generated schema to check the documents it sends against.
+                 *
+                 * **Its expression is registered and then deliberately discarded.** It used to be
+                 * returned and used as a fallback for any response arm whose own body could not be
+                 * resolved, which meant every catch-all answered with whichever shape `errorBodyOf` had
+                 * settled on rather than the one its own response declares. Each arm resolves its own
+                 * body now; registering this one only ensures it is declared.
+                 */
+                const errorBody = errorBodyOf(context.program, service);
+                if (errorBody !== undefined) {
+                    withVisibility(Visibility.Read, () => registry.expressionFor(errorBody));
+                }
+                const routes = withStreamModule(streamModule, () => collectRoutes(context.program, registry, service));
+                // And every type no operation reaches, as openapi3 publishes it - see `unreachedTypes`.
+                withVisibility(Visibility.All, () => {
+                    for (const type of unreachedTypes())
+                        registry.expressionFor(type);
+                });
+                // And every component openapi3 writes that no route names - see `publishedComponents`.
+                for (const { type, at, ignore, binary } of publishedComponents(context.program)) {
+                    withVisibility(at, () => withMetadataAnnotationsIgnored(ignore, () => withMultipartBinary(binary, () => registry.declare(type))));
+                }
+                return { routes };
+            })));
             /**
-             * **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.
+             * **Named AFTER the walk and BEFORE the file is rendered.** Naming mints identifiers that
+             * `schemas.gen.ts` must declare, so it has to happen while the registry is complete and before
+             * anything is written - and it has to happen HERE rather than in a server emitter, or the
+             * validators it produces never reach this package's own output.
              */
-            const { 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),
-            });
-            await emitFile(context.program, {
-                path: resolvePath(resolved.contractsOutputDir, "vocabularies.gen.ts"),
-                content: renderVocabularies(vocabularies),
+            const { names, declarations } = nameRouteSchemas(routes, resolved.compileSchemas);
+            writes.push({
+                path: resolvePath(outputDir, "schemas.gen.ts"),
+                content: renderSchemas(registry, externals, declarations, resolved.compileSchemas),
             });
-            const assertions = renderWireAssertions(registry, types, entries, responses, resolved.contractsPackage);
-            if (assertions !== undefined) {
-                await emitFile(context.program, {
-                    path: resolvePath(outputDir, "wire-contract.gen.ts"),
-                    content: assertions,
+            if (resolved.contractsOutputDir !== undefined) {
+                const types = new TypeRegistry(context.program, registry.held);
+                /**
+                 * **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.
+                 */
+                /**
+                 * **And inside the same sealing**, because whether a model is published at all can depend
+                 * on it - a template instance extending a base openapi3 seals is refused on both sides,
+                 * `sealed-base-extended` - and the two walks have to agree about that.
+                 */
+                const { requests, assertions } = withSealedObjects(resolved.sealObjectSchemas, () => {
+                    const { entries, responses } = withStreamModule(streamModule, () => ({
+                        entries: collectRequestTypes(context.program, types, service),
+                        responses: collectResponseTypes(context.program, types, service),
+                    }));
+                    withVisibility(Visibility.All, () => {
+                        for (const type of unreachedTypes())
+                            types.expressionFor(type);
+                    });
+                    for (const { type, at, ignore, binary } of publishedComponents(context.program)) {
+                        withVisibility(at, () => withMetadataAnnotationsIgnored(ignore, () => withMultipartBinary(binary, () => types.declare(type))));
+                    }
+                    types.refuse(registry.refusedNames());
+                    return {
+                        requests: renderRequestTypes(entries, responses, types),
+                        assertions: renderWireAssertions(registry, types, entries, responses, resolved.contractsPackage),
+                    };
                 });
+                writes.push({
+                    path: resolvePath(resolved.contractsOutputDir, "requests.gen.ts"),
+                    content: requests,
+                });
+                writes.push({
+                    path: resolvePath(resolved.contractsOutputDir, "vocabularies.gen.ts"),
+                    content: renderVocabularies(vocabularies),
+                });
+                if (assertions !== undefined) {
+                    writes.push({
+                        path: resolvePath(outputDir, "wire-contract.gen.ts"),
+                        content: assertions,
+                    });
+                }
             }
+            // 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,
+            });
+        }
+        finally {
+            restoreView();
         }
-        // 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 });
+        for (const write of writes)
+            await emitFile(context.program, write);
     }
     return emitted;
 }