typespec-http-zod 0.28.0 → 0.30.0

package/dist/src/zod.d.ts

@@ -75,6 +75,50 @@ 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;
+/** A scalar's schema without its description, for a position that publishes its own. */
+/**
+ * The scalars an `@encode` chain passes through, when it returns to one it already passed - and
+ * `undefined` when it ends at a type that crosses the wire.
+ *
+ * **The one guard for every walk that follows `@encode`.** The schema, the wire kind and the contract
+ * type each follow the chain by calling themselves on the encoded type, and each one overflowed the
+ * stack on `Ping -> Pong -> Ping`. A scalar encoded as itself is no cycle: the chain ends there.
+ */
+export declare function encodeCycleOf(program: Program, scalar: Scalar): readonly Scalar[] | 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**.
@@ -108,6 +152,40 @@ export declare function effectiveIndexer(model: Model): Model["indexer"];
  * for a real subtype - the same rule that decides whether a base may be sealed.
  */
 export declare function discriminatedSubtypes(program: Program, model: Model): readonly Model[];
+/**
+ * **How a `@discriminator` base is validated: a value whose discriminator names a subtype as that
+ * subtype, and any other value as the base model itself.**
+ *
+ * The document publishes the base as an object of its own properties carrying `discriminator:
+ * {propertyName, mapping}`, and every subtype as `allOf` that base. The mapping says which subtype a
+ * value naming it is; nothing in the document refuses a value naming none. This emitter dispatched
+ * on the mapping and stopped there, so `{ "kind": "wrongKind", "weight": 8 }` was refused for a
+ * `Dog` whose `kind` is `string | "golden"`, though `Dog` requires only `kind` and `weight`. That is
+ * the response `@typespec/http-specs` declares for `type/model/inheritance/enum-discriminator`,
+ * `single-discriminator` and `nested-discriminator`, and a handler returning it failed its own
+ * response contract (typespec-http-graphql, 2026-10-16).
+ *
+ * **A closed discriminator every value of which a subtype claims has no base arm**: a value outside
+ * it is refused by the base's own discriminator, and a value inside it always names a subtype. So a
+ * fixed enum fully covered by its subtypes is validated exactly as before.
+ */
+export interface DiscriminatedBase {
+    /** The discriminator's wire name. */
+    readonly propertyName: string;
+    /** The subtypes a `z.discriminatedUnion` dispatches to, each carrying literal discriminator values. */
+    readonly dispatched: readonly Model[];
+    /**
+     * Subtypes that are themselves bases validated with a base arm. A `z.union` has no literal values
+     * to dispatch on, so no `z.discriminatedUnion` can hold one; it sits beside the dispatch, where its
+     * own literal discriminator keeps it exclusive.
+     */
+    readonly beside: readonly Model[];
+    /** Every value a subtype claims, which are the keys of the document's `mapping`. */
+    readonly claimed: readonly string[];
+    /** Whether a value no subtype claims is validated as the base model. */
+    readonly open: boolean;
+}
+export declare function discriminatedBaseOf(program: Program, model: Model): DiscriminatedBase | undefined;
 export declare function wireKindOf(program: Program, type: Type): "number" | "boolean" | undefined;
 /**
  * A name as an object key - quoted when it is not a legal JavaScript identifier.

package/dist/src/zod.js

@@ -1,6 +1,7 @@
-import { getDiscriminatedUnion, getDiscriminator, getEncode, resolveEncodedName, isNeverType, isTemplateDeclaration, } from "@typespec/compiler";
-import { createMetadataInfo, isQueryParam, Visibility } from "@typespec/http";
-import { applyConstraints } from "./constraints.js";
+import { getDiscriminatedUnion, getDiscriminatedUnionFromInheritance, getDiscriminator, getDoc, getEncode, ignoreDiagnostics, resolveEncodedName, isNeverType, isTemplateDeclaration, } from "@typespec/compiler";
+import { createMetadataInfo, getCookieParamOptions, getHeaderFieldName, getPathParamName, getQueryParamName, isCookieParam, isHeader, isPathParam, isQueryParam, Visibility, } from "@typespec/http";
+import { applyConstraints, firstReportOf } from "./constraints.js";
+import { literal } from "./literal.js";
 import { reportDiagnostic } from "./lib.js";
 /**
  * What a walk returns after reporting a refusal.
@@ -406,10 +407,95 @@ const SCALARS = {
     url: "z.url()",
 };
 function scalarToZod(program, scalar) {
+    return described(scalarSchemaOf(program, scalar), scalarDocOf(program, scalar));
+}
+/**
+ * **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 function described(expression, doc) {
+    return doc === undefined ? expression : `${expression}.describe(${literal(doc)})`;
+}
+/**
+ * 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 function scalarDocOf(program, scalar) {
+    for (let current = scalar; current !== undefined && !program.checker.isStdType(current); current = current.baseScalar) {
+        const doc = getDoc(program, current);
+        if (doc !== undefined)
+            return doc;
+    }
+    return undefined;
+}
+/** A scalar's schema without its description, for a position that publishes its own. */
+/**
+ * The scalars an `@encode` chain passes through, when it returns to one it already passed - and
+ * `undefined` when it ends at a type that crosses the wire.
+ *
+ * **The one guard for every walk that follows `@encode`.** The schema, the wire kind and the contract
+ * type each follow the chain by calling themselves on the encoded type, and each one overflowed the
+ * stack on `Ping -> Pong -> Ping`. A scalar encoded as itself is no cycle: the chain ends there.
+ */
+export function encodeCycleOf(program, scalar) {
+    const passed = [];
+    for (let current = scalar; current !== undefined;) {
+        if (passed.includes(current))
+            return [...passed, current];
+        passed.push(current);
+        const encoded = encodedTypeOf(program, current);
+        current = encoded === current ? undefined : encoded;
+    }
+    return undefined;
+}
+function scalarSchemaOf(program, scalar) {
     // `scalar unixTimestamp32 is utcDateTime;` with `@encode(int32)` on the SCALAR, not on each use.
     const encoded = encodedTypeOf(program, scalar);
     if (encoded !== undefined && encoded !== scalar) {
-        return applyConstraints(program, scalarToZod(program, encoded), scalar);
+        const cycle = encodeCycleOf(program, scalar);
+        if (cycle !== undefined) {
+            // Reached once per use; reported once per scalar.
+            if (firstReportOf(program, "encode-cycle", scalar)) {
+                reportDiagnostic(program, {
+                    code: "encode-cycle",
+                    target: scalar,
+                    format: {
+                        type: scalar.name,
+                        // From the first link on: `Ping` is encoded as `'Pong' -> 'Ping'`.
+                        chain: cycle
+                            .slice(1)
+                            .map((link) => `'${link.name}'`)
+                            .join(" -> "),
+                    },
+                });
+            }
+            return UNREPRESENTABLE;
+        }
+        return applyConstraints(program, scalarSchemaOf(program, encoded), scalar);
     }
     let current = scalar;
     // Walk the `extends` chain so a named scalar (`scalar chNumber extends string`) resolves to the
@@ -454,7 +540,7 @@ function scalarToZod(program, scalar) {
 function enumToZod(_program, target) {
     const values = [...target.members.values()].map((member) => member.value ?? member.name);
     if (values.some((value) => typeof value !== "string")) {
-        return `z.union([${values.map((value) => `z.literal(${JSON.stringify(value)})`).join(", ")}])`;
+        return `z.union([${values.map((value) => `z.literal(${literal(value)})`).join(", ")}])`;
     }
     /**
      * Every string vocabulary resolves through the generated constant rather than being restated.
@@ -475,7 +561,7 @@ function enumToZod(_program, target) {
      */
     const shared = contractsPackage();
     if (shared === undefined) {
-        return `z.enum([${values.map((value) => JSON.stringify(value)).join(", ")}])`;
+        return `z.enum([${values.map((value) => literal(value)).join(", ")}])`;
     }
     noteExternalImport(shared, "SPEC_VOCABULARIES");
     return `z.enum(SPEC_VOCABULARIES.${target.name})`;
@@ -534,7 +620,7 @@ function declaresDiscriminator(program, variant, property) {
  */
 function discriminatedVariant(program, union, variantName, variant, options) {
     const inner = typeToZod(program, variant);
-    const tag = `${objectKey(options.discriminatorPropertyName)}: z.literal(${JSON.stringify(variantName)})`;
+    const tag = `${objectKey(options.discriminatorPropertyName)}: z.literal(${literal(variantName)})`;
     // The variant already carries the discriminator, so the document publishes it and there is
     // nothing to add.
     if (options.envelope === "none")
@@ -587,7 +673,7 @@ function unionToZod(program, union) {
         }
         const members = [...discriminated.variants.entries()].map(([name, variant]) => discriminatedVariant(program, union, name, variant, options));
         const property = options.discriminatorPropertyName;
-        return `z.discriminatedUnion(${JSON.stringify(property)}, [${members.join(", ")}])`;
+        return `z.discriminatedUnion(${literal(property)}, [${members.join(", ")}])`;
     }
     const variants = [...union.variants.values()].map((variant) => variant.type);
     const nullable = variants.some((type) => type.kind === "Intrinsic" && type.name === "null");
@@ -602,7 +688,7 @@ function unionToZod(program, union) {
     }
     const suffix = nullable ? ".nullable()" : "";
     if (real.every((type) => type.kind === "String")) {
-        const literals = real.map((type) => JSON.stringify(type.value));
+        const literals = real.map((type) => literal(type.value));
         return `z.enum([${literals.join(", ")}])${suffix}`;
     }
     if (real.length === 1)
@@ -678,30 +764,130 @@ export function discriminatedSubtypes(program, model) {
         return [];
     return model.derivedModels.filter((derived) => includeDerivedModel(derived));
 }
+export function discriminatedBaseOf(program, model) {
+    const discriminator = getDiscriminator(program, model);
+    const subtypes = discriminatedSubtypes(program, model);
+    if (discriminator === undefined || subtypes.length === 0)
+        return undefined;
+    /**
+     * The compiler's own reading of which subtype claims which value, which is what openapi3 writes
+     * the `mapping` from.
+     */
+    const claimed = [
+        ...ignoreDiagnostics(getDiscriminatedUnionFromInheritance(model, discriminator)).variants.keys(),
+    ];
+    const declared = discriminatorPropertyOf(program, model, discriminator.propertyName);
+    /**
+     * Undeclared, the discriminator is the `string` openapi3 adds to the base - open. Declared, it is
+     * closed only where its type is a finite set of strings.
+     */
+    const values = declared === undefined ? undefined : closedValuesOf(declared.type);
+    const beside = subtypes.filter((subtype) => isValidatedWithBaseArm(program, subtype));
+    return {
+        propertyName: discriminator.propertyName,
+        dispatched: subtypes.filter((subtype) => !beside.includes(subtype)),
+        beside,
+        claimed,
+        open: values === undefined || values.some((value) => !claimed.includes(value)),
+    };
+}
+/** Whether a model is a base validated as a `z.union` rather than a `z.discriminatedUnion`. */
+function isValidatedWithBaseArm(program, model) {
+    const base = discriminatedBaseOf(program, model);
+    return base !== undefined && (base.open || base.beside.length > 0);
+}
+/** The base's own discriminator property, matched by wire name as openapi3 matches it. */
+function discriminatorPropertyOf(program, model, propertyName) {
+    return inheritedAndOwnProperties(model).find((property) => rawPropertyKey(program, property) === propertyName);
+}
+/** The strings a type admits, where they are finite; `undefined` where it admits any string. */
+function closedValuesOf(type) {
+    if (type.kind === "String")
+        return [type.value];
+    if (type.kind === "EnumMember") {
+        const value = type.value ?? type.name;
+        return typeof value === "string" ? [value] : undefined;
+    }
+    const members = type.kind === "Enum"
+        ? [...type.members.values()]
+        : type.kind === "Union"
+            ? [...type.variants.values()].map((variant) => variant.type)
+            : undefined;
+    if (members === undefined)
+        return undefined;
+    const values = [];
+    for (const member of members) {
+        const closed = closedValuesOf(member);
+        if (closed === undefined)
+            return undefined;
+        values.push(...closed);
+    }
+    return values;
+}
+/**
+ * The base arm's discriminator, refused for every value a subtype claims.
+ *
+ * **Without this a known kind falls through to the base.** `z.union` tries the dispatch and then the
+ * base arm, and a base with subtypes is never sealed, so `{kind: "sparrow", wingspan: 1, x: 1}` -
+ * refused by the sealed `Sparrow` - would be accepted as a `Bird` with `x` stripped. Guarded, a value
+ * naming a subtype is validated as that subtype and nothing else.
+ *
+ * `abort` keeps this refusal out of the error a caller reads: Zod reports the one arm that did not
+ * abort, which for a known kind is the subtype that was actually broken.
+ */
+function guardedDiscriminator(schema, base, model) {
+    if (base.claimed.length === 0)
+        return schema;
+    const test = base.claimed.map((value) => `value !== ${literal(value)}`).join(" && ");
+    const error = literal(`Validated as the subtype this '${base.propertyName}' names, not as '${model.name}'.`);
+    return `${schema}.refine((value) => ${test}, { abort: true, error: ${error} })`;
+}
 function modelToZod(program, model) {
     /**
-     * **A `@discriminator` base is a CHOICE between its subtypes, not a shape of its own.**
+     * **A `@discriminator` base is a CHOICE between its subtypes, and its own shape for any value
+     * naming none of them.** See {@link DiscriminatedBase}.
      *
      * `@discriminator("kind") model Bird { kind: string; wingspan: int32 }` with four models extending
      * it reaches OpenAPI as a component carrying `discriminator: {propertyName, mapping}`, and the
      * mapping is an instruction: validate the body against whichever subtype the discriminator names.
-     * Emitting the base's own properties instead produced `z.object({kind: z.string(), wingspan})`,
+     * Emitting the base's own properties alone produced `z.object({kind: z.string(), wingspan})`,
      * which accepts `{kind: "eagle"}` while ignoring everything `Eagle` actually declares - a
      * polymorphic endpoint validating none of its polymorphism.
      *
-     * `z.discriminatedUnion` is the faithful encoding and composes both ways this corpus needs.
-     * Measured on Zod 4.4.3: a union may be an OPTION of another union, which is how
+     * `z.discriminatedUnion` is the faithful encoding of the dispatch and composes both ways this
+     * corpus needs. Measured on Zod 4.4.3: a union may be an OPTION of another union, which is how
      * `Fish -> Shark -> SawShark` works; and an option carrying a getter that refers back to the union
      * being defined does **not** throw, because the discriminator is read without enumerating the rest
      * of the shape. `Eagle.friends?: Bird[]` is exactly that, and it decides whether polymorphism and
      * recursion can coexist at all.
+     *
+     * **`z.discriminatedUnion` has no arm for "any other value"**, and `unionFallback` cannot add one:
+     * it retries the same options, each of which must carry literal discriminator values. So an open
+     * base is `z.union([dispatch, ...nested bases, base arm])`, every arm exclusive on the
+     * discriminator - each subtype by its literal, the base arm by {@link guardedDiscriminator}.
      */
-    const subtypes = discriminatedSubtypes(program, model);
-    if (subtypes.length > 0) {
-        const discriminator = getDiscriminator(program, model);
-        const options = subtypes.map((derived) => typeToZod(program, derived));
-        return `z.discriminatedUnion(${JSON.stringify(discriminator?.propertyName)}, [${options.join(", ")}])`;
+    const base = discriminatedBaseOf(program, model);
+    if (base !== undefined) {
+        const arms = [];
+        if (base.dispatched.length > 0) {
+            const options = base.dispatched.map((derived) => typeToZod(program, derived));
+            arms.push(`z.discriminatedUnion(${literal(base.propertyName)}, [${options.join(", ")}])`);
+        }
+        arms.push(...base.beside.map((derived) => typeToZod(program, derived)));
+        if (base.open)
+            arms.push(modelObjectToZod(program, model, base));
+        return arms.length === 1 ? (arms[0] ?? UNREPRESENTABLE) : `z.union([${arms.join(", ")}])`;
     }
+    return modelObjectToZod(program, model);
+}
+/**
+ * A model as the object of its own properties, inherited ones included.
+ *
+ * **Given a discriminated base, this is its base arm**: the same object, with its discriminator
+ * refused for every value a subtype claims, and - where the base does not declare the discriminator -
+ * the required `string` openapi3 adds to the base's properties in its place.
+ */
+function modelObjectToZod(program, model, base) {
     const indexer = effectiveIndexer(model);
     const indexerKey = indexer?.key.name;
     const declared = inheritedAndOwnProperties(model);
@@ -816,13 +1002,23 @@ function modelToZod(program, model) {
          * parameters for the reason `renderSchemas` names both: one leaves the input side `unknown`.
          */
         const annotation = deferred ? (annotateDeferred(property) ?? "") : "";
+        const guarded = base !== undefined && rawPropertyKey(program, property) === base.propertyName
+            ? guardedDiscriminator(value, base, model)
+            : value;
         return {
             deferred,
             text: deferred
-                ? `\tget ${key}()${annotation} {\n\t\treturn ${value};\n\t},`
-                : `\t${key}: ${value},`,
+                ? `\tget ${key}()${annotation} {\n\t\treturn ${guarded};\n\t},`
+                : `\t${key}: ${guarded},`,
         };
     });
+    if (base !== undefined &&
+        discriminatorPropertyOf(program, model, base.propertyName) === undefined) {
+        members.push({
+            deferred: false,
+            text: `\t${objectKey(base.propertyName)}: ${guardedDiscriminator("z.string()", base, model)},`,
+        });
+    }
     const entries = members.map((member) => member.text);
     /**
      * A model-level `@refine` goes through the same path as every other constraint, so the predicate's
@@ -901,8 +1097,10 @@ const NUMERIC_EXPRESSIONS = ["z.number()", "z.int(", "z.int32(", "z.uint32("];
 export function wireKindOf(program, type) {
     if (type.kind === "Scalar") {
         const encoded = encodedTypeOf(program, type);
-        if (encoded !== undefined && encoded !== type)
-            return wireKindOf(program, encoded);
+        if (encoded !== undefined && encoded !== type) {
+            // Reported by the schema walk; a chain with no end has no kind to decode into.
+            return encodeCycleOf(program, type) === undefined ? wireKindOf(program, encoded) : undefined;
+        }
         for (let current = type; current !== undefined; current = current.baseScalar) {
             const mapped = SCALARS[current.name];
             if (mapped === undefined)
@@ -945,7 +1143,16 @@ export function wireKindOf(program, type) {
  * Exported so there is one answer to this question. There were two sites and only one of them knew.
  */
 export function objectKey(name) {
-    return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
+    /**
+     * **`__proto__` is the one name a key cannot spell plainly.** In an object literal, `__proto__:`
+     * - quoted or not - sets the object's prototype rather than declaring a key, so the emitted shape
+     * had no such property: it vanished from the published JSON Schema, and under
+     * `seal-object-schemas` every body carrying it was refused as an unrecognised key. A computed
+     * key declares it, in a value and in a type alike. See `unenforceable-property-name`.
+     */
+    if (name === "__proto__")
+        return `[${literal(name)}]`;
+    return /^[A-Za-z_$][\w$]*$/.test(name) ? name : literal(name);
 }
 /**
  * A doc string as a JSDoc comment, indented, or `""` when there is none.
@@ -1063,9 +1270,56 @@ const PARAMETER_STYLE_ENCODINGS = new Set([
     "ArrayEncoding.commaDelimited",
     "ArrayEncoding.newlineDelimited",
 ]);
+/**
+ * **A date-time header with no `@encode` is an RFC 7231 HTTP-date, as if it said
+ * `@encode(DateTimeKnownEncoding.rfc7231)`.**
+ *
+ * That is TypeSpec's wire form for one, and `@typespec/openapi3` publishes it as
+ * `format: http-date` from `applyEncoding`'s `isDateTimeHeader` branch, which this emitter did not
+ * follow. The header fell through to the scalar's default, `z.iso.datetime({ offset: true })`, so a
+ * request sending it as the document describes was refused with 400, and a handler setting it as an
+ * HTTP-date failed its own response contract with 500 (issue #4). The explicit encoding already
+ * emitted `z.string()`, and this is that.
+ *
+ * **The predicate is openapi3's: the header's own schema carries `format: date-time`.** That is
+ * the standard `utcDateTime` or `offsetDateTime` itself. A declared scalar extending one is
+ * published as a `$ref`, a list carries the format on its items, and `T | null` is an `anyOf`
+ * under 3.1 and 3.2 - the versions this package grades against - so none of those is an HTTP-date
+ * in the document, and none is here. (3.0 publishes the nullable one as `nullable: true` beside an
+ * `http-date` format; the graded documents do not.)
+ */
+function isDateTimeHeader(program, property) {
+    const type = property.type;
+    return isHeader(program, property) && type.kind === "Scalar" && isStdDateTime(program, type);
+}
+function isStdDateTime(program, scalar) {
+    const { checker } = program;
+    return (scalar === checker.getStdType("utcDateTime") || scalar === checker.getStdType("offsetDateTime"));
+}
+/** Whether a property's value, or a scalar, is a date-time: one of the two, or built on one. */
+function isDateTime(program, target) {
+    const type = target.kind === "ModelProperty" ? (nullableInnerOf(target.type) ?? target.type) : target;
+    for (let current = type.kind === "Scalar" ? type : undefined; current !== undefined; current = current.baseScalar) {
+        if (isStdDateTime(program, current))
+            return true;
+    }
+    return false;
+}
 export function encodedTypeOf(program, target) {
     const encoded = getEncode(program, target);
-    if (encoded === undefined)
+    if (encoded === undefined) {
+        return target.kind === "ModelProperty" && isDateTimeHeader(program, target)
+            ? program.checker.getStdType("string")
+            : undefined;
+    }
+    /**
+     * **`rfc3339` on a date-time is the form it already has, so it changes nothing.** openapi3's
+     * `mergeFormatAndEncoding` keeps `format: date-time` for it, and the type it reports, `string`,
+     * emitted `z.string()`: the explicit spelling of the default dropped the date-time check the
+     * document still states. Only the encodings that change the wire form - `rfc7231`,
+     * `unixTimestamp` - change the type.
+     */
+    if (encoded.encoding === "rfc3339" && isDateTime(program, target))
         return undefined;
     if (target.kind === "ModelProperty" &&
         isQueryParam(program, target) &&
@@ -1091,9 +1345,26 @@ export function propertyToZod(program, property) {
     // wrapper is kept: `@encode` changes what the value IS, not whether it may be absent.
     const encoded = encodedTypeOf(program, property);
     const declared = encoded ?? nullable ?? property.type;
-    const base = nullable === undefined || encoded !== undefined
-        ? applyConstraints(program, typeToZod(program, declared), property)
-        : `${applyConstraints(program, typeToZod(program, declared), property)}.nullable()`;
+    const bare = nullable === undefined || encoded !== undefined;
+    /**
+     * **One description per position, and a property's own doc wins over its scalar's.**
+     *
+     * openapi3 publishes `subject: Subject` as `{ $ref: Subject, description: <the property's doc> }`,
+     * and a reader takes the sibling over what the reference carries. A scalar here is inlined rather
+     * than referenced, so where the property's value IS the scalar, its schema is taken without its
+     * description and the one the position publishes is decided once: the property's doc, else the
+     * scalar's. Otherwise a documented property of a documented scalar was written
+     * `.describe(a).describe(b)`, which says the same thing in a way no one would write.
+     *
+     * Under `.nullable()` the scalar keeps its own, inside the wrapper: openapi3 publishes
+     * `anyOf: [{ $ref: Subject }, { type: "null" }]` there, so the scalar's description belongs to the
+     * branch and only the property's belongs to the property.
+     */
+    const inlinedScalar = bare && declared.kind === "Scalar";
+    const value = inlinedScalar ? scalarSchemaOf(program, declared) : typeToZod(program, declared);
+    const constrained = applyConstraints(program, value, property);
+    const base = bare ? constrained : `${constrained}.nullable()`;
+    const description = getDoc(program, property) ?? (inlinedScalar ? scalarDocOf(program, declared) : undefined);
     /**
      * **Optionality is a function of the position too, not only of the `?` in the spec.**
      *
@@ -1104,6 +1375,7 @@ export function propertyToZod(program, property) {
      * predicate `@typespec/openapi3` uses to decide the `required` list.
      */
     const optional = property.optional || isOptionalAt(program, property);
+    reportInheritedName(program, property, optional);
     /**
      * **A default only applies where the document says the property may be absent.**
      *
@@ -1125,7 +1397,7 @@ export function propertyToZod(program, property) {
             target: property,
             format: { name: property.name },
         });
-        return base;
+        return described(base, description);
     }
     /**
      * A TypeSpec default (`basis?: string = "s1159"`) becomes `.default(...)`, which in Zod also makes
@@ -1136,7 +1408,7 @@ export function propertyToZod(program, property) {
      */
     const defaulted = defaultOf(program, property);
     if (defaulted !== undefined)
-        return `${base}.default(${defaulted})`;
+        return described(`${base}.default(${defaulted})`, description);
     /**
      * **`.exactOptional()`, because the document says the KEY may be absent and nothing more.**
      *
@@ -1155,7 +1427,66 @@ export function propertyToZod(program, property) {
      * differential's serialisation axis is untouched, and `def.type` is still `"optional"`, so the
      * shape describers read it unchanged.
      */
-    return optional ? `${base}.exactOptional()` : base;
+    return described(optional ? `${base}.exactOptional()` : base, description);
+}
+/**
+ * The names every JavaScript object inherits, which Zod reads in place of an absent property.
+ * `__proto__` is among them and is the different case: Zod skips it outright.
+ */
+const INHERITED_NAMES = new Set(Object.getOwnPropertyNames(Object.prototype));
+/** Properties already reported, by declaration: one property renders once per visibility. */
+const reportedNames = new WeakMap();
+/**
+ * **A wire name the validator cannot treat as an ordinary key is reported where it bites.** See
+ * `unenforceable-property-name` and `optional-prototype-name` in `lib.ts` for why each is a
+ * warning and what each costs.
+ *
+ * Reported here rather than from a walk over the program because `optional` is a fact about the
+ * POSITION: a PATCH makes a required property optional, and only there does an inherited name
+ * refuse its omission. Once per declaration, by its syntax node, because a visibility projection
+ * hands this a different `ModelProperty` for the same one.
+ */
+function reportInheritedName(program, property, optional) {
+    const name = wireNameOf(program, property);
+    if (!INHERITED_NAMES.has(name))
+        return;
+    const unenforceable = name === "__proto__";
+    if (!unenforceable && !optional)
+        return;
+    const declaration = property.node ?? property;
+    let reported = reportedNames.get(program);
+    if (reported === undefined)
+        reportedNames.set(program, (reported = new WeakSet()));
+    if (reported.has(declaration))
+        return;
+    reported.add(declaration);
+    if (unenforceable) {
+        reportDiagnostic(program, {
+            code: "unenforceable-property-name",
+            target: property,
+            format: { name },
+        });
+    }
+    else {
+        reportDiagnostic(program, {
+            code: "optional-prototype-name",
+            target: property,
+            format: { name },
+        });
+    }
+}
+/** The key a property is validated under: its parameter name, or its name in a JSON body. */
+function wireNameOf(program, property) {
+    if (isHeader(program, property))
+        return getHeaderFieldName(program, property);
+    if (isQueryParam(program, property))
+        return getQueryParamName(program, property) ?? property.name;
+    if (isPathParam(program, property))
+        return getPathParamName(program, property) ?? property.name;
+    if (isCookieParam(program, property)) {
+        return getCookieParamOptions(program, property)?.name ?? property.name;
+    }
+    return rawPropertyKey(program, property);
 }
 /**
  * A default value as a JS literal, or `undefined` where this emitter cannot render one.
@@ -1180,7 +1511,7 @@ export function propertyToZod(program, property) {
  */
 function renderValue(value) {
     if (value.valueKind === "StringValue")
-        return JSON.stringify(value.value);
+        return literal(value.value);
     if (value.valueKind === "NumericValue")
         return String(value.value.asNumber());
     if (value.valueKind === "BooleanValue")
@@ -1189,7 +1520,7 @@ function renderValue(value) {
         return "null";
     if (value.valueKind === "EnumValue") {
         const member = value.value;
-        return JSON.stringify(member.value ?? member.name);
+        return literal(member.value ?? member.name);
     }
     if (value.valueKind === "ArrayValue") {
         const rendered = value.values.map(renderValue);
@@ -1203,7 +1534,7 @@ function renderValue(value) {
             const rendered = renderValue(descriptor.value);
             if (rendered === undefined)
                 return undefined;
-            entries.push(`${JSON.stringify(name)}: ${rendered}`);
+            entries.push(`${literal(name)}: ${rendered}`);
         }
         return `{${entries.join(", ")}}`;
     }
@@ -1330,13 +1661,13 @@ export function typeToZodBody(program, type) {
         case "Union":
             return unionToZod(program, type);
         case "String":
-            return `z.literal(${JSON.stringify(type.value)})`;
+            return `z.literal(${literal(type.value)})`;
         case "Number":
             return `z.literal(${type.value})`;
         case "Boolean":
             return `z.literal(${String(type.value)})`;
         case "EnumMember":
-            return `z.literal(${JSON.stringify(type.value ?? type.name)})`;
+            return `z.literal(${literal(type.value ?? type.name)})`;
         /**
          * **A named union VARIANT is a type you can refer to, and it is not the union.**
          *