typespec-http-zod 0.25.1 → 0.26.0

package/dist/src/api.js

@@ -1,11 +1,12 @@
-import { emitFile, getDoc, getDocData, getEncode, getLocationContext, getSummary, isErrorModel, isNeverType, isVoidType, navigateProgram, NoTarget, resolvePath, } from "@typespec/compiler";
-import { getAuthenticationForOperation, isStatusCode, resolveRequestVisibility, Visibility, } from "@typespec/http";
+import { emitFile, getDoc, getDocData, getEncode, getLocationContext, getSummary, isErrorModel, isNeverType, isVoidType, navigateProgram, NoTarget, resolveEncodedName, resolvePath, } from "@typespec/compiler";
+import { getAuthenticationForOperation, resolveRequestVisibility, Visibility, } from "@typespec/http";
 import { getOperationId, resolveOperationId } from "@typespec/openapi";
 import { reportDiagnostic } from "./lib.js";
 import { SchemaRegistry, TypeRegistry } from "./registry.js";
 import { typeToTs } from "./types.js";
 import { resolveStreamModule, streamedTypeOf, withStreamModule } from "./streams.js";
 import { resolveVersioningModule, serviceSnapshots } from "./versioning.js";
+import { EXPLODED_QUERY_SOURCE, explodedQueryCall, needsExpansionDecoding, routeTemplateOf, URI_EXPANSION_SOURCE, uriExpansionCall, } from "./uri-template.js";
 import { collectExternalImports, noteDeclaredVocabularies, noteKeyVocabularies, objectKey, wireKindOf, withContractsPackage, withSealedObjects, withVisibility, } from "./zod.js";
 /**
  * `typespec-http-zod` - Zod validators and framework-free contract types from a TypeSpec HTTP
@@ -273,97 +274,77 @@ function statusKeysOf(program, response) {
     }
     return keys;
 }
-/** Whether a document status key describes a SUCCESS, so the success arms already carry it. */
-function isSuccessKey(status) {
-    return status === "2XX" || (typeof status === "number" && status >= 200 && status < 300);
-}
-/**
- * Every FAILURE arm the operation declares, each with the schema for ITS OWN body.
- *
- * **None of these reached the generated output at all, and a census is the proof.** Measured on one
- * service, the document declared `200`x9, `201`x3, `202`x1, `401`x1 and `default`x2, and only the
- * first three were emitted. So the schema for a failure never arrived, and no application could have
- * checked what it sends when something goes wrong even if it wanted to.
- *
- * **Then every arm that did arrive carried the SERVICE-WIDE error schema.** The spike declares
- * `@error model WebhookUnauthorized { ...ProblemDetails; @statusCode 401 }` and openapi3 publishes
- * the 401 as `$ref: WebhookUnauthorized` while we answered with `problemDetailsSchema`. The shapes
- * were identical there, so nothing was mis-validated - but the component the document names for that
- * response had no declaration at all.
- *
- * **`"default"` used to be the one arm with no body of its own**, filled in downstream from the
- * service-wide schema. That was backwards: a catch-all response declares a body like any other
- * response, and `response/status-code-range` gives two operations whose `default` is a DIFFERENT
- * model from every other failure they declare. Reading each response's own body answers all three at
- * once, and is why the emitter no longer needs to believe a service has one error shape.
- *
- * Arms come out in the order OpenAPI resolves them - exact codes, then ranges, then the catch-all -
- * so a consumer scanning for the first match applies the precedence the specification states.
- */
 /**
- * The headers each response status declares, keyed by the status the arm answers with.
+ * Every response the operation declares, one per status key, in OpenAPI's precedence order.
+ *
+ * **Each response's own body, headers and media types, and nothing borrowed from another.** The
+ * failure arms used to be collected here separately from the success, and before that every failure
+ * carried the service-wide error schema: `@error model WebhookUnauthorized { ...ProblemDetails;
+ * @statusCode 401 }` is published as `$ref: WebhookUnauthorized`, and `response/status-code-range`
+ * gives two operations whose `default` is a different model from every other failure they declare.
+ * Reading each status's own response answers both, and is why nothing here believes a service has
+ * one error shape or one success shape.
+ *
+ * Where two responses resolve to the same status the first body wins, which is what the document
+ * does, and media types and headers are the union across them.
  *
- * **Read from `@typespec/http`'s own resolution**, which separates a response's headers from its
- * body and gives each one under its WIRE name with the declaring property behind it. Deriving either
- * name any other way would be a second spelling of a fact the compiler already resolved.
+ * Call inside `withVisibility(program, Visibility.Read, ...)`: a response is read at `Read`, and
+ * resolving it under a request visibility declares components under the wrong suffix.
  */
