typespec-http-zod 0.27.0 → 0.29.0

package/dist/src/results.js

@@ -0,0 +1,135 @@
+import { CONTENTLESS_STATUS_CODES, STATUS_CODES } from "./statuses.js";
+import { literal } from "./literal.js";
+/**
+ * **A media type's essence: `type/subtype`, lowercased, with no parameters** (RFC 9110 section
+ * 8.3.1). Two media types are the same type exactly when their essences are equal, so every
+ * comparison of a declared media type is of this. `application/json; charset=utf-8` and
+ * `Application/JSON` were compared as whole strings and read as not JSON: the body became raw text,
+ * and the response an unvalidated string.
+ */
+export function mediaTypeEssenceOf(type) {
+    return (type.split(";")[0] ?? "").trim().toLowerCase();
+}
+/** `application/json` and every `+json` suffix: the media types a body is serialised as JSON for. */
+export function isJsonMediaType(type) {
+    return /^application\/(json|.*\+json)$/.test(mediaTypeEssenceOf(type));
+}
+/**
+ * **A media type whose body is text by its registration**: the `text` top-level type (RFC 2046
+ * section 4.1) and the XML media types, `application/xml` and the `+xml` suffix (RFC 7303).
+ *
+ * **What decides whether a body nothing parses is text or bytes.** A model declared under such a type
+ * has no reader or serialisation this emitter can derive, so it is handed over as the text that
+ * arrived and answered as the text the handler writes. Under any other type, such as
+ * `application/octet-stream` or `application/x-protobuf`, text cannot carry it: decoded as UTF-8,
+ * every byte that is not a valid sequence becomes U+FFFD, so it is bytes instead. JSON is text as
+ * well, and is parsed rather than handed over, so it never reaches this question.
+ */
+export function isTextualMediaType(type) {
+    const essence = mediaTypeEssenceOf(type);
+    return essence.startsWith("text/") || essence === "application/xml" || essence.endsWith("+xml");
+}
+/** A media range such as `image/*`, rather than a type a response can be sent as. */
+export function isMediaRange(mediaType) {
+    return mediaTypeEssenceOf(mediaType).endsWith("/*");
+}
+/**
+ * The type of the `contentType` a result names for a member.
+ *
+ * **A range is typed as the types inside it**: `image/*` is `` `image/${string}` ``, so `text/html`
+ * under it does not compile, and TypeScript still narrows a literal member away from it. Only the
+ * full range is `string`.
+ */
+export function mediaTypeTypeOf(mediaType) {
+    if (!isMediaRange(mediaType))
+        return literal(mediaType);
+    if (mediaType === "*/*")
+        return "string";
+    return `\`${mediaType.slice(0, -1)}\${string}\``;
+}
+/**
+ * Every member an operation's responses declare, in the order the responses are listed.
+ *
+ * `hasBody` says which responses carry a body, because the two kinds of record spell that
+ * differently - an emitted one has a schema, a resolved one has a type.
+ */
+export function resultMembersOf(responses, hasBody) {
+    return responses.flatMap((response, index) => {
+        if (response.contentTypes.length === 0) {
+            return [
+                {
+                    response,
+                    index,
+                    mediaType: undefined,
+                    choosesMediaType: false,
+                    serving: "none",
+                    unvalidated: false,
+                },
+            ];
+        }
+        const choosesMediaType = response.contentTypes.length > 1 || response.contentTypes.some(isMediaRange);
+        return response.contentTypes.map((mediaType) => {
+            const serving = servingOf(response, mediaType, hasBody(response));
+            return {
+                response,
+                index,
+                mediaType,
+                choosesMediaType,
+                serving,
+                unvalidated: serving === "unvalidated" || (serving === "binary" && !response.binary),
+            };
+        });
+    });
+}
+function servingOf(response, mediaType, bodied) {
+    if (!bodied)
+        return "none";
+    if (response.streamed)
+        return "stream";
+    if (response.binary)
+        return "binary";
+    if (isJsonMediaType(mediaType))
+        return "json";
+    /**
+     * **A string body under a non-JSON media type IS the text**, so it is validated and served as is.
+     * Any other body under one - a model as `application/xml` - has no serialisation this emitter can
+     * derive, so it has to come from the application and is served unvalidated: as the text it writes
+     * under a textual media type, and as bytes under any other (see {@link isTextualMediaType}).
+     */
+    if (response.textual)
+        return "text";
+    return isTextualMediaType(mediaType) ? "unvalidated" : "binary";
+}
+/**
+ * The codes a declared response answers with, written out.
+ *
+ * - An exact code is itself.
+ * - A range is its class's codes, less every code declared exactly - OpenAPI resolves an exact code
+ *   before its range, as a server does - and, where it carries a body, less the codes that cannot.
+ * - `default` is every code from `2xx` to `5xx` that nothing else declares, exactly or by range,
+ *   again less the contentless codes where it carries a body. `1xx` is not a result a handler
+ *   returns.
+ *
+ * **Written out rather than as `number`**, because `number` admits `999`, and a client cannot
+ * narrow a result on a status type that admits everything. Empty where nothing is left, which a
+ * caller renders as `never`.
+ */
+export function statusCodesOf(response, responses, hasBody) {
+    const { status } = response;
+    if (typeof status === "number")
+        return [status];
+    const exact = new Set(responses.flatMap((candidate) => typeof candidate.status === "number" ? [candidate.status] : []));
+    const contentless = new Set(hasBody(response) ? CONTENTLESS_STATUS_CODES : []);
+    const classOf = (key) => STATUS_CODES[Number(key.charAt(0))];
+    const candidates = status === "default"
+        ? [2, 3, 4, 5].flatMap((digit) => STATUS_CODES[digit])
+        : classOf(status);
+    const ranged = new Set(status === "default"
+        ? responses.flatMap((candidate) => typeof candidate.status === "string" && candidate.status !== "default"
+            ? classOf(candidate.status)
+            : [])
+        : []);
+    return candidates
+        .filter((code) => !exact.has(code) && !ranged.has(code) && !contentless.has(code))
+        .toSorted((a, b) => a - b);
+}

