typespec-http-zod 0.27.0 → 0.28.0

package/dist/src/constraints.d.ts

@@ -30,7 +30,7 @@ export declare function applyConstraints(program: Program, expression: string, t
  *
  * **`false` means "not proven safe", not "proven dangerous"**, and the rule's wording follows that.
  * `redos-detector` proves safety rather than guessing at danger, so a pattern it cannot decide inside
- * the timeout is judged the same way as one it decides against. Measured over a realistic spread of
+ * the step budget is judged the same way as one it decides against. Measured over a realistic spread of
  * 14 patterns an API would carry: 2 conservative warnings, both on a quantifier nested over an
  * overlapping class, and nothing dangerous missed - including `^\w+([.-]?\w+)*$`, which reads as
  * ordinary and takes **11 seconds** on a 29-character input.

package/dist/src/constraints.js

@@ -1,5 +1,5 @@
 import { getEncode, getMaxItems, getMaxLength, getMaxValue, getMinItems, getMinLength, getMinValue, getMinValueExclusive, getMaxValueExclusive, getPattern, } from "@typespec/compiler";
-import { isSafePattern } from "redos-detector";
+import { defaultMaxSteps, isSafePattern } from "redos-detector";
 import { reportDiagnostic } from "./lib.js";
 /**
  * Constraint decorators -> the Zod modifiers that enforce them.
@@ -87,18 +87,21 @@ function encodesAsString(program, target) {
     return (own ?? scalar)?.type.name === "string";
 }
 /**
- * How long one pattern may be analysed before the answer is "could not prove it".
+ * How much analysis one pattern gets before the answer is "could not prove it": a number of steps.
  *
- * **Bounded, because the analysis is itself exponential in the bad case.** Measured: `^(a|a)+$`
- * takes 1.6 seconds to decide, and a build should not stall on a pattern whose whole problem is that
- * it does too much work. A pattern that cannot be decided inside this is one this emitter cannot
- * certify, which is what the warning says.
+ * **Bounded, because the analysis is itself exponential in the bad case, and bounded in STEPS,
+ * because a verdict must not depend on the machine.** It was 500 ms of wall-clock time, and on a
+ * loaded CI host `^([0-9a-f]{40}|[0-9a-f]{64})$` took 93 to 403 ms and once ran out: the same spec
+ * warned on one build and not the next. A step count is the same everywhere. `redos-detector`'s own
+ * default; measured, `^(a|a)+$` spends it in 1.7 seconds idle and 6 under load, and every ordinary
+ * pattern decides in milliseconds. A pattern that cannot be decided inside it is one this emitter
+ * cannot certify, which is what the warning says.
  */
-const ANALYSIS_TIMEOUT_MS = 500;
+const ANALYSIS_STEPS = defaultMaxSteps;
 /**
  * Patterns already judged, keyed on the text, which is the only input the verdict depends on.
  *
- * The analysis costs up to {@link ANALYSIS_TIMEOUT_MS} a pattern, and one pattern text commonly
+ * The analysis costs up to {@link ANALYSIS_STEPS} steps a pattern, and one pattern text commonly
  * recurs across declarations - `^\\d{4}-\\d{2}-\\d{2}$` appears on several scalars in more than one
  * consumer spec - so each distinct text is analysed once per process.
  */
@@ -162,7 +165,7 @@ function firstReportOf(program, code, target) {
  *
  * **`false` means "not proven safe", not "proven dangerous"**, and the rule's wording follows that.
  * `redos-detector` proves safety rather than guessing at danger, so a pattern it cannot decide inside
- * the timeout is judged the same way as one it decides against. Measured over a realistic spread of
+ * the step budget is judged the same way as one it decides against. Measured over a realistic spread of
  * 14 patterns an API would carry: 2 conservative warnings, both on a quantifier nested over an
  * overlapping class, and nothing dangerous missed - including `^\w+([.-]?\w+)*$`, which reads as
  * ordinary and takes **11 seconds** on a 29-character input.
@@ -173,7 +176,8 @@ export function patternIsProvablySafe(pattern) {
         try {
             safe = isSafePattern(pattern, {
                 unicode: unicodeSafe(pattern),
-                timeout: ANALYSIS_TIMEOUT_MS,
+                maxSteps: ANALYSIS_STEPS,
+                timeout: Number.POSITIVE_INFINITY,
             }).safe;
         }
         catch {

package/dist/src/registry.js

@@ -134,16 +134,37 @@ const RESERVED_DECLARATION_NAMES = new Set([
     "with",
     "yield",
 ]);
+/**
+ * **The names the emitted files declare for THEMSELVES, beside the spec's own declarations.**
+ *
+ * `requests.gen.ts` declares `Produced`, `Simplify`, `ByteStream` and its three lookups; `schemas.gen.ts`
+ * declares `ResponseArm`. A model named after one of them was declared twice: `TS2300` for a type
+ * alias, and for `WireInputs` or `WireOutputs` something worse, because two interfaces of one name
+ * MERGE - the model's properties silently became members of the lookup. So a spec's model of that
+ * name is renamed exactly as a reserved word is.
+ *
+ * Graded by `test/collisions/`, which reads the names an emitted file declares off the OUTPUT rather
+ * than off this set, so a helper added later without a line here fails a test.
+ */
+const EMITTED_HELPER_NAMES = new Set([
+    "ByteStream",
+    "Produced",
+    "ResponseArm",
+    "Simplify",
+    "WireInputs",
+    "WireOutputs",
+    "WireResults",
+]);
 /**
  * The name a declaration is emitted under.
  *
- * A trailing `_` is appended where the spec's own name cannot be a TypeScript declaration. It is
- * applied in ONE place so both walks agree: `wire-contract.gen.ts` pairs a validator against a
- * contract type by name, and a mangling applied to one side only would break that assertion rather
- * than the file.
+ * A trailing `_` is appended where the spec's own name cannot be a TypeScript declaration, or is one
+ * the emitted file already declares for itself. It is applied in ONE place so both walks agree:
+ * `wire-contract.gen.ts` pairs a validator against a contract type by name, and a mangling applied to
+ * one side only would break that assertion rather than the file.
  */
 function safeDeclarationName(name) {
-    return RESERVED_DECLARATION_NAMES.has(name) ? `${name}_` : name;
+    return RESERVED_DECLARATION_NAMES.has(name) || EMITTED_HELPER_NAMES.has(name) ? `${name}_` : name;
 }
 /** A type earns a name when the spec gave it one - anonymous shapes stay inline where they are used. */
 function declaredNameOf(program, type) {

package/dist/src/results.d.ts

@@ -0,0 +1,113 @@
+/**
+ * **What a result is made of: one member per declared response and media type, and the codes each
+ * one answers with.** One derivation, read by every artefact that states a result.
+ *
+ * `typespec-hono` types a handler's return as a union of these members, `typespec-http-mcp` types a
+ * tool's the same way, and `requests.gen.ts` states the same union for a backend that has no
+ * framework to import. All three used to hold their own copy of these rules, and three copies of
+ * rules that must agree are three that will not: a status one of them could see and another could
+ * not is how `WireOutputs` came to publish one success body for an operation answering two.
+ */
+/**
+ * A status as the DOCUMENT keys it: an exact code, a `4XX` bucket, or the catch-all.
+ *
+ * `"default"` is kept as itself rather than mapped to a number. The document means "any status not
+ * listed above", and inventing one would be answering a question the contract left open.
+ */
+export type StatusKey = number | "default" | `${1 | 2 | 3 | 4 | 5}XX`;
+/**
+ * The facts about one declared response that decide how its result is shaped.
+ *
+ * Structural, so both an emitted response (`EmittedResponse`, whose body is a Zod expression) and a
+ * resolved one (whose body is a TypeSpec type) satisfy it; the caller says which ones carry a body.
+ */
+export interface ResponseFacts {
+    readonly status: StatusKey;
+    readonly contentTypes: readonly string[];
+    readonly binary: boolean;
+    readonly streamed: boolean;
+    readonly textual: boolean;
+}
+/** How a member's body is served, which decides both its type and the call that serves it. */
+export type BodyServing = "none" | "stream" | "binary" | "json" | "text" | "unvalidated";
+/**
+ * One member of an operation's result: one response, served as one media type.
+ *
+ * **A status offering several media types is several members**, because the body differs by media
+ * type: the Swagger Petstore answers `getPetById` with a `Pet` as `application/json` and with text as
+ * `application/xml`. One member with a union body could not say which body goes with which type.
+ */
+export interface ResultMember<R extends ResponseFacts> {
+    readonly response: R;
+    /** The response's position in the list it came from, so a caller can find what it names it by. */
+    readonly index: number;
+    /** The media type served, or `undefined` where the response has no body. */
+    readonly mediaType: string | undefined;
+    /**
+     * Whether the result names the media type: the status offers more than one, or the document names
+     * a range such as `image/*`, which is not a type a response can be sent as.
+     */
+    readonly choosesMediaType: boolean;
+    readonly serving: BodyServing;
+    /**
+     * **The document declares a schema for this body that nothing checks it against**: a model under a
+     * media type that is not JSON, which the handler supplies as text (`"unvalidated"`) or, under a
+     * type that is not text, as bytes (`"binary"`). A `bytes` or `Http.File` body declares nothing to
+     * check, so it is not this.
+     */
+    readonly unvalidated: boolean;
+}
+/**
+ * **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 declare function mediaTypeEssenceOf(type: string): string;
+/** `application/json` and every `+json` suffix: the media types a body is serialised as JSON for. */
+export declare function isJsonMediaType(type: string): boolean;
+/**
+ * **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 declare function isTextualMediaType(type: string): boolean;
+/** A media range such as `image/*`, rather than a type a response can be sent as. */
+export declare function isMediaRange(mediaType: string): boolean;
+/**
+ * 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 declare function mediaTypeTypeOf(mediaType: string): 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 declare function resultMembersOf<R extends ResponseFacts>(responses: readonly R[], hasBody: (response: R) => boolean): ResultMember<R>[];
+/**
+ * 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 declare function statusCodesOf<R extends ResponseFacts>(response: R, responses: readonly R[], hasBody: (response: R) => boolean): readonly number[];

package/dist/src/results.js

@@ -0,0 +1,134 @@
+import { CONTENTLESS_STATUS_CODES, STATUS_CODES } from "./statuses.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 JSON.stringify(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,6 @@
-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 { discriminatedSubtypes, effectiveIndexer, emitsDefault, encodedTypeOf, inheritedAndOwnProperties, isOptionalAt, isPayloadProperty, objectKey, refusalTarget, withDeclarationSite, } from "./zod.js";
 /**
  * TypeSpec type -> plain TypeScript type text.
  *
@@ -12,9 +12,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 +73,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;
@@ -261,9 +262,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 +303,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 +332,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;

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

@@ -103,4 +103,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

@@ -230,10 +230,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.
@@ -143,7 +143,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;

package/dist/src/zod.js

@@ -1063,7 +1063,7 @@ const PARAMETER_STYLE_ENCODINGS = new Set([
     "ArrayEncoding.commaDelimited",
     "ArrayEncoding.newlineDelimited",
 ]);
-function encodedTypeOf(program, target) {
+export function encodedTypeOf(program, target) {
     const encoded = getEncode(program, target);
     if (encoded === undefined)
         return undefined;
@@ -1209,6 +1209,24 @@ function renderValue(value) {
     }
     return undefined;
 }
+/**
+ * **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 function emitsDefault(program, property) {
+    const optional = property.optional || isOptionalAt(program, property);
+    return (optional &&
+        property.defaultValue !== undefined &&
+        renderValue(property.defaultValue) !== undefined);
+}
 /** A property's declared default, as a JS literal, or `undefined` when it has none. */
 function defaultOf(program, property) {
     const value = property.defaultValue;