typespec-http-zod 0.23.0 → 0.25.0

package/dist/src/constraints.d.ts

@@ -6,12 +6,13 @@ import { type Program, type Type } from "@typespec/compiler";
  * over: the spec author writes standard TypeSpec rather than a dialect, and `@typespec/openapi3`
  * documents them without any help from us.
  *
- * **`@refine` is the ONE that is still ours, and it is on its way out.** It is not a constraint -
- * it is an arbitrary predicate, which a type language has no way to say and therefore no document
- * can publish, so a validator enforcing it enforces something no caller can read. `@trimmed` was the
- * other one and is gone: `.trim()` is a transform, and transforming a value before validating it
- * makes the runtime accept inputs the published contract rejects. The spec states `@pattern`
- * instead, which openapi3 publishes.
+ * **This package ships no decorators of its own, and the two it used to have are gone.** `@refine`
+ * was an arbitrary predicate, which a type language has no way to say and therefore no document can
+ * publish, so a validator enforcing it enforced something no caller could read. `@trimmed` was the
+ * other: `.trim()` is a transform, and transforming a value before validating it makes the runtime
+ * accept inputs the published contract rejects. The spec states `@pattern` instead, which openapi3
+ * publishes. `src/tsp-index.ts` exports `$lib` and no `$decorators`, and `vocabulary.test.ts`
+ * asserts that no emitted file carries a `.refine(` outside the one multipart-file carve-out.
  */
 export declare function applyConstraints(program: Program, expression: string, target: Type): string;
 /**

package/dist/src/constraints.js

@@ -6,12 +6,13 @@ import { getMaxItems, getMaxLength, getMaxValue, getMinItems, getMinLength, getM
  * over: the spec author writes standard TypeSpec rather than a dialect, and `@typespec/openapi3`
  * documents them without any help from us.
  *
- * **`@refine` is the ONE that is still ours, and it is on its way out.** It is not a constraint -
- * it is an arbitrary predicate, which a type language has no way to say and therefore no document
- * can publish, so a validator enforcing it enforces something no caller can read. `@trimmed` was the
- * other one and is gone: `.trim()` is a transform, and transforming a value before validating it
- * makes the runtime accept inputs the published contract rejects. The spec states `@pattern`
- * instead, which openapi3 publishes.
+ * **This package ships no decorators of its own, and the two it used to have are gone.** `@refine`
+ * was an arbitrary predicate, which a type language has no way to say and therefore no document can
+ * publish, so a validator enforcing it enforced something no caller could read. `@trimmed` was the
+ * other: `.trim()` is a transform, and transforming a value before validating it makes the runtime
+ * accept inputs the published contract rejects. The spec states `@pattern` instead, which openapi3
+ * publishes. `src/tsp-index.ts` exports `$lib` and no `$decorators`, and `vocabulary.test.ts`
+ * asserts that no emitted file carries a `.refine(` outside the one multipart-file carve-out.
  */
 export function applyConstraints(program, expression, target) {
     let result = expression;

package/dist/src/lib.d.ts

@@ -42,6 +42,38 @@ export interface EmitterOptions {
      * stating it outright rather than an emitter option deciding.
      */
     "seal-object-schemas"?: boolean;
+    /**
+     * Whether every emitted validator is wrapped in `z.compile()`.
+     *
+     * **A pre-compiled schema parses the same values to the same results, only faster.** Zod walks the
+     * schema once and emits a flat, loop-free function through `new Function`, then falls back to the
+     * ordinary parser for anything it cannot handle - so errors, parsed output and JSON Schema
+     * serialisation are unchanged. Measured on an emitted five-property model at zod 4.5.2:
+     * `safeParse` goes from 371 ns to 51 ns.
+     *
+     * **Off by default, because it is a trade rather than a free win.** Compilation happens at module
+     * scope, so it costs startup time in proportion to the number of schemas, and buys nothing until
+     * enough requests arrive to pay that back. Measured on two emitted modules at zod 4.5.2: 25
+     * declarations in 3.3 ms and 73 in 5.7 ms, so 0.08-0.13 ms each depending on how much the schema
+     * does.
+     *
+     * **Measured at scale rather than extrapolated:** a generated 580-operation service (58 models,
+     * 1218 declarations, 638 of them compiled) evaluates its schema module in ~93 ms uncompiled and
+     * ~132 ms compiled - so about **40 ms of extra startup**, roughly a tenth of a Cloudflare Worker's
+     * 400 ms startup budget. It boots and serves on `workerd` at that size with the fast path live. It also needs
+     * `new Function`, which a CSP or no-eval environment refuses; Zod degrades to the uncompiled
+     * schema there rather than throwing, so setting this is never unsafe, merely sometimes pointless.
+     *
+     * **On Cloudflare Workers this is the only route to a compiled schema.** `new Function` is
+     * permitted during a Worker's STARTUP phase (`allow_eval_during_startup`, the default from
+     * compatibility date 2025-06-01) and module scope is startup, so wrapping here works. Zod's own
+     * `import "zod/compile"` does not: it compiles on first PARSE, which happens inside a request,
+     * where the runtime refuses. Only the emitter owns the module scope these schemas are built in.
+     *
+     * A recursive model emits `z.lazy()`, which cannot be compiled. Zod returns it uncompiled and it
+     * goes on parsing normally, so the option is safe to set on any spec.
+     */
+    "compile-schemas"?: boolean;
     /**
      * Models whose PROPERTY NAMES are also emitted as a runtime tuple.
      *
@@ -100,6 +132,7 @@ export interface EmitterOptions {
         "contracts-output-dir"?: string;
         "contracts-package"?: string;
         "seal-object-schemas"?: boolean;
+        "compile-schemas"?: boolean;
         "key-vocabularies"?: string[];
         "runtime-module"?: string;
         "regenerate-hint"?: string;
@@ -122,6 +155,9 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
     "default-on-required-property": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
     };
+    "truncated-doc-comment": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "tag", "tag"]>;
+    };
     "undeclared-discriminator": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "property", "variant", "property", "variant"]>;
     };
@@ -144,7 +180,7 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
     };
 }, EmitterOptions, never>;
-export declare const reportDiagnostic: <C extends "default-on-required-property" | "duplicate-declaration" | "duplicate-operation-id" | "empty-union" | "undeclared-discriminator" | "unknown-key-vocabulary" | "unmirrorable-seal" | "unsupported-default" | "unsupported-status-code-range" | "unsupported-type", M extends keyof {
+export declare const reportDiagnostic: <C extends "default-on-required-property" | "duplicate-declaration" | "duplicate-operation-id" | "empty-union" | "truncated-doc-comment" | "undeclared-discriminator" | "unknown-key-vocabulary" | "unmirrorable-seal" | "unsupported-default" | "unsupported-status-code-range" | "unsupported-type", M extends keyof {
     "unsupported-type": {
         readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why", "remedy"]>;
     };
@@ -154,6 +190,9 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "default-on-required-property": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
     };
+    "truncated-doc-comment": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "tag", "tag"]>;
+    };
     "undeclared-discriminator": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "property", "variant", "property", "variant"]>;
     };
@@ -185,6 +224,9 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "default-on-required-property": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
     };
+    "truncated-doc-comment": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "tag", "tag"]>;
+    };
     "undeclared-discriminator": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "property", "variant", "property", "variant"]>;
     };

package/dist/src/lib.js

@@ -12,6 +12,7 @@ export const EmitterOptionsSchema = {
         "contracts-output-dir": { type: "string", nullable: true },
         "contracts-package": { type: "string", nullable: true },
         "seal-object-schemas": { type: "boolean", nullable: true },
+        "compile-schemas": { type: "boolean", nullable: true },
         "key-vocabularies": { type: "array", items: { type: "string" }, nullable: true },
         "runtime-module": { type: "string", nullable: true },
         "regenerate-hint": { type: "string", nullable: true },
@@ -26,6 +27,7 @@ export const EmitterOptionsSchema = {
                     "contracts-output-dir": { type: "string", nullable: true },
                     "contracts-package": { type: "string", nullable: true },
                     "seal-object-schemas": { type: "boolean", nullable: true },
+                    "compile-schemas": { type: "boolean", nullable: true },
                     "key-vocabularies": { type: "array", items: { type: "string" }, nullable: true },
                     "runtime-module": { type: "string", nullable: true },
                     "regenerate-hint": { type: "string", nullable: true },
@@ -112,6 +114,50 @@ const diagnostics = {
             default: paramMessage `'${"name"}' is required, so its default can never apply: a required property is never absent. The OpenAPI document publishes it in 'required' and carries the default only as an annotation, and this validator does the same - a request omitting '${"name"}' is refused. Declare it optional, '${"name"}?: ... = ...', if callers may omit it.`,
         },
     },
+    /**
+     * **A doc comment the compiler truncated, so the description this emitter passes on is cut short.**
+     *
+     * **An unescaped `@` in a doc comment begins a doc tag, and everything from there to the end of
+     * the comment leaves the description.** Measured against `@typespec/compiler@1.15.0` through its
+     * own parser: `parseDocContent` breaks its loop on `Token.At` outside a code fence, and the
+     * doc-mode scanner turns every `@` into that token. `parseDocTag` then parses the remainder as a
+     * tag and, for a name it does not know, keeps it as `DocUnknownTag` - which `getDoc` never reads.
+     * No diagnostic is raised anywhere in that path.
+     *
+     * So it is not only `{@link}`. `support@example.com` in prose truncates at `support`, and
+     * "use @maxLength to bound it" truncates at "use", with no brace anywhere to notice. A consumer
+     * measured 14 of 1,006 published descriptions cut this way and found it by reading the emitted
+     * document by hand.
+     *
+     * **The check reads the AST, because the truncated string cannot answer.** By the time `getDoc`
+     * returns, the `@` is gone, so a check over the emitted text would find nothing to match - and
+     * pattern-matching emitted text is the thing this package refuses to decide anything by. The fact
+     * is on the node: a tag that is not `param`, `template`, `prop`, `returns`, `return` or `errors`
+     * parses as `DocUnknownTag`. That is exact, with no heuristic and no false positive on the four
+     * spellings that survive: a brace in prose, a backticked brace, `\{`, and `\@`.
+     *
+     * **Gated on the description actually coming from the comment**, via `getDocData().source`. A type
+     * carrying an `@doc(...)` decorator takes its description from there, where `@` inside a string
+     * literal means nothing, so warning would be a false positive - and a warning that fires on
+     * correct specs is one a consumer turns off wholesale.
+     *
+     * **A WARNING, for the reason `default-on-required-property` is one.** The spec is representable:
+     * `@typespec/openapi3` publishes the same truncated description happily, so refusing it would make
+     * one spec emit under one emitter and not the other. An error would also set `program.hasError()`
+     * and cost the whole document over one comment. What is wrong is not that it cannot be served, but
+     * that the author has written something that does not say what they meant.
+     *
+     * **Upstream this is intended, and the escape is sanctioned.** `microsoft/typespec#3374` reported
+     * exactly this, naming both `{@link}` and email addresses, and was closed as a duplicate of
+     * `#1358`, which is open on the Backlog. `#3375` then added the `\@` escape deliberately. So the
+     * remedy this message names is upstream's own, and only the silence is unaccounted for.
+     */
+    "truncated-doc-comment": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"name"}' has a doc comment that stops at '@${"tag"}': an unescaped '@' begins a doc tag, so everything after it is dropped from the description this emitter and the OpenAPI document beside it both publish. Use '\\@${"tag"}' to escape it, wrap it in backticks, or set the description with '@doc(...)' instead.`,
+        },
+    },
     /**
      * **A discriminated union whose discriminator the document never publishes.**
      *

package/dist/src/registry.d.ts

@@ -1,4 +1,5 @@
 import type { ModelProperty, Program, Type } from "@typespec/compiler";
+import { Visibility } from "@typespec/http";
 /**
  * Assigns each named TypeSpec model/enum a single Zod declaration, emitted in dependency order.
  *
@@ -54,6 +55,46 @@ interface Declaration {
     /** Whether the declaration is annotated `: z.ZodType<typeName>`, which `z.lazy()` requires. */
     readonly annotated?: boolean;
 }