package/dist/src/statuses.d.ts

@@ -0,0 +1,24 @@
+/**
+ * **The status codes a server can answer with, by class.** A `4XX` range or a `default` response
+ * means "every code in these classes that nothing more specific claims", and a type for such a
+ * result needs those codes spelled out: `number` would admit `999`, and a type that admits a status
+ * no server can send is a type no client can narrow on.
+ *
+ * **One list, owned here, because two server emitters each held a copy.** `typespec-hono` and
+ * `typespec-http-mcp` both typed a ranged or `default` result from their own table, and the contract
+ * types in `requests.gen.ts` need the same one to state a result a backend can hand straight to
+ * either. Three copies of a table that must agree are three tables that will not.
+ *
+ * **Graded outside this package, against Hono's own `http-status.d.ts`,** by the two emitters that
+ * serve through it - an expectation that does not come from the code it grades. A code Hono adds
+ * turns their arm red here first.
+ */
+export declare const STATUS_CODES: {
+    readonly 1: readonly [100, 101, 102, 103];
+    readonly 2: readonly [200, 201, 202, 203, 204, 205, 206, 207, 208, 226];
+    readonly 3: readonly [300, 301, 302, 303, 304, 305, 306, 307, 308];
+    readonly 4: readonly [400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418, 421, 422, 423, 424, 425, 426, 428, 429, 431, 451];
+    readonly 5: readonly [500, 501, 502, 503, 504, 505, 506, 507, 508, 510, 511];
+};
+/** The codes a response cannot carry a body under, per RFC 9110: 101, 204, 205 and 304. */
+export declare const CONTENTLESS_STATUS_CODES: readonly [101, 204, 205, 304];

package/dist/src/statuses.js

@@ -0,0 +1,27 @@
+/**
+ * **The status codes a server can answer with, by class.** A `4XX` range or a `default` response
+ * means "every code in these classes that nothing more specific claims", and a type for such a
+ * result needs those codes spelled out: `number` would admit `999`, and a type that admits a status
+ * no server can send is a type no client can narrow on.
+ *
+ * **One list, owned here, because two server emitters each held a copy.** `typespec-hono` and
+ * `typespec-http-mcp` both typed a ranged or `default` result from their own table, and the contract
+ * types in `requests.gen.ts` need the same one to state a result a backend can hand straight to
+ * either. Three copies of a table that must agree are three tables that will not.
+ *
+ * **Graded outside this package, against Hono's own `http-status.d.ts`,** by the two emitters that
+ * serve through it - an expectation that does not come from the code it grades. A code Hono adds
+ * turns their arm red here first.
+ */
+export const STATUS_CODES = {
+    1: [100, 101, 102, 103],
+    2: [200, 201, 202, 203, 204, 205, 206, 207, 208, 226],
+    3: [300, 301, 302, 303, 304, 305, 306, 307, 308],
+    4: [
+        400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418,
+        421, 422, 423, 424, 425, 426, 428, 429, 431, 451,
+    ],
+    5: [500, 501, 502, 503, 504, 505, 506, 507, 508, 510, 511],
+};
+/** The codes a response cannot carry a body under, per RFC 9110: 101, 204, 205 and 304. */
+export const CONTENTLESS_STATUS_CODES = [101, 204, 205, 304];