-function responseHeadersOf(program, operation) {
+function responsesOf(program, operation, registry) {
     const byStatus = new Map();
     for (const response of operation.responses) {
-        const status = response.statusCodes;
-        if (typeof status !== "number")
-            continue;
-        const headers = [];
-        for (const content of response.responses) {
-            for (const [name, property] of Object.entries(content.headers ?? {})) {
-                if (!headers.some((existing) => existing.name === name)) {
-                    /**
-                     * **The TYPE too, because a handler has to be able to SET this.** A `@header`
-                     * property is stripped from the body schema - correctly, it is not body - so a server
-                     * emitter has to put it back into the type a handler returns, and it cannot do that
-                     * from a name alone. Measured before this existed: an arm naming `contentType` and
-                     * `metadata` against a handler declared `Awaitable<Result<void>>`.
-                     */
-                    headers.push({ name, property: property.name, type: typeToTs(program, property.type) });
+        for (const status of statusKeysOf(program, response)) {
+            const key = String(status);
+            const entry = byStatus.get(key) ?? {
+                status,
+                body: undefined,
+                contentTypes: new Set(),
+                headers: [],
+                streamed: false,
+            };
+            for (const content of response.responses) {
+                if (entry.body === undefined && content.body?.bodyKind === "single") {
+                    entry.body = bodyTypeOf(content.body.type);
+                }
+                for (const contentType of content.body?.contentTypes ?? []) {
+                    entry.contentTypes.add(contentType);
+                }
+                for (const [name, property] of Object.entries(content.headers ?? {})) {
+                    if (entry.headers.some((existing) => existing.name === name))
+                        continue;
+                    entry.headers.push({
+                        name,
+                        type: typeToTs(program, property.type),
+                        optional: property.optional,
+                    });
                 }
             }
-        }
-        if (headers.length === 0)
-            continue;
-        const existing = byStatus.get(status) ?? [];
-        byStatus.set(status, [
-            ...existing,
-            ...headers.filter((h) => !existing.some((e) => e.name === h.name)),
-        ]);
-    }
-    return [...byStatus].map(([status, headers]) => ({ status, headers }));
-}
-/** The media types each numeric response status offers, from the compiler's own resolution. */
-function responseMediaTypesOf(operation) {
-    const byStatus = new Map();
-    for (const response of operation.responses) {
-        const status = response.statusCodes;
-        if (typeof status !== "number")
-            continue;
-        const types = responseContentTypesOf(operation, status);
-        if (types.length === 0)
-            continue;
-        byStatus.set(status, types);
-    }
-    return [...byStatus].map(([status, contentTypes]) => ({ status, contentTypes }));
-}
-function errorArmsOf(program, operation, registry) {
-    const arms = new Map();
-    for (const response of operation.responses) {
-        for (const status of statusKeysOf(program, response)) {
-            if (isSuccessKey(status) || arms.has(status))
-                continue;
-            arms.set(status, bodySchemaOf(response, registry));
+            if (streamedTypeOf(program, response.type) !== undefined)
+                entry.streamed = true;
+            byStatus.set(key, entry);
         }
     }
-    return [...arms]
-        .map(([status, schema]) => ({ status, schema }))
-        .toSorted((a, b) => statusPrecedenceOf(a.status) - statusPrecedenceOf(b.status));
+    return [...byStatus.values()]
+        .map((entry) => {
+        const contentTypes = [...entry.contentTypes];
+        const binary = entry.body !== undefined && isBinaryPart(entry.body) && isRawBinaryMediaType(contentTypes);
+        return {
+            status: entry.status,
+            schema: entry.body === undefined
+                ? undefined
+                : binary
+                    ? "z.unknown()"
+                    : registry.expressionFor(entry.body),
+            contentTypes,
+            headers: entry.headers,
+            binary,
+            streamed: entry.streamed,
+            textual: entry.body !== undefined && isStringType(entry.body),
+        };
+    })
+        .toSorted((a, b) => statusPrecedenceOf(a.status) - statusPrecedenceOf(b.status) ||
+        statusOrderOf(a.status) - statusOrderOf(b.status));
 }
 /**
  * Where an arm sits in OpenAPI's own precedence order.
@@ -380,21 +361,40 @@ function statusPrecedenceOf(status) {
         return 2;
     return typeof status === "number" ? 0 : 1;
 }
-/** A response's own body, as an emitted Zod expression - `undefined` where it declares none. */
-function bodySchemaOf(response, registry) {
-    for (const content of response.responses) {
-        if (content.body?.bodyKind !== "single")
-            continue;
-        const type = bodyTypeOf(content.body.type);
-        if (type !== undefined)
-            return registry.expressionFor(type);
+/**
+ * Whether a type's values are strings: `string` or a scalar built on it, a string literal or template,
+ * or a union of those.
+ *
+ * Read from the type rather than from the emitted schema, which would be a decision made by matching
+ * generated text - `z.iso.datetime()` is a string and does not begin with `z.string`.
+ */
+function isStringType(type) {
+    switch (type.kind) {
+        case "String":
+        case "StringTemplate":
+            return true;
+        case "Scalar":
+            for (let scalar = type; scalar !== undefined; scalar = scalar.baseScalar) {
+                if (scalar.name === "string")
+                    return true;
+            }
+            return false;
+        case "Union":
+            return [...type.variants.values()].every((variant) => isStringType(variant.type));
+        default:
+            return false;
     }
-    return undefined;
+}
+/** Ascending within one precedence class, so the order does not depend on declaration order. */
+function statusOrderOf(status) {
+    if (typeof status === "number")
+        return status;
+    return status === "default" ? 0 : Number(status.charAt(0));
 }
 /**
  * Everything the document says about authenticating an operation, read ONCE.
  *
- * **`scopes` and `noAuth` were two lossy projections of this, each with its own read of the same
+ * **`scopes` and a boolean `noAuth` were two lossy projections of this, each with its own read of the same
  * fact.** A flat scope union cannot say which scheme demanded what, so an emitter that wanted the
  * gate the document actually publishes had to call `getAuthenticationForOperation` a third time and
  * rebuild the requirements itself -- which is what both server emitters were doing, in two
@@ -406,7 +406,6 @@ function bodySchemaOf(response, registry) {
 function authenticationFor(program, operation) {
     const options = getAuthenticationForOperation(program, operation.operation)?.options ?? [];
     const security = [];
-    let noAuth = false;
     for (const option of options) {
         const requirement = {};
         let anonymous = false;
@@ -418,7 +417,6 @@ function authenticationFor(program, operation) {
              */
             if (scheme.type === "noAuth") {
                 anonymous = true;
-                noAuth = true;
                 continue;
             }
             /** Scopes belong to the flows of an OAuth2 scheme; every other kind has none. */
@@ -427,13 +425,24 @@ function authenticationFor(program, operation) {
                     ? [...new Set(scheme.flows.flatMap((flow) => flow.scopes.map((scope) => scope.value)))]
                     : [];
         }
-        if (anonymous && Object.keys(requirement).length === 0)
-            continue;
-        if (Object.keys(requirement).length > 0)
+        /**
+         * **An option that needs nothing is published as `{}`, and kept.** `NoAuth | X` is
+         * `security: [{}, { X: [] }]` in the document `@typespec/openapi3` writes from the same program,
+         * and `{}` is the requirement every caller satisfies. Dropping it published `[{ X: [] }]`, a
+         * contract that refuses the anonymous caller the document accepts; typespec-hono had carried a
+         * corrected copy of this rule of its own because this one was wrong.
+         */
+        if (anonymous || Object.keys(requirement).length > 0)
             security.push(requirement);
     }
     const scopes = [...new Set(security.flatMap((requirement) => Object.values(requirement).flat()))];
-    return { security, scopes, noAuth };
+    const anonymous = security.some((requirement) => Object.keys(requirement).length === 0);
+    const real = security.some((requirement) => Object.keys(requirement).length > 0);
+    return {
+        security,
+        scopes,
+        authentication: !real ? "none" : anonymous ? "optional" : "required",
+    };
 }
 /**
  * The body every `@error` response in the service declares, when they all declare the same one.
@@ -591,70 +600,6 @@ function elementKindOf(program, type) {
 function isArrayType(type) {
     return type.kind === "Model" && type.indexer?.key.name === "integer";
 }
-/**
- * How to choose between an operation's two success statuses, read from the declared arms.
- *
- * **A discriminator, not a trial-parse.** "Try the 200 schema, and if it fails use the 202" is the
- * banned fallback wearing a different hat: a genuine validation failure on the first arm would be
- * reported as the second arm's shape. Each arm pins a **required literal** property instead -
- * `awaiting: true` on the accepted one - and a consumer reads that one property.
- *
- * This replaces hand-written per-operation closures, which existed only because a spec declaring the
- * SAME body model for both statuses could not say which was which.
- */
-function statusDiscriminatorOf(operation, statuses) {
-    if (statuses.length < 2)
-        return undefined;
-    for (const status of statuses) {
-        const body = successBodyOf(operation, status);
-        if (body?.kind !== "Model")
-            continue;
-        for (const [name, property] of body.properties) {
-            // The OTHER arm carries the same property as optional; a required literal is the mark.
-            if (property.optional)
-                continue;
-            if (property.type.kind === "Boolean" || property.type.kind === "String") {
-                return { property: name, value: property.type.value, status };
-            }
-        }
-    }
-    return undefined;
-}
-/**
- * How a handler says WHICH success status it means, when the spec declares more than one.
- *
- * **The `@statusCode` property is the selector, and it is the one the spec already wrote.**
- * `model Created { @statusCode statusCode: 200 | 201; @body body: Item }` declares both statuses and
- * names the property that chooses between them, so nothing has to be inferred from the body's shape.
- *
- * That inference is what {@link statusDiscriminatorOf} does, and it needs a required literal property
- * on one of the bodies. Measured across the whole conformance corpus: it fires ZERO times, so before
- * this the second arm had never been emitted by any spec at all - `armFor` could not select a status
- * that was never written. Both remain: a discriminator still serves two DIFFERENT response models,
- * this serves one model declaring a union of statuses.
- *
- * All statuses of such a model share one body by construction - it is one model - so every arm
- * carries the same schema and only the status and the selector value differ.
- */
-function statusSelectorOf(program, operation, statuses) {
-    if (statuses.length < 2)
-        return undefined;
-    for (const response of operation.responses) {
-        const type = response.type;
-        if (type === undefined || type.kind !== "Model")
-            continue;
-        for (const [name, property] of type.properties) {
-            if (isStatusCode(program, property))
-                return { property: name, statuses };
-        }
-    }
-    return undefined;
-}
-/** The emitted schema for a specific success status, used for the second arm of a dual-status op. */
-function alternateSchemaFor(operation, status, registry) {
-    const body = successBodyOf(operation, status);
-    return body === undefined ? undefined : registry.expressionFor(body);
-}
 /**
  * The Zod for a **multipart** request body, built from its parts.
  *
@@ -701,16 +646,26 @@ function multipartTsOf(body, registry) {
     });
     return entries.length === 0 ? "{}" : `{\n${entries.join("\n")}\n}`;
 }
-function multipartSchemaOf(body, registry) {
+function multipartSchemaOf(program, body, registry) {
     const entries = body.parts.map((part) => {
         const type = part.body?.type;
+        /**
+         * **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
+         * `0.5`, and text that is not a well-formed number is passed on unchanged to fail against the
+         * schema the document publishes. `c.req.parseBody()` hands a text part over as a string, so
+         * `z.number()` alone refused every conformant request; measured on `@typespec/http-specs`
+         * `payload/multipart/non-string-float`, a 400 for the request the scenario documents.
+         */
         const inner = type === undefined
             ? "z.unknown()"
             : isFilePart(type)
                 ? `z.unknown().refine(${MULTIPART_FILE_REFINEMENT})`
                 : isBinaryPart(type)
                     ? "z.unknown()"
-                    : registry.expressionFor(type);
+                    : 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
@@ -782,6 +737,27 @@ function isFilePart(type) {
     return false;
 }
 /** `bytes`, or a model built on `File` - the parts openapi3 publishes as an empty schema. */
+/**
+ * Whether a multipart part travels as JSON: every media type `@typespec/http` resolves for it is a
+ * JSON one. That is `application/json` for a model or array part, and whatever an explicit
+ * `@header contentType` names for a part that declares one.
+ */
+function isJsonPart(part) {
+    const contentTypes = part.body?.contentTypes ?? [];
+    return (contentTypes.length > 0 &&
+        contentTypes.every((contentType) => /^application\/(?:[\w.+-]+\+)?json$/i.test(contentType)));
+}
+/**
+ * **A JSON part is decoded from the JSON text a form carries** before the document's schema applies.
+ * A client writes the part as text with `Content-Type: application/json` and no filename, so
+ * `c.req.parseBody()` hands over a string; the schema alone refused every such request with
+ * `expected object, received string`. Text that is not JSON is an issue of its own rather than a
+ * 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.
+ */
+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) {
     if (type.kind === "Scalar") {
         for (let scalar = type; scalar !== undefined; scalar = scalar.baseScalar) {
@@ -996,9 +972,16 @@ function mediaTypeDecoded(declared) {
     const normalise = values.every((value) => value === value.toLowerCase()) ? ".toLowerCase()" : "";
     return `z.preprocess((raw) => (typeof raw === "string" ? (raw.split(";")[0] ?? "").trim()${normalise} : raw), ${declared})`;
 }
-function parameterSchemasOf(program, operation, registry) {
+function parameterSchemasOf(program, operation, registry, segments, 
+/** The names of a query string written into the route itself, which no parameter may gather. */
+literalQueryNames) {
     const byTarget = {};
     let accept;
+    /** Form-exploded records and models, gathered back under their names around the query object. */
+    const gathered = [];
+    const queryNames = operation.parameters.parameters
+        .filter((parameter) => parameter.type === "query")
+        .map((parameter) => parameter.name);
     for (const parameter of operation.parameters.parameters) {
         if (parameter.type !== "path" && parameter.type !== "query" && parameter.type !== "header") {
             continue;
@@ -1046,11 +1029,54 @@ function parameterSchemasOf(program, operation, registry) {
          * occurrences arrive already an array and pass through untouched, exactly as the delimiter
          * arm leaves a pre-split value alone.
          */
-        const expression = isExplodedCollection(parameter)
+        const boxedOrSplit = isExplodedCollection(parameter)
             ? `z.preprocess((raw) => (typeof raw === "string" ? [raw] : raw), ${decoded})`
             : delimiter === undefined
                 ? decoded
                 : `z.preprocess((raw) => (typeof raw === "string" ? raw.split(${JSON.stringify(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(parameter.param.type);
+        const values = recordValuesOf(program, parameter.param.type);
+        let expression = boxedOrSplit;
+        if (parameter.type === "path") {
+            const segment = segments.find((candidate) => candidate.kind === "expression" && candidate.parameter === parameter.name);
+            if (segment !== undefined && needsExpansionDecoding(segment, shape)) {
+                expression = `z.preprocess(${uriExpansionCall({ ...segment, name: parameter.name, shape, values })}, ${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.
+                 */
+                const model = parameter.param.type.kind === "Model" && parameter.param.type.indexer === undefined
+                    ? parameter.param.type
+                    : undefined;
+                const properties = model === undefined ? [] : modelPropertiesOf(model);
+                gathered.push(explodedQueryCall({
+                    name: parameter.name,
+                    others: [...queryNames.filter((name) => name !== parameter.name), ...literalQueryNames],
+                    keys: model === undefined
+                        ? undefined
+                        : properties.map((property) => resolveEncodedName(program, property, "application/json")),
+                    numbers: properties
+                        .filter((property) => wireKindOf(program, property.type) === "number")
+                        .map((property) => resolveEncodedName(program, property, "application/json")),
+                    booleans: properties
+                        .filter((property) => wireKindOf(program, property.type) === "boolean")
+                        .map((property) => resolveEncodedName(program, property, "application/json")),
+                    values,
+                }));
+            }
+            else {
+                expression = `z.preprocess(${uriExpansionCall({ prefix: "", suffix: "", operator: "", name: parameter.name, explode: false, shape, values })}, ${decoded})`;
+            }
+        }
         const entry = `\t${objectKey(parameter.name)}: ${expression},`;
         (byTarget[parameter.type] ??= []).push(entry);
         /**
@@ -1074,24 +1100,49 @@ function parameterSchemasOf(program, operation, registry) {
         const entries = byTarget[target];
         return entries === undefined ? undefined : `z.object({\n${entries.join("\n")}\n})`;
     };
+    const query = shape("query");
     return {
         path: shape("path"),
-        query: shape("query"),
+        query: query === undefined
+            ? undefined
+            : gathered.reduce((inner, gather) => `z.preprocess(${gather}, ${inner})`, query),
+        queryFields: query,
         header: shape("header"),
         negotiatedHeader: shape("header-without-accept"),
         accept,
     };
 }
+/** 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);
+    }
+    return chain.flatMap((current) => [...current.properties.values()]);
+}
 export function collectRoutes(program, registry, service) {
     const routes = [];
     {
         for (const operation of service.operations) {
+            /**
+             * **Every operation is a route, whatever its responses are.** This used to require an exact
+             * 2xx or 3xx, which dropped an operation whose only success was a `2XX` range without a word
+             * - the same silent shape as the 282 bodyless operations an earlier rule dropped, because a
+             * range is not a number. A bodyless success is ordinary HTTP, and so is a ranged one.
+             */
             const statusCode = successStatusOf(operation);
-            if (statusCode === undefined)
-                continue;
-            // No body is a legitimate success - see `EmittedRoute.responseSchema`. Skipping here is what
-            // dropped 282 operations across the conformance corpus without a word.
-            const responseType = successBodyOf(operation, statusCode);
             const requestType = requestBodyOf(operation);
             /**
              * **A streamed operation's EVENT payloads are not reachable from its body.**
@@ -1110,9 +1161,6 @@ export function collectRoutes(program, registry, service) {
             // `@requestVisibility` when the operation states one, otherwise the verb's default - the
             // same resolution `@typespec/openapi3` performs before emitting a request schema.
             const requestVisibility = resolveRequestVisibility(program, operation.operation, operation.verb);
-            const statusCodes = successStatusesOf(operation);
-            const discriminator = statusDiscriminatorOf(operation, statusCodes);
-            const statusSelector = statusSelectorOf(program, operation, statusCodes);
             /**
              * A `bytes` body means the BYTES are the contract.
              *
@@ -1158,11 +1206,36 @@ export function collectRoutes(program, registry, service) {
              * `multipartTsOf`, both recorded above.
              */
             const optionalMultipartBody = bodyParameter?.bodyKind === "multipart" && optionalBody;
+            /**
+             * **A body that is not a MODEL has no properties to merge, and merging it anyway lost it.**
+             *
+             * `@body body: string` emitted a handler input of `Record<string, never>` and a call site of
+             * `{}`: the server validated the body and then never handed it to the handler, silently, from
+             * a compile that reported success. `@body body: SomeEnum` was the same rule failing loudly,
+             * `TS2698: Spread types may only be created from object types`, which is what
+             * `payload/media-type`, `type/enum/*`, `type/scalar` and `versioning/returnTypeChangedFrom`
+             * had been pinned on in the conformance corpus.
+             *
+             * A scalar, an enum, a union or a literal body is therefore NAMED, which is the treatment an
+             * indexed or optional body already gets and for the same reason: the merge cannot express it.
+             *
+             * **Except a `bytes` body**, which {@link EmittedRoute.rawBodyProperty} already names, and
+             * naming it twice would put the same value under two keys.
+             */
+            const unmergeableBody = requestType !== undefined && requestType.kind !== "Model" && rawBodyProperty === undefined;
             const bodyProperty = (requestType?.kind === "Model" && (requestType.indexer !== undefined || optionalBody)) ||
-                optionalMultipartBody
+                optionalMultipartBody ||
+                unmergeableBody
                 ? (bodyParameter?.property?.name ?? "body")
                 : undefined;
             const authentication = authenticationFor(program, operation);
+            const template = routeTemplateOf(operation.uriTemplate, operation.parameters.parameters
+                .filter((parameter) => parameter.type === "path")
+                .map((parameter) => ({
+                name: parameter.name,
+                optional: parameter.param.optional,
+                reserved: parameter.type === "path" && parameter.allowReserved,
+            })));
             routes.push({
                 operationId: operationIdOf(program, operation.operation),
                 verb: operation.verb.toUpperCase(),
@@ -1188,10 +1261,16 @@ export function collectRoutes(program, registry, service) {
                 reservedPathParameters: operation.parameters.parameters
                     .filter((parameter) => parameter.type === "path" && parameter.allowReserved)
                     .map((parameter) => parameter.name),
-                statusCode,
-                statusCodes,
-                responseContentTypes: responseContentTypesOf(operation, statusCode),
+                pathSegments: template.segments,
+                literalQuery: template.literalQuery,
+                responseContentTypes: statusCode === undefined ? [] : responseContentTypesOf(operation, statusCode),
                 requestContentTypes: [...(operation.parameters.body?.contentTypes ?? [])],
+                // `isRawBinaryMediaType` is "every declared type is non-JSON", which is the same question
+                // here: a string body under `application/json` IS json, and its reader is the JSON one.
+                requestTextual: requestType !== undefined &&
+                    rawBodyProperty === undefined &&
+                    isStringType(requestType) &&
+                    isRawBinaryMediaType([...(operation.parameters.body?.contentTypes ?? [])]),
                 /**
                  * `@summary` first, `@doc` as the fallback.
                  *
@@ -1213,56 +1292,34 @@ export function collectRoutes(program, registry, service) {
                     // such route mounted with nothing checking the request at all.
                     const parameterBody = operation.parameters.body;
                     if (parameterBody?.bodyKind === "multipart") {
-                        return multipartSchemaOf(parameterBody, registry);
+                        return multipartSchemaOf(program, parameterBody, registry);
                     }
                     return requestType === undefined ? undefined : registry.expressionFor(requestType);
                 }),
                 ...(() => {
-                    const split = withVisibility(program, requestVisibility, () => parameterSchemasOf(program, operation, registry));
+                    const split = withVisibility(program, requestVisibility, () => parameterSchemasOf(program, operation, registry, template.segments, template.literalQuery.map(([name]) => name)));
                     return {
                         pathSchema: split.path,
                         querySchema: split.query,
+                        queryFieldsSchema: split.queryFields,
                         headerSchema: split.header,
                         negotiatedHeaderSchema: split.negotiatedHeader,
                         accept: split.accept,
                     };
                 })(),
-                responseSchema: responseType === undefined
-                    ? undefined
-                    : withVisibility(program, Visibility.Read, () => 
-                    /**
-                     * A raw binary body is `z.unknown()`, matching what a binary multipart part
-                     * already emits and what the document actually asserts - see
-                     * {@link isRawBinaryMediaType}.
-                     */
-                    isBinaryPart(responseType) &&
-                        isRawBinaryMediaType(responseContentTypesOf(operation, statusCode))
-                        ? "z.unknown()"
-                        : registry.expressionFor(responseType)),
+                /**
+                 * Read at `Visibility.Read`, as openapi3 reads a response, and after the request walks so
+                 * declarations keep the order they had. Resolving responses under the ambient request
+                 * visibility declared six components under the wrong suffix - measured:
+                 * type/model/visibility gained six divergences.
+                 */
+                responses: withVisibility(program, Visibility.Read, () => responsesOf(program, operation, registry)),
                 rawBodyProperty,
                 bodyProperty,
                 optionalBody,
-                // Responses are read at Visibility.Read, exactly as the success body above is. Resolving
-                // them under the ambient request visibility declared six components under the wrong
-                // suffix - measured: type/model/visibility gained six divergences.
-                errorArms: withVisibility(program, Visibility.Read, () => errorArmsOf(program, operation, registry)),
-                responseHeaders: responseHeadersOf(program, operation),
-                responseMediaTypes: responseMediaTypesOf(operation),
                 scopes: authentication.scopes,
                 security: authentication.security,
-                noAuth: authentication.noAuth,
-                statusBy: discriminator,
-                statusSelector,
-                /**
-                 * **Each arm is validated against its OWN shape.**
-                 *
-                 * A consumer checks its value against the arm's schema, and with one schema
-                 * for two statuses the acknowledged response was checked against the resolved arm's
-                 * shape - a 502 on a perfectly good 202.
-                 */
-                alternateResponseSchema: discriminator === undefined
-                    ? undefined
-                    : alternateSchemaFor(operation, discriminator.status, registry),
+                authentication: authentication.authentication,
             });
         }
     }
@@ -1344,7 +1401,7 @@ function renderExternalImports(externals, ...bodies) {
 function compiled(expression, on) {
     return on ? `z.compile(${expression})` : expression;
 }
-function renderSchemas(registry, externals, routeDeclarations, runtimeModule, compileSchemas) {
+function renderSchemas(registry, externals, routeDeclarations, compileSchemas) {
     const declarations = registry.declarations().map((d) => {
         /**
          * **A declaration on a CYCLE cannot take its type from `z.infer`, because that is the loop.**
@@ -1440,20 +1497,45 @@ function renderSchemas(registry, externals, routeDeclarations, runtimeModule, co
      */
     const usesZod = new Set([...declarations, ...routeDeclarations].join("").match(/[A-Za-z_$][\w$]*/g) ?? []).has("z");
     const parts = [generatedBanner()];
-    if (usesZod)
+    if (usesZod || routeDeclarations.length > 0)
         parts.push('\nimport { z } from "zod";\n');
     /**
-     * A TYPE import, so nothing of this package's survives into the emitted JavaScript.
+     * **The arm shape is declared IN this file, not imported, and that is what lets two emitters share
+     * it.** It used to be `import type { ResponseArm } from <runtime-module>`, the one line of this
+     * file that depended on where a runtime lived. A server emitter and a tool emitter pointed at one
+     * output directory both write `schemas.gen.ts`, and `emitFile` is a silent last-writer-wins, so the
+     * two had to agree on that specifier or the order of `emit:` decided which import survived. With
+     * the shape declared here the file depends on no runtime at all, and `runtime-module` had nothing
+     * left to decide.
      *
-     * The annotation is what makes a misspelled or omitted `schema` a compile error rather than an arm
-     * that silently validates nothing - see the option's own docblock for the measurement. Emitted only
-     * when there are arms to annotate, because an unused import fails the lint a generated file has to
+     * The annotation is still what makes a misspelled or omitted `schema` a compile error rather than
+     * an arm that silently validates nothing. Not exported: the type an application reads an arm
+     * through is `typespec-http-zod/runtime`'s, which is structurally the same. Emitted only where
+     * there are arms to annotate, because an unused declaration fails the lint a generated file has to
      * pass like any other.
      */
+    parts.push(renderExternalImports(externals, [...declarations, ...routeDeclarations].join("")));
+    /**
+     * **The RFC 6570 decoders are declared here, once, and only where a validator calls them**, for the
+     * 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(""));
+    if (referenced.has("uriExpansion"))
+        parts.push(URI_EXPANSION_SOURCE);
+    if (referenced.has("explodedQuery"))
+        parts.push(EXPLODED_QUERY_SOURCE);
     if (routeDeclarations.length > 0) {
-        parts.push(`import type { ResponseArm } from ${JSON.stringify(runtimeModule)};\n`);
+        parts.push(`
+/** One declared response: its status key, its body's schema, its media types and its headers. */
+type ResponseArm = {
+	readonly status: number | "default" | \`\${1 | 2 | 3 | 4 | 5}XX\`;
+	readonly schema: z.ZodType | undefined;
+	readonly contentTypes?: readonly string[];
+	readonly headers?: readonly { readonly name: string; readonly optional: boolean }[];
+};
+`);
     }
-    parts.push(renderExternalImports(externals, [...declarations, ...routeDeclarations].join("")));
     parts.push(declarations.join(""));
     if (routeDeclarations.length > 0)
         parts.push(`\n${routeDeclarations.join("\n")}\n`);
@@ -1542,129 +1624,72 @@ function nameRouteSchemas(routes, compileSchemas) {
         };
         // Order follows the request: what identifies the resource, then what filters it, then its body.
         const path = declare("Path", route.pathSchema);
-        const query = declare("Query", route.querySchema);
+        /**
+         * Where a query group is gathered, its object is declared on its own and the wire validator wraps
+         * that identifier, so both have a name and only the second pipes.
+         */
+        const gathers = route.queryFieldsSchema !== undefined && route.querySchema !== route.queryFieldsSchema;
+        const queryFields = gathers ? declare("QueryFields", route.queryFieldsSchema) : undefined;
+        const query = declare("Query", gathers && queryFields !== undefined && route.queryFieldsSchema !== undefined
+            ? route.querySchema?.replace(route.queryFieldsSchema, queryFields)
+            : route.querySchema);
         const negotiating = shared.has(`${route.verb} ${route.path}`);
         const header = declare("Header", negotiating ? route.negotiatedHeaderSchema : route.headerSchema);
         // A raw body is read as text, never parsed, so it has no validator - the bytes are the contract.
         const body = route.rawBodyProperty === undefined ? declare("Body", route.requestSchema) : undefined;
-        const response = declare("Response", route.responseSchema);
-        const alternateResponse = declare("AlternateResponse", route.alternateResponseSchema);
+        /**
+         * 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.
+         */
+        const declaredBodies = new Map();
+        const arms = route.responses.map((response) => {
+            if (response.schema === undefined)
+                return { status: response.status, schema: undefined };
+            if (!declaredBodies.has(response.schema)) {
+                const suffix = response.status === "default" ? "Default" : String(response.status);
+                declaredBodies.set(response.schema, declare(`Response${suffix}`, response.schema));
+            }
+            return { status: response.status, schema: declaredBodies.get(response.schema) };
+        });
         const responses = schemaConst(route.operationId, "Responses");
-        declarations.push(`export const ${responses} = ${responseArmsOf(route, response, alternateResponse)} satisfies readonly ResponseArm[];`);
+        declarations.push(`export const ${responses} = ${responseArmsOf(route, arms)} satisfies readonly ResponseArm[];`);
         names.set(route.operationId, {
             operationId: route.operationId,
             path,
             query,
+            queryFields: gathers ? queryFields : query,
             header,
             body,
-            response,
-            alternateResponse,
+            arms,
             responses,
         });
     }
     return { names, declarations };
 }
 /**
- * What an operation may answer with, as a literal - each declared status paired with the body the
- * document gives it, in OpenAPI's own precedence order.
+ * What an operation may answer with, as a literal - each declared status with the body, media types
+ * and headers the document gives it, in OpenAPI's own precedence order.
+ *
+ * **Rendered from one record per status, so no arm can shadow another.** The primary success arm and
+ * the failure arms used to be rendered from separate projections and then deduplicated by matching
+ * the emitted text for `status:`, which is how a redirect came to be declared twice and how a
+ * failure arm came to carry no headers while a success arm with the same headers did.
  *
- * **This docblock was orphaned in the source it came from**, sitting above an unrelated function
- * while the one it describes had none. Reattached.
+ * `contentTypes` and `headers` are written only where the document names some, so "none declared"
+ * and "none carried" are the same state rather than two a runtime has to tell apart.
  */
-function responseArmsOf(route, response, alternate) {
-    const arms = [];
-    const primary = response ?? "undefined";
-    /**
-     * The headers this status declares, rendered onto the arm that answers with it.
-     *
-     * Emitted only where there are some: an arm for a response declaring none must not acquire an
-     * empty list, or every `respond` implementation has to tell "none declared" from "none carried".
-     */
-    /**
-     * The media types this status offers.
-     *
-     * **Emitted whenever the document names any, including a single one.** It was emitted only for
-     * several, on the reasoning that one type is what a `respond` already assumes - and that reasoning
-     * was wrong, because it assumed the one type is JSON. A `text/plain` arm and a JSON arm were then
-     * indistinguishable to a generic `respond`: the document knew and the runtime did not, so consumers
-     * restated the media type in their own result envelope to get it back.
-     */
-    const mediaTypesFor = (status) => {
-        const declared = route.responseMediaTypes.find((entry) => entry.status === status)?.contentTypes ?? [];
-        if (declared.length === 0)
-            return "";
-        return `, contentTypes: [${declared.map((t) => JSON.stringify(t)).join(", ")}]`;
-    };
-    const headersFor = (status) => {
-        const declared = route.responseHeaders.find((entry) => entry.status === status)?.headers ?? [];
-        if (declared.length === 0)
-            return "";
-        const rendered = declared
-            .map((h) => `{ name: ${JSON.stringify(h.name)}, property: ${JSON.stringify(h.property)} }`)
-            .join(", ");
-        return `, headers: [${rendered}]`;
-    };
-    if (route.statusSelector !== undefined) {
-        /**
-         * **One arm per declared status, keyed on the property the spec already named.**
-         *
-         * The selector arms come first and the default last, the same order the discriminator below
-         * uses: anything scanning for a match wants the specific ones before the fallback. Every arm
-         * carries the same schema because a `@statusCode` union is ONE model - the statuses differ,
-         * the body does not.
-         */
-        const { property, statuses } = route.statusSelector;
-        for (const status of statuses.filter((candidate) => candidate !== route.statusCode)) {
-            arms.push(`{ status: ${status}, schema: ${primary}${mediaTypesFor(status)}${headersFor(status)}, when: { property: ${JSON.stringify(property)}, value: ${status} } }`);
-        }
-        arms.push(`{ status: ${route.statusCode}, schema: ${primary}${mediaTypesFor(route.statusCode)}${headersFor(route.statusCode)} }`);
-    }
-    else if (route.statusBy === undefined) {
-        arms.push(`{ status: ${route.statusCode}, schema: ${primary}${mediaTypesFor(route.statusCode)}${headersFor(route.statusCode)} }`);
-    }
-    else {
-        const alternateSchema = alternate ?? "undefined";
-        const { property, value, status } = route.statusBy;
-        arms.push(`{ status: ${status}, schema: ${alternateSchema}${mediaTypesFor(status)}${headersFor(status)}, when: { property: ${JSON.stringify(property)}, value: ${JSON.stringify(value)} } }`, `{ status: ${route.statusCode}, schema: ${primary}${mediaTypesFor(route.statusCode)}${headersFor(route.statusCode)} }`);
-    }
-    /**
-     * The failure arms, which used to be dropped entirely.
-     *
-     * **The document declares what an error body looks like and the server never passed it on**, so
-     * `respond` could not check what it sends on failure even in principle.
-     *
-     * **This used to fall back to the service-wide error schema, and the fallback was the defect.**
-     * `arm.schema ?? errorSchema` was reached by every arm the emitter could not resolve a body for -
-     * which, while `"default"` was deliberately given none, meant every catch-all in every service
-     * answered with whichever shape `errorBodyOf` had settled on rather than the one its own response
-     * declares. Each arm resolves its own body now, so an arm with no schema is a response the document
-     * says carries no body, and saying `undefined` is the truthful answer rather than a guess.
-     */
-    /**
-     * **An error arm whose status the primary arm already answers is dropped, primary winning.**
-     *
-     * `errorArmsOf` excludes 2xx from the failure arms, so widening the primary to include 3xx made a
-     * redirect BOTH: `[{ status: 302, schema: undefined, headers: [...] }, { status: 302, schema:
-     * undefined }]`, two arms for one status where the second shadows the first's headers for anything
-     * scanning past the first match.
-     *
-     * Widening `isSuccessKey` to match would be wrong in the other direction: an operation declaring a
-     * 200 AND a 302 has 200 as its primary, so the 302 must stay a failure arm to be emitted at all.
-     * Deduplicating here keeps both cases, because it asks what was actually emitted rather than what
-     * might have been.
-     */
-    const emitted = new Set();
-    for (const arm of arms) {
-        const status = /status: ([^,}]+)/.exec(arm)?.[1]?.trim();
-        if (status !== undefined)
-            emitted.add(status);
-    }
-    for (const arm of route.errorArms) {
-        if (emitted.has(String(arm.status)) || emitted.has(JSON.stringify(arm.status)))
-            continue;
-        arms.push(`{ status: ${JSON.stringify(arm.status)}, schema: ${arm.schema ?? "undefined"} }`);
-    }
-    return `[${arms.join(", ")}]`;
+function responseArmsOf(route, arms) {
+    const rendered = route.responses.map((response, index) => {
+        const schema = arms[index]?.schema ?? "undefined";
+        const contentTypes = response.contentTypes.length === 0
+            ? ""
+            : `, contentTypes: [${response.contentTypes.map((type) => JSON.stringify(type)).join(", ")}]`;
+        const headers = response.headers.length === 0
+            ? ""
+            : `, headers: [${response.headers.map((header) => `{ name: ${JSON.stringify(header.name)}, optional: ${header.optional} }`).join(", ")}]`;
+        return `{ status: ${JSON.stringify(response.status)}, schema: ${schema}${contentTypes}${headers} }`;
+    });
+    return `[${rendered.join(", ")}]`;
 }
 const upperFirst = (value) => value.charAt(0).toUpperCase() + value.slice(1);
 /**
@@ -2129,8 +2154,6 @@ ${entries.join("\n")}
 } as const;
 `;
 }
-/** What the generated files import their runtime contract from when nothing says otherwise. */
-export const DEFAULT_RUNTIME_MODULE = "typespec-http-zod/runtime";
 /**
  * Emit this library's artefacts for every `@service` in the program, and hand back what was emitted.
  *
@@ -2185,9 +2208,8 @@ function reportTruncatedDocComments(program) {
         scalar: check,
     });
 }
-export async function emitHttpZod(context, wrapper = {}) {
+export async function emitHttpZod(context) {
     const options = context.options;
-    const defaultRuntimeModule = wrapper.defaultRuntimeModule ?? DEFAULT_RUNTIME_MODULE;
     /**
      * Each service already projected to the version it currently serves - see `versioning.ts`.
      *
@@ -2279,7 +2301,6 @@ export async function emitHttpZod(context, wrapper = {}) {
             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"] ?? [],
-            runtimeModule: perService?.["runtime-module"] ?? options["runtime-module"] ?? defaultRuntimeModule,
             regenerateHint: perService?.["regenerate-hint"] ?? options["regenerate-hint"],
         };
         beginBanner(resolved.regenerateHint);
@@ -2337,7 +2358,7 @@ export async function emitHttpZod(context, wrapper = {}) {
         const { names, declarations } = nameRouteSchemas(routes, resolved.compileSchemas);
         await emitFile(context.program, {
             path: resolvePath(outputDir, "schemas.gen.ts"),
-            content: renderSchemas(registry, externals, declarations, resolved.runtimeModule, resolved.compileSchemas),
+            content: renderSchemas(registry, externals, declarations, resolved.compileSchemas),
         });
         if (resolved.contractsOutputDir !== undefined) {
             const types = new TypeRegistry(context.program);