+/**
+ * One model can need MORE THAN ONE declaration.
+ *
+ * **Keyed on `(type, visibility)`, because a model is not one shape.** `@visibility` and HTTP
+ * metadata both mean the same declaration projects differently by position: `@typespec/openapi3`
+ * emits `VisibilityModel` and `VisibilityModelCreate` as separate components for exactly this
+ * reason. Keyed on the type alone, whichever position was walked first won and every other position
+ * silently got its shape - measured on the corpus, one strict model carrying all six lifecycle
+ * properties, so a create request was required to send read-only fields.
+ *
+ * The suffix rule is openapi3's: canonical (`Read`) keeps the bare name, and another visibility only
+ * earns a suffix when the model is actually TRANSFORMED at it. Same rule, so the identifiers line up
+ * with the component names the document publishes.
+ */
+/**
+ * The visibility a type is actually DECLARED at, which is not always the one requested.
+ *
+ * **A type not reshaped at this visibility IS the canonical declaration, not a copy of it.** Keying
+ * on the requested visibility while only suffixing transformed types produced two cache entries
+ * sharing one identifier and an emitted file that stopped parsing:
+ * `Identifier 'approvalTierSchema' has already been declared`. An enum is the same enum in a request
+ * and a response, which is what the `Model` guard is for.
+ *
+ * It is the same collapse `@typespec/openapi3` performs before naming a component, and
+ * `isTransformedBy` is its own predicate, `metadataInfo.isTransformed`.
+ *
+ * **Extracted so both registries answer it identically.** They must: the emitted assertion pairs a
+ * validator with a contract type BY NAME, so a rule applied in one walk and paraphrased in the other
+ * is a pairing that silently compares the wrong two things.
+ */
+export declare function visibilityFor(program: Program, type: Type, requested: Visibility): Visibility;
+/**
+ * A declaration's name at a visibility: the bare name at canonical, suffixed anywhere else.
+ *
+ * The suffix is `@typespec/http`'s `getVisibilitySuffix`, called with `Visibility.Read` as the
+ * canonical exactly as `@typespec/openapi3` calls it in `schema-emitter.ts`. Same function, same
+ * argument, so these identifiers line up with the component names the document publishes rather than
+ * merely resembling them.
+ */
+export declare function nameAt(bare: string, at: Visibility): string;
 export declare class SchemaRegistry {
     #private;
     constructor(program: Program);

package/dist/src/registry.js

@@ -78,11 +78,22 @@ const spreadSourceName = (type) => spreadSourceOf(type)?.name;
  * so a word missing from the list fails a test rather than reaching a consumer - the list is the
  * implementation and the compiler is the oracle.
  *
- * Contextual keywords are deliberately absent, because they are legal: `interface`, `string`,
- * `number`, `any`, `never`, `public` and `yield` all name a type without complaint. Measured, rather
- * than assumed from a language reference.
+ * Most contextual keywords are absent, because they are legal: `interface`, `string`, `number`,
+ * `any`, `never` and `public` all name a type without complaint.
+ *
+ * **Two contextual words are NOT legal, and both were missing from this set.** `as` and `yield` are
+ * refused in the declaration positions this emitter writes -- `export type as = ...` is
+ * `TS1005: '{' expected`, and `yield` is `TS1214: 'yield' is a reserved word in strict mode` as both
+ * a type alias and an interface. Either one made the whole emitted file unparseable, because the
+ * parser gives up after the first.
+ *
+ * **A word belongs here when `tsc` refuses it in EITHER position**, since both are emitted for the
+ * same model. Measured that way against tsc 7.0.2, one invocation per word: of the 56 candidates,
+ * 39 are refused and 39 are listed. `yield` had been recorded here as measured-legal and is not,
+ * which is why the arm that grades this set now takes its words from somewhere else entirely.
  */
 const RESERVED_DECLARATION_NAMES = new Set([
+    "as",
     "await",
     "break",
     "case",
@@ -120,6 +131,7 @@ const RESERVED_DECLARATION_NAMES = new Set([
     "void",
     "while",
     "with",
+    "yield",
 ]);
 /**
  * The name a declaration is emitted under.
@@ -185,6 +197,40 @@ const lowerFirst = (value) => value.charAt(0).toLowerCase() + value.slice(1);
  * earns a suffix when the model is actually TRANSFORMED at it. Same rule, so the identifiers line up
  * with the component names the document publishes.
  */
+/**
+ * The visibility a type is actually DECLARED at, which is not always the one requested.
+ *
+ * **A type not reshaped at this visibility IS the canonical declaration, not a copy of it.** Keying
+ * on the requested visibility while only suffixing transformed types produced two cache entries
+ * sharing one identifier and an emitted file that stopped parsing:
+ * `Identifier 'approvalTierSchema' has already been declared`. An enum is the same enum in a request
+ * and a response, which is what the `Model` guard is for.
+ *
+ * It is the same collapse `@typespec/openapi3` performs before naming a component, and
+ * `isTransformedBy` is its own predicate, `metadataInfo.isTransformed`.
+ *
+ * **Extracted so both registries answer it identically.** They must: the emitted assertion pairs a
+ * validator with a contract type BY NAME, so a rule applied in one walk and paraphrased in the other
+ * is a pairing that silently compares the wrong two things.
+ */
+export function visibilityFor(program, type, requested) {
+    return type.kind === "Model" &&
+        requested !== Visibility.Read &&
+        isTransformedBy(program, type, requested)
+        ? requested
+        : Visibility.Read;
+}
+/**
+ * A declaration's name at a visibility: the bare name at canonical, suffixed anywhere else.
+ *
+ * The suffix is `@typespec/http`'s `getVisibilitySuffix`, called with `Visibility.Read` as the
+ * canonical exactly as `@typespec/openapi3` calls it in `schema-emitter.ts`. Same function, same
+ * argument, so these identifiers line up with the component names the document publishes rather than
+ * merely resembling them.
+ */
+export function nameAt(bare, at) {
+    return `${bare}${at === Visibility.Read ? "" : getVisibilitySuffix(at, Visibility.Read)}`;
+}
 function keyFor(type, visibility) {
     /**
      * **Keyed on the SPREAD SOURCE where there is one, or one component gets two declarations.**
@@ -244,12 +290,7 @@ export class SchemaRegistry {
          * request and a response. Collapsing onto `Read` first is what makes the key and the name agree,
          * and it is the same collapse openapi3 performs before naming a component.
          */
-        const requested = currentVisibility();
-        const at = type.kind === "Model" &&
-            requested !== Visibility.Read &&
-            isTransformedBy(this.#program, type, requested)
-            ? requested
-            : Visibility.Read;
+        const at = visibilityFor(this.#program, type, currentVisibility());
         const key = keyFor(type, at);
         const existing = this.#declarations.get(key);
         if (existing !== undefined)
@@ -275,7 +316,7 @@ export class SchemaRegistry {
                 this.#cyclic.add(inFlight);
             return pending;
         }
-        const name = `${bare}${at === Visibility.Read ? "" : getVisibilitySuffix(at, Visibility.Read)}`;
+        const name = nameAt(bare, at);
         const identifier = `${lowerFirst(name)}Schema`;
         this.#inProgress.set(key, identifier);
         const rendered = captureBackEdges(() => this.#inline(type));
@@ -459,17 +500,32 @@ function isSingleObjectLiteral(source) {
 }
 export class TypeRegistry {
     #program;
+    /**
+     * **Keyed on `(type, visibility)`, exactly as {@link SchemaRegistry} is, and for the same reason.**
+     *
+     * One model is not one shape. Keyed on the `Type` alone, whichever position was walked first won
+     * and every other position silently got its shape - measured on `type/model/visibility`, where a
+     * `GET` reached the model first and the create body's contract type came out carrying the read
+     * projection. The two registries pair BY NAME in the emitted assertion, so they have to agree
+     * about how many declarations there are before the pairing means anything.
+     *
+     * Both now go through the shared {@link visibilityFor} and {@link nameAt}: paraphrasing either
+     * rule in one walk is how a validator ends up compared against a type describing something else.
+     */
     #declarations = new Map();
     #order = [];
-    #inProgress = new Set();
+    #inProgress = new Map();
     constructor(program) {
         this.#program = program;
     }
     expressionFor(type) {
-        const name = declaredNameOf(type);
-        if (name === undefined)
+        const bare = declaredNameOf(type);
+        if (bare === undefined)
             return this.#inline(type);
-        const existing = this.#declarations.get(type);
+        const at = visibilityFor(this.#program, type, currentVisibility());
+        const key = keyFor(type, at);
+        const name = nameAt(bare, at);
+        const existing = this.#declarations.get(key);
         if (existing !== undefined)
             return existing.name;
         /**
@@ -477,12 +533,17 @@ export class TypeRegistry {
          * may refer to itself - `interface InnerModel { children?: InnerModel[] }` is the ordinary way
          * to write a tree - so the name alone is the whole answer. The Zod registry has to defer the
          * same edge behind a getter only because a `const` cannot read itself while initialising.
+         *
+         * The in-flight name is the SUFFIXED one, not the bare one: a recursive model reached at
+         * `Create` must refer to `ThingCreate`, or it self-references a declaration that is not the
+         * one being written.
          */
-        if (this.#inProgress.has(type))
-            return name;
-        this.#inProgress.add(type);
+        const pending = this.#inProgress.get(key);
+        if (pending !== undefined)
+            return pending;
+        this.#inProgress.set(key, name);
         const source = this.#inline(type);
-        this.#inProgress.delete(type);
+        this.#inProgress.delete(key);
         const declaration = {
             name,
             /**
@@ -508,7 +569,7 @@ export class TypeRegistry {
             isVocabulary: type.kind === "Enum",
             source,
         };
-        this.#declarations.set(type, declaration);
+        this.#declarations.set(key, declaration);
         /**
          * **Declared once per NAME, not once per `Type`, and the two are not the same thing.**
          *

package/dist/src/types.js

@@ -1,6 +1,6 @@
 import { getDiscriminatedUnion, getEncode, isNeverType, resolveEncodedName, } from "@typespec/compiler";
 import { reportDiagnostic } from "./lib.js";
-import { discriminatedSubtypes, effectiveIndexer, inheritedAndOwnProperties, objectKey, refusalTarget, withDeclarationSite, } from "./zod.js";
+import { discriminatedSubtypes, effectiveIndexer, inheritedAndOwnProperties, isOptionalAt, isPayloadProperty, objectKey, refusalTarget, withDeclarationSite, } from "./zod.js";
 /**
  * TypeSpec type -> plain TypeScript type text.
  *
@@ -196,7 +196,20 @@ function modelToTs(program, model) {
      * that catches this emitter disagreeing with itself, and it cannot catch a disagreement that
      * aborts the compile first.
      */
+    /**
+     * **Metadata is filtered out here, as it is on the Zod side, and the two must agree.**
+     *
+     * `metadataInfo.isPayloadProperty` is what decides whether a property is in the BODY at this
+     * position: a `@query` or `@header` property is carried separately, and an `@invisible` one is
+     * carried nowhere. `modelToZod` has asked since it was written; this walk never did, so a
+     * contract type listed properties the validator beside it refuses as unknown keys.
+     *
+     * **Applied AFTER the dictionary check above, deliberately.** That check reads the UNFILTERED
+     * list, because a model whose only properties are metadata is still a declared object rather than
+     * a dictionary, and filtering first would flip it to `Record<string, T>` on one side alone.
+     */
     const entries = declared
+        .filter((property) => isPayloadProperty(program, property))
         .filter((property) => !isNeverType(property.type))
         .map((property) => `\t${withDeclarationSite(property, () => propertyToTs(program, property))}`);
     /**
@@ -226,8 +239,8 @@ function modelToTs(program, model) {
      * of the failure - see `test/contractshape/`.
      *
      * What arrives is still described honestly, on the surface derived from the validator:
-     * `schemas.gen.ts` exports `Exact<z.infer<typeof x>>`, which carries the index signature because
-     * a `.loose()` parse really does. Two surfaces, two directions, neither lying.
+     * `schemas.gen.ts` exports `z.infer<typeof x>`, which carries the index signature because a
+     * `.loose()` parse really does. Two surfaces, two directions, neither lying.
      */
     return entries.length === 0 ? "{}" : `{\n${entries.join("\n")}\n}`;
 }
@@ -266,9 +279,9 @@ export function propertyToTs(program, property, wireName) {
      * optionality per property fixes every depth at once, because there is no depth to reach.
      *
      * **The two directions of the emitted set differ here on purpose**, exactly as they do on
-     * openness: `schemas.gen.ts` exports `Exact<z.infer<...>>`, the narrow view of what ARRIVES, in
-     * which a default has fired and the property is present. `wire-contract.gen.ts` pairs this walk
-     * against `z.input` for the same reason.
+     * openness: `schemas.gen.ts` exports `z.infer<...>`, the narrow view of what ARRIVES, in which a
+     * default has fired and the property is present. `wire-contract.gen.ts` pairs this walk against
+     * `z.input` for the same reason.
      *
      * A defaulted property that reaches here is one the document publishes as optional, because
      * `propertyToZod` reports `default-on-required-property` for the other spelling and emits no
@@ -278,7 +291,7 @@ export function propertyToTs(program, property, wireName) {
      * **`?: T | undefined`, and dropping the `| undefined` was tried in `0.19.0` and reverted.**
      *
      * It looks wrong - JSON has no `undefined`, so a wire type saying `?: T` reads more honest, and
-     * it would make this walk agree with `Exact<z.infer<...>>` on the schemas side. **Measured, it
+     * 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.
@@ -291,7 +304,15 @@ export function propertyToTs(program, property, wireName) {
      * 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.
      */
-    return property.optional ? `${key}?: ${value} | undefined;` : `${key}: ${value};`;
+    /**
+     * **Optional AT THIS POSITION, not merely optional in the declaration.** A PATCH body's properties
+     * are optional whether or not the spec marked them so, which is `metadataInfo.isOptional` and is
+     * 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};`;
 }
 /** Installed by the registry so a named model is declared once and referenced everywhere else. */
 let resolveRef = () => undefined;

package/dist/src/zod.d.ts

@@ -2,6 +2,10 @@ import { type Enum, type Model, type ModelProperty, type Program, type Type } fr
 import { Visibility } from "@typespec/http";
 export declare function withSealedObjects<T>(sealed: boolean, run: () => T): T;
 export declare function withVisibility<T>(program: Program, next: Visibility, run: () => T): T;
+/** Whether a property is optional AT THE CURRENT POSITION - PATCH makes update fields optional. */
+export declare function isOptionalAt(program: Program, property: ModelProperty): boolean;
+/** Whether a property belongs in the BODY at the current position, rather than being metadata. */
+export declare function isPayloadProperty(program: Program, property: ModelProperty): boolean;
 /** Whether this model is shaped differently at `visibility` than at the canonical `Read`. */
 export declare function isTransformedBy(program: Program, model: Model, at: Visibility): boolean;
 /** The visibility the current walk is emitting for - the registry keys declarations on it. */
@@ -122,6 +126,29 @@ export declare function wireKindOf(program: Program, type: Type): "number" | "bo
  * Exported so there is one answer to this question. There were two sites and only one of them knew.
  */
 export declare function objectKey(name: string): string;
+/**
+ * A doc string as a JSDoc comment, indented, or `""` when there is none.
+ *
+ * **Spec-authored text going into emitted source is the same question `objectKey` answers for a
+ * property name, and it had the same two-sites-one-answer shape.** A summary was interpolated raw
+ * into a `/** ... *\/` block by this estate's two server emitters. Measured: `@summary("a *\/ b")` is
+ * an ordinary string literal, so the text reaches here intact, closes the comment early and turns
+ * the remainder into code. `TS1131`, `TS1434`, `TS1161` - one operation costing the whole file,
+ * exactly like a model named `as`.
+ *
+ * **The bar is idiomatic output, not merely parseable output.** Two consequences:
+ *
+ * - A terminator is escaped as `*\/`, which is how TypeScript itself writes one inside a comment, so
+ *   the sentence survives and reads correctly. Dropping or replacing the characters would lose an
+ *   author's words to a mechanical problem they cannot see from their spec.
+ * - A multi-line description is rendered as a multi-line BLOCK. Interpolating the newlines into a
+ *   one-line form produces a comment whose continuation lines carry no ` * `, which no formatter
+ *   would emit and no reviewer would write.
+ *
+ * `indent` is passed rather than assumed because the two call sites sit at different depths, and a
+ * 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 propertyToZod(program: Program, property: ModelProperty): string;
 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. */

package/dist/src/zod.js

@@ -139,12 +139,12 @@ export function withVisibility(program, next, run) {
     }
 }
 /** Whether a property is optional AT THE CURRENT POSITION - PATCH makes update fields optional. */
-function isOptionalAt(program, property) {
+export function isOptionalAt(program, property) {
     metadataInfo ??= createMetadataInfo(program);
     return metadataInfo.isOptional(property, visibility);
 }
 /** Whether a property belongs in the BODY at the current position, rather than being metadata. */
-function isPayloadProperty(program, property) {
+export function isPayloadProperty(program, property) {
     metadataInfo ??= createMetadataInfo(program);
     return metadataInfo.isPayloadProperty(property, visibility);
 }
@@ -874,6 +874,49 @@ export function wireKindOf(program, type) {
 export function objectKey(name) {
     return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
 }
+/**
+ * A doc string as a JSDoc comment, indented, or `""` when there is none.
+ *
+ * **Spec-authored text going into emitted source is the same question `objectKey` answers for a
+ * property name, and it had the same two-sites-one-answer shape.** A summary was interpolated raw
+ * into a `/** ... *\/` block by this estate's two server emitters. Measured: `@summary("a *\/ b")` is
+ * an ordinary string literal, so the text reaches here intact, closes the comment early and turns
+ * the remainder into code. `TS1131`, `TS1434`, `TS1161` - one operation costing the whole file,
+ * exactly like a model named `as`.
+ *
+ * **The bar is idiomatic output, not merely parseable output.** Two consequences:
+ *
+ * - A terminator is escaped as `*\/`, which is how TypeScript itself writes one inside a comment, so
+ *   the sentence survives and reads correctly. Dropping or replacing the characters would lose an
+ *   author's words to a mechanical problem they cannot see from their spec.
+ * - A multi-line description is rendered as a multi-line BLOCK. Interpolating the newlines into a
+ *   one-line form produces a comment whose continuation lines carry no ` * `, which no formatter
+ *   would emit and no reviewer would write.
+ *
+ * `indent` is passed rather than assumed because the two call sites sit at different depths, and a
+ * comment indented differently from the member it documents is the tell that a generator wrote it.
+ */
+export function jsDocComment(text, indent) {
+    if (text === undefined)
+        return "";
+    const lines = text
+        .replaceAll("*/", "*\\/")
+        .split("\n")
+        .map((line) => line.trimEnd());
+    while (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    while (lines.length > 0 && lines[0] === "")
+        lines.shift();
+    if (lines.length === 0)
+        return "";
+    const [only] = lines;
+    if (lines.length === 1 && only !== undefined)
+        return `${indent}/** ${only} */\n`;
+    const body = lines
+        .map((line) => (line === "" ? `${indent} *` : `${indent} * ${line}`))
+        .join("\n");
+    return `${indent}/**\n${body}\n${indent} */\n`;
+}
 /**
  * The name a property carries **on the wire**, which is not always the name the spec gave it.
  *
@@ -1021,7 +1064,25 @@ export function propertyToZod(program, property) {
     const defaulted = defaultOf(program, property);
     if (defaulted !== undefined)
         return `${base}.default(${defaulted})`;
-    return optional ? `${base}.optional()` : base;
+    /**
+     * **`.exactOptional()`, because the document says the KEY may be absent and nothing more.**
+     *
+     * `.optional()` additionally accepts an explicit `undefined`, and **JSON cannot carry one** - so
+     * for a body the validator was admitting a value no conformant request can contain, and for a
+     * parameter one no transport produces. The document says exactly "absent or a value" by leaving
+     * the property out of `required`, and this is the construct that says the same.
+     *
+     * **The emitted TYPE has said this since `0.17.0`; only the validator disagreed.** `Exact<>` was
+     * written to strip `| undefined` back off `z.infer`, with a docblock arguing precisely this - so
+     * one program published a type refusing `{ note: undefined }` beside a validator accepting it, and
+     * nothing compared them. `z.infer` of `.exactOptional()` is `note?: T` natively and at every depth,
+     * which a shallow mapped type never managed, so `Exact<>` is deleted rather than kept beside it.
+     *
+     * Measured on zod 4.5.2 before the change: `z.toJSONSchema` is byte-identical for the two, so the
+     * differential's serialisation axis is untouched, and `def.type` is still `"optional"`, so the
+     * shape describers read it unchanged.
+     */
+    return optional ? `${base}.exactOptional()` : base;
 }
 /**
  * A default value as a JS literal, or `undefined` where this emitter cannot render one.