package/dist/src/types.js

@@ -1,6 +1,7 @@
-import { getDiscriminatedUnion, getEncode, isNeverType, resolveEncodedName, } from "@typespec/compiler";
+import { getDiscriminatedUnion, isNeverType, resolveEncodedName, } from "@typespec/compiler";
 import { reportDiagnostic } from "./lib.js";
-import { discriminatedSubtypes, effectiveIndexer, inheritedAndOwnProperties, isOptionalAt, isPayloadProperty, objectKey, refusalTarget, withDeclarationSite, } from "./zod.js";
+import { literal } from "./literal.js";
+import { discriminatedSubtypes, effectiveIndexer, emitsDefault, encodedTypeOf, inheritedAndOwnProperties, isOptionalAt, isPayloadProperty, objectKey, refusalTarget, withDeclarationSite, } from "./zod.js";
 /**
  * TypeSpec type -> plain TypeScript type text.
  *
@@ -12,9 +13,10 @@ import { discriminatedSubtypes, effectiveIndexer, inheritedAndOwnProperties, isO
  * importing the other.
  *
  * **It must agree with `zod.ts` exactly**, because the emitted assertion compares them. Every rule
- * here has a counterpart there: `utcDateTime` is a string on both sides, `?` becomes
- * `?: T | undefined` because `exactOptionalPropertyTypes` is on, and a property the document leaves
- * out of `required` is optional here whether its absence is spelled `?` or covered by a default.
+ * here has a counterpart there: `utcDateTime` is a string on both sides, `?` is `?: T` because
+ * `.exactOptional()` refuses an explicit `undefined` and `?: T | undefined` only where `.default()`
+ * accepts one, and a property the document leaves out of `required` is optional here whether its
+ * absence is spelled `?` or covered by a default.
  *
  * **The assertion pairs this walk against `z.input`, the type the validator ACCEPTS**, and not
  * against `z.infer`, which is what it produces. These types are the floor a producer supplies, and
@@ -72,7 +74,7 @@ function refuse(program, type, why, remedy = "") {
 }
 function scalarToTs(program, scalar) {
     // A scalar declaration can carry the encoding itself - see `scalarToZod`.
-    const encoded = getEncode(program, scalar)?.type;
+    const encoded = encodedTypeOf(program, scalar);
     if (encoded !== undefined && encoded !== scalar)
         return scalarToTs(program, encoded);
     let current = scalar;
@@ -101,7 +103,7 @@ function scalarToTs(program, scalar) {
 }
 function enumToTs(target) {
     const values = [...target.members.values()].map((member) => member.value ?? member.name);
-    return values.map((value) => JSON.stringify(value)).join(" | ");
+    return values.map((value) => literal(value)).join(" | ");
 }
 function unionToTs(program, union) {
     /**
@@ -114,7 +116,7 @@ function unionToTs(program, union) {
     if (discriminated !== undefined && discriminated.defaultVariant === undefined) {
         const { envelope, discriminatorPropertyName, envelopePropertyName } = discriminated.options;
         const arms = [...discriminated.variants.entries()].map(([name, variant]) => {
-            const tag = `${objectKey(discriminatorPropertyName)}: ${JSON.stringify(name)};`;
+            const tag = `${objectKey(discriminatorPropertyName)}: ${literal(name)};`;
             const inner = typeToTs(program, variant);
             // No injection: with no envelope the variant declares the discriminator itself, or the union
             // is refused in `zod.ts`. Nothing is added that the document does not publish.
@@ -261,9 +263,14 @@ function modelToTs(program, model) {
  * annotation claims is by construction the type this walk renders for the same property.
  */
 export function propertyTypeToTs(program, property) {
-    // `@encode` changes the wire TYPE, resolved exactly as `zod.ts` resolves it - a property encoded as
-    // a string on one side and an array on the other fails the emitted assertion, and deserves to.
-    const encoded = getEncode(program, property)?.type;
+    /**
+     * **`@encode` changes the wire TYPE, and `encodedTypeOf` is the one rule for when it does.** This
+     * read `getEncode(...).type` directly, so it missed the exception the Zod walk makes: an array
+     * encoding on a QUERY parameter is a style of flattening, not a type, and the validator splits it
+     * back into the declared list. So `WireInputs` said `colors: string` for a pipe-delimited query
+     * whose handler is given `string[]` - two walks of one property, one of them knowing a rule.
+     */
+    const encoded = encodedTypeOf(program, property);
     return typeToTs(program, encoded ?? property.type);
 }
 export function propertyToTs(program, property, wireName) {
@@ -297,21 +304,28 @@ export function propertyToTs(program, property, wireName) {
      * `.default(...)` for it - so the two walks agree without either one restating the rule.
      */
     /**
-     * **`?: T | undefined`, and dropping the `| undefined` was tried in `0.19.0` and reverted.**
+     * **`?: T`, and `?: T | undefined` only where the validator emits `.default(...)`. The contract
+     * type is the validator's INPUT, `z.input`, at every property.**
+     *
+     * `.exactOptional()` refuses `{ note: undefined }` and `.default(v)` accepts it, so those are the
+     * two answers; {@link emitsDefault} says which one this property got. `wire-contract.gen.ts`
+     * compares the two walks with nothing widened, so a disagreement here does not compile.
      *
-     * It looks wrong - JSON has no `undefined`, so a wire type saying `?: T` reads more honest, and
-     * it would make this walk agree with `z.infer<...>` on the schemas side. **Measured, it
-     * breaks the most ordinary handler there is.** `createWidget: (ctx, input) => ok(input)` - return
-     * what you were given - stopped compiling, because what a handler RECEIVES carries
-     * `?: T | undefined` and what it would then have to SUPPLY did not.
+     * **This was `?: T | undefined` for every optional, kept deliberately on three reasons that were
+     * each measured false** once `0.24.0` moved the validator to `.exactOptional()`:
      *
-     * That is the difference from the index signature and from `readonly`, which look like the same
-     * class and are not: removing those two makes MORE values assignable, and removing this one makes
-     * fewer. `{ retiredOn: undefined }` serialises to `{}`, identical to omitting the key, so
-     * permitting it costs the wire nothing and refusing it costs every producer a conditional spread.
+     * - the echo handler `(ctx, input) => ok(input)` broke without it, because what a handler
+     *   received carried `| undefined`. What it receives is `z.infer` of `.exactOptional()` now,
+     *   `?: T`, and the echo compiles;
+     * - `{ note: undefined }` serialises identically to omitting the key. A server checks a body
+     *   before it serialises it: a value typed by `WireOutputs` reached `servedBody` and answered
+     *   500 for a body whose bytes were valid, and across a service binding it is never serialised;
+     * - refusing it costs a producer a conditional spread. That spread infers `{ note?: string }` on
+     *   TypeScript 5.9 and 7.0 and assigns to the exact type, and it is what a producer under
+     *   `exactOptionalPropertyTypes` writes for the handler's own return type anyway.
      *
-     * The two emitted surfaces differ here on purpose, exactly as they do on openness:
-     * `schemas.gen.ts` exports the narrow received view, this walk emits the permissive floor.
+     * Two consumers reported the disagreement independently - one carried a `Loosen<T>` to compare the
+     * two surfaces - and openapi-typescript, `hc` and `z.infer` all spell an optional `?: T`.
      */
     /**
      * **Optional AT THIS POSITION, not merely optional in the declaration.** A PATCH body's properties
@@ -319,9 +333,9 @@ export function propertyToTs(program, property, wireName) {
      * what `propertyToZod` has always consulted. This walk read `property.optional` alone, so an
      * update contract demanded every field while the validator beside it accepted any subset.
      */
-    return property.optional || isOptionalAt(program, property)
-        ? `${key}?: ${value} | undefined;`
-        : `${key}: ${value};`;
+    if (!(property.optional || isOptionalAt(program, property)))
+        return `${key}: ${value};`;
+    return emitsDefault(program, property) ? `${key}?: ${value} | undefined;` : `${key}?: ${value};`;
 }
 /** Installed by the registry so a named model is declared once and referenced everywhere else. */
 let resolveRef = () => undefined;
@@ -356,13 +370,13 @@ export function typeToTsBody(program, type) {
         case "Union":
             return unionToTs(program, type);
         case "String":
-            return JSON.stringify(type.value);
+            return literal(type.value);
         case "Number":
             return String(type.value);
         case "Boolean":
             return String(type.value);
         case "EnumMember":
-            return JSON.stringify(type.value ?? type.name);
+            return literal(type.value ?? type.name);
         // A named union variant is a referable type - `DogKind.Golden`. See the note in `zod.ts`.
         case "UnionVariant":
             return typeToTs(program, type.type);

package/dist/src/uri-template.d.ts

@@ -1,15 +1,3 @@
-/**
- * RFC 6570 URI templates, read for what a server has to mount and what it has to decode.
- *
- * **`HttpOperation.uriTemplate`, never `HttpOperation.path`.** `path` drops every operator, so
- * `array{.param*}`, `array{;param}` and `array{/param}` all become `array{param}`, and a route mounted
- * from it answers 404 to the URL its own contract declares. Measured on `@typespec/http-specs`
- * `routes`: 30 of its mock server's URIs, plus the query-continuation six.
- *
- * `parseUriTemplate` is copied from `@typespec/http` 1.16.0 (`dist/src/uri-template.js`, MIT), which
- * implements it but does not export it, so the template is split exactly as the library that built
- * it splits it.
- */
 /**
  * One `/`-delimited segment of a route, as a server has to mount it.
  *
@@ -103,4 +91,4 @@ export declare function explodedQueryCall(spec: {
  * gathers those keys back under the parameter's name before the query object is validated: a model
  * takes exactly its declared properties, a record every key no other query parameter claims.
  */
-export declare const EXPLODED_QUERY_SOURCE = "\n/** RFC 6570 form expansion of an exploded record or model, gathered back under its parameter. */\nfunction explodedQuery(\n\traw: unknown,\n\tspec: {\n\t\treadonly name: string;\n\t\treadonly others: readonly string[];\n\t\treadonly keys: readonly string[] | null;\n\t\treadonly numbers: readonly string[];\n\t\treadonly booleans: readonly string[];\n\t\treadonly values: \"number\" | \"boolean\" | \"\";\n\t},\n): unknown {\n\tif (raw === null || typeof raw !== \"object\" || Array.isArray(raw) || spec.name in raw) return raw;\n\tconst gathered: Record<string, unknown> = {};\n\tconst rest: Record<string, unknown> = {};\n\tfor (const [key, value] of Object.entries(raw)) {\n\t\tconst own = spec.keys === null ? !spec.others.includes(key) : spec.keys.includes(key);\n\t\tif (!own) {\n\t\t\trest[key] = value;\n\t\t\tcontinue;\n\t\t}\n\t\tconst kind = spec.values !== \"\" ? spec.values : spec.numbers.includes(key) ? \"number\" : spec.booleans.includes(key) ? \"boolean\" : \"\";\n\t\tgathered[key] =\n\t\t\ttypeof value !== \"string\"\n\t\t\t\t? value\n\t\t\t\t: kind === \"number\" && value.trim() !== \"\" && Number.isFinite(Number(value))\n\t\t\t\t\t? Number(value)\n\t\t\t\t\t: kind === \"boolean\" && (value === \"true\" || value === \"false\")\n\t\t\t\t\t\t? value === \"true\"\n\t\t\t\t\t\t: value;\n\t}\n\treturn Object.keys(gathered).length === 0 ? raw : { ...rest, [spec.name]: gathered };\n}\n";
+export declare const EXPLODED_QUERY_SOURCE = "\n/** RFC 6570 form expansion of an exploded record or model, gathered back under its parameter. */\nfunction explodedQuery(\n\traw: unknown,\n\tspec: {\n\t\treadonly name: string;\n\t\treadonly others: readonly string[];\n\t\treadonly keys: readonly string[] | null;\n\t\treadonly numbers: readonly string[];\n\t\treadonly booleans: readonly string[];\n\t\treadonly values: \"number\" | \"boolean\" | \"\";\n\t},\n): unknown {\n\tif (raw === null || typeof raw !== \"object\" || Array.isArray(raw)) return raw;\n\tconst gathered: Record<string, unknown> = {};\n\tconst rest: Record<string, unknown> = {};\n\tfor (const [key, value] of Object.entries(raw)) {\n\t\t// Already gathered only where an OBJECT sits under the name: a query value from the wire is a\n\t\t// string or a list of them, and `{ param: 0 }` expands to `?param=0`.\n\t\tif (key === spec.name && value !== null && typeof value === \"object\" && !Array.isArray(value)) return raw;\n\t\tconst own = spec.keys === null ? !spec.others.includes(key) : spec.keys.includes(key);\n\t\tif (!own) {\n\t\t\trest[key] = value;\n\t\t\tcontinue;\n\t\t}\n\t\tconst kind = spec.values !== \"\" ? spec.values : spec.numbers.includes(key) ? \"number\" : spec.booleans.includes(key) ? \"boolean\" : \"\";\n\t\tgathered[key] =\n\t\t\ttypeof value !== \"string\"\n\t\t\t\t? value\n\t\t\t\t: kind === \"number\" && value.trim() !== \"\" && Number.isFinite(Number(value))\n\t\t\t\t\t? Number(value)\n\t\t\t\t\t: kind === \"boolean\" && (value === \"true\" || value === \"false\")\n\t\t\t\t\t\t? value === \"true\"\n\t\t\t\t\t\t: value;\n\t}\n\treturn Object.keys(gathered).length === 0 ? raw : { ...rest, [spec.name]: gathered };\n}\n";

package/dist/src/uri-template.js

@@ -1,3 +1,4 @@
+import { literal } from "./literal.js";
 /**
  * RFC 6570 URI templates, read for what a server has to mount and what it has to decode.
  *
@@ -128,7 +129,7 @@ export function needsExpansionDecoding(segment, shape) {
  * {@link URI_EXPANSION_SOURCE}, declared once in `schemas.gen.ts` when something calls it.
  */
 export function uriExpansionCall(spec) {
-    return `(raw, ctx) => uriExpansion(raw, ctx, { prefix: ${JSON.stringify(spec.prefix)}, suffix: ${JSON.stringify(spec.suffix)}, operator: ${JSON.stringify(spec.operator)}, name: ${JSON.stringify(spec.name)}, explode: ${spec.explode}, shape: ${JSON.stringify(spec.shape)}, values: ${JSON.stringify(spec.values)} })`;
+    return `(raw, ctx) => uriExpansion(raw, ctx, { prefix: ${literal(spec.prefix)}, suffix: ${literal(spec.suffix)}, operator: ${literal(spec.operator)}, name: ${literal(spec.name)}, explode: ${spec.explode}, shape: ${literal(spec.shape)}, values: ${literal(spec.values)} })`;
 }
 /**
  * **RFC 6570 section 3.2, run backwards.** A router hands over the text of the segment an expression
@@ -209,7 +210,7 @@ function uriExpansion(
  * gatherer itself is {@link EXPLODED_QUERY_SOURCE}.
  */
 export function explodedQueryCall(spec) {
-    return `(raw) => explodedQuery(raw, { name: ${JSON.stringify(spec.name)}, others: ${JSON.stringify(spec.others)}, keys: ${JSON.stringify(spec.keys ?? null)}, numbers: ${JSON.stringify(spec.numbers)}, booleans: ${JSON.stringify(spec.booleans)}, values: ${JSON.stringify(spec.values)} })`;
+    return `(raw) => explodedQuery(raw, { name: ${literal(spec.name)}, others: ${literal(spec.others)}, keys: ${literal(spec.keys ?? null)}, numbers: ${literal(spec.numbers)}, booleans: ${literal(spec.booleans)}, values: ${literal(spec.values)} })`;
 }
 /**
  * **`{?param*}` over a record or a model expands to the object's own keys**, `?a=1&b=2` and
@@ -230,10 +231,13 @@ function explodedQuery(
 		readonly values: "number" | "boolean" | "";
 	},
 ): unknown {
-	if (raw === null || typeof raw !== "object" || Array.isArray(raw) || spec.name in raw) return raw;
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return raw;
 	const gathered: Record<string, unknown> = {};
 	const rest: Record<string, unknown> = {};
 	for (const [key, value] of Object.entries(raw)) {
+		// Already gathered only where an OBJECT sits under the name: a query value from the wire is a
+		// string or a list of them, and \`{ param: 0 }\` expands to \`?param=0\`.
+		if (key === spec.name && value !== null && typeof value === "object" && !Array.isArray(value)) return raw;
 		const own = spec.keys === null ? !spec.others.includes(key) : spec.keys.includes(key);
 		if (!own) {
 			rest[key] = value;

package/dist/src/zod.d.ts

@@ -1,4 +1,4 @@
-import { type Enum, type Model, type ModelProperty, type Program, type Type } from "@typespec/compiler";
+import { type Enum, type Model, type ModelProperty, type Program, type Scalar, type Type } from "@typespec/compiler";
 import { Visibility } from "@typespec/http";
 /**
  * What a walk returns after reporting a refusal.
@@ -75,6 +75,40 @@ export declare function withDeclarationSite<T>(site: Type | undefined, run: () =
  * walked, which does.
  */
 export declare function refusalTarget(type: Type): Type;
+/**
+ * **A doc becomes `.describe()`, which is the one place Zod keeps a description.**
+ *
+ * `@typespec/openapi3` writes every `getDoc` as a JSON Schema `description`, and nothing carried it
+ * into the validators: a surface publishing its input schema FROM them - an MCP server's
+ * `tools/list` - gave a model calling a tool bare patterns and enums with no word on what a field is
+ * for. Measured on one consumer: a tool refused 369 calls and accepted 98, most refusals coming from
+ * the client checking that published schema before it called.
+ *
+ * `.describe()` records the text in `z.globalRegistry`, which is a `globalThis` singleton shared by
+ * every copy of Zod in a process, and both `z.toJSONSchema` and Zod's Standard Schema converter read
+ * it by default. It returns a clone and changes nothing a parse decides.
+ *
+ * **It is always the OUTERMOST call at a position, and never on a bare reference.** Inside
+ * `.nullable()` the text lands in `anyOf[0]` rather than on the property; on an identifier inside
+ * `z.array()` or a union it would clone a declaration that other code finds by identity. So it is
+ * applied where a declaration's body, a property's value or a scalar's schema is finished, and
+ * nowhere else.
+ *
+ * Gated on `undefined` rather than on truthiness, as openapi3's `applyConstraint` is: an empty
+ * `@doc("")` is published as `""`, and so is it here.
+ */
+export declare function described(expression: string, doc: string | undefined): string;
+/**
+ * The description a declared scalar publishes: its own doc, else the nearest one up its `extends`
+ * chain, and never a standard type's.
+ *
+ * Both halves are openapi3's, from `#getSchemaForScalar`: a derived scalar starts from its base's
+ * schema, description included, and overwrites what it declares itself - so `scalar B extends A`
+ * with no doc publishes A's. A standard scalar's description is deleted, because "standard types are
+ * going to be inlined in the spec and we don't want the description of the scalar to show up".
+ * Without that, `string`'s own "A sequence of textual characters." would sit on every `z.string()`.
+ */
+export declare function scalarDocOf(program: Program, scalar: Scalar): string | undefined;
 export declare function withSyntheticDeclarations<T>(hook: (name: string, build: () => string) => string, run: () => T): T;
 /**
  * Every property the model declares, **including the ones it inherits**.
@@ -143,7 +177,21 @@ export declare function objectKey(name: string): string;
  * comment indented differently from the member it documents is the tell that a generator wrote it.
  */
 export declare function jsDocComment(text: string | undefined, indent: string): string;
+export declare function encodedTypeOf(program: Program, target: ModelProperty | Scalar): Scalar | undefined;
 export declare function propertyToZod(program: Program, property: ModelProperty): string;
+/**
+ * **Whether `propertyToZod` emits `.default(...)` for this property, which is exactly whether its
+ * INPUT admits an explicit `undefined`.**
+ *
+ * `.exactOptional()` refuses `{ p: undefined }`; `.default(v)` accepts it and fills `v`. The contract
+ * types in `requests.gen.ts` state the input, so they have to know which of the two this emitted -
+ * and asking this function rather than restating its rule is what keeps the two walks agreeing.
+ * A default on a REQUIRED property emits neither (`default-on-required-property`), and one whose
+ * value cannot be rendered emits no `.default()` (`unsupported-default`); both fall out here.
+ *
+ * Pure: it reports nothing, so the type walk can ask it without duplicating a diagnostic.
+ */
+export declare function emitsDefault(program: Program, property: ModelProperty): boolean;
 export declare function withRefResolver<T>(resolver: (type: Type) => string | undefined, run: () => T): T;
 /** Called by the registry when it hands out the identifier of a declaration that is still open. */
 export declare function noteBackEdge(): void;