typespec-http-zod 0.29.0 → 0.30.0

package/dist/src/api.d.ts

@@ -257,6 +257,19 @@ export interface EmittedRoute {
      * a scalar. Empty when there is none, never `undefined`.
      */
     readonly decodedPathParameters: readonly string[];
+    /**
+     * Every pair of inputs a handler would be handed under ONE key - `@header("x")` beside
+     * `@query("x")`, two `@query("x")`, a `@path id` beside a `@header("id")`, a parameter named as
+     * the body is. Empty for almost every operation.
+     *
+     * **A server emitter spreads the parameter groups into one input, so the later group's value
+     * silently replaced the earlier one**, after each had been validated against its own schema.
+     * `@typespec/http` refuses only a path and a query parameter of one name. The handler input has
+     * one value per key and cannot carry both, so a server should not mount such an operation; this
+     * package reports it as `shared-input-key`, and states the key as both declarations at once. See
+     * {@link SharedInputKey}.
+     */
+    readonly sharedInputKeys: readonly SharedInputKey[];
     /**
      * A query string written into the route itself, as the pairs it spells:
      * `/items?fixed=true{&param}` carries `[["fixed", "true"]]`. It identifies the route as much as
@@ -439,6 +452,17 @@ export interface EmittedRoute {
      */
     readonly security: readonly SecurityRequirement[];
 }
+/** Where a value reaches a handler's input from. */
+export type InputLocation = "path" | "query" | "header" | "cookie" | "body";
+/** Two inputs a handler would be handed under one key. See {@link EmittedRoute.sharedInputKeys}. */
+export interface SharedInputKey {
+    /** The key both arrive under, as the input spells it. */
+    readonly key: string;
+    /** Where the input declared first comes from. */
+    readonly first: InputLocation;
+    /** Where the input declared second comes from. */
+    readonly second: InputLocation;
+}
 export declare function collectRoutes(program: Program, registry: SchemaRegistry, service: HttpService): EmittedRoute[];
 /** Whether emitted source references `name` as an identifier rather than as part of a longer one. */
 export declare function referencedIn(source: string, name: string): boolean;

package/dist/src/api.js

@@ -11,7 +11,7 @@ import { resolveVersioningModule, serviceSnapshots } from "./versioning.js";
 import { EXPLODED_QUERY_SOURCE, explodedQueryCall, needsExpansionDecoding, routeTemplateOf, URI_EXPANSION_SOURCE, uriExpansionCall, } from "./uri-template.js";
 export { CONTENTLESS_STATUS_CODES, STATUS_CODES } from "./statuses.js";
 export { isJsonMediaType, isMediaRange, isTextualMediaType, mediaTypeEssenceOf, mediaTypeTypeOf, resultMembersOf, statusCodesOf, } from "./results.js";
-import { collectExternalImports, isPayloadProperty, noteDeclaredVocabularies, noteKeyVocabularies, objectKey, wireKindOf, withContractsPackage, withSealedObjects, withVisibility, } from "./zod.js";
+import { collectExternalImports, encodedTypeOf, isPayloadProperty, noteDeclaredVocabularies, noteKeyVocabularies, objectKey, wireKindOf, withContractsPackage, withSealedObjects, withVisibility, } from "./zod.js";
 /**
  * `typespec-http-zod` - Zod validators and framework-free contract types from a TypeSpec HTTP
  * service, agreeing with the OpenAPI document `@typespec/openapi3` publishes from the same source.
@@ -328,19 +328,20 @@ function resolveResponses(program, operation) {
                 file: false,
             };
             for (const content of response.responses) {
-                if (entry.body === undefined && content.body?.bodyKind === "single") {
-                    entry.body = bodyTypeOf(content.body.type);
+                const body = presentBody(content.body);
+                if (entry.body === undefined && body?.bodyKind === "single") {
+                    entry.body = body.type;
                 }
                 /**
                  * **An `Http.File` response's body is its contents, served as bytes.** The same reading
                  * as a file request body: a media type and nothing to serialise. Read only for
                  * `"single"`, every download in `type/file` declared `image/png` and was served empty.
                  */
-                if (entry.body === undefined && content.body?.bodyKind === "file") {
-                    entry.body = content.body.contents.type;
+                if (entry.body === undefined && body?.bodyKind === "file") {
+                    entry.body = body.contents.type;
                     entry.file = true;
                 }
-                for (const contentType of content.body?.contentTypes ?? []) {
+                for (const contentType of body?.contentTypes ?? []) {
                     entry.contentTypes.add(contentType);
                 }
                 for (const [name, property] of Object.entries(content.headers ?? {})) {
@@ -606,6 +607,26 @@ export function errorBodyOf(program, service) {
 function bodyTypeOf(type) {
     return isVoidType(type) || isNeverType(type) ? undefined : type;
 }
+/**
+ * A declared body as the wire carries it: `undefined` where it is `void` or `never`, so no media
+ * type is listed for it either.
+ *
+ * **`@typespec/http` keeps a body it was told is empty**, media types and all, whenever the response
+ * or request declares it explicitly - `@statusCode _: 409; @body body: void`. Every artefact read
+ * the media types off it, so a 409 with no body was published as `contentTypes:
+ * ["application/json"]` and `schema: undefined`, which a consumer reads as a body it cannot validate,
+ * and a `void` request body reached the Zod walk and refused the compile. openapi3 publishes no
+ * `content` for `void`. For `never` it publishes `schema: {}` - any value - because its body paths
+ * test only for `void`, while it omits a `never` PROPERTY from every schema; a type with no values is
+ * no body here, and `reference.md` records the divergence.
+ */
+function presentBody(body) {
+    return body?.bodyKind === "single" && bodyTypeOf(body.type) === undefined ? undefined : body;
+}
+/** The operation's request body, absent where it is declared `void` or `never`. */
+function requestBodyParameterOf(operation) {
+    return presentBody(operation.parameters.body);
+}
 /**
  * The media types this operation's success response can be served as.
  *
@@ -623,15 +644,24 @@ function responseContentTypesOf(operation, status) {
         if (response.statusCodes !== status)
             continue;
         for (const content of response.responses) {
-            for (const contentType of content.body?.contentTypes ?? [])
+            for (const contentType of presentBody(content.body)?.contentTypes ?? []) {
                 types.add(contentType);
+            }
         }
     }
     return [...types];
 }
-/** The type a parameter actually crosses the wire as, after any `@encode` on the property. */
+/**
+ * The type a parameter actually crosses the wire as, after any `@encode` on the property.
+ *
+ * **Read through `encodedTypeOf`, the rule the parameter's schema is built by.** This read
+ * `getEncode(...).type` directly, which for an array encoding on a query parameter is `string`: the
+ * schema kept the declared `int32[]`, as the document does, while the element decoder found no list
+ * and left `"1"` to meet `z.int32()`. Every path here that decides how a value is split, decoded or
+ * expanded reads this type, so none of them can disagree with the schema it feeds.
+ */
 function encodedParameterType(program, property) {
-    return getEncode(program, property)?.type ?? property.type;
+    return encodedTypeOf(program, property) ?? property.type;
 }
 /**
  * The wire kind of an ARRAY parameter's elements, or `undefined` where it is not such an array.
@@ -856,7 +886,7 @@ function isParseableMediaType(type) {
 }
 /** The declared request body type, if the operation takes one. */
 function requestBodyOf(operation) {
-    const body = operation.parameters.body;
+    const body = requestBodyParameterOf(operation);
     if (body?.bodyKind === "single")
         return body.type;
     return undefined;
@@ -893,9 +923,17 @@ const COLLECTION_DELIMITERS = {
     "ArrayEncoding.commaDelimited": ",",
     "ArrayEncoding.newlineDelimited": "\n",
 };
-/** Whether the declared type is a list, which is what makes a delimiter meaningful. */
-function isCollectionParameter(property) {
-    return isArrayType(property.type);
+/**
+ * Whether the parameter crosses the wire as a list, which is what makes a delimiter meaningful.
+ *
+ * **The encoded type, not the declared one.** `@header @encode(ArrayEncoding.commaDelimited) tags:
+ * string[]` is a string on the wire - the document publishes `type: string` - and its schema is
+ * `z.string()`; reading the declared list split `"a,b"` into an array and handed that to the string
+ * schema, so every request was refused. Only a query parameter keeps its list under an array
+ * encoding, and only there is a split undone.
+ */
+function isCollectionParameter(program, property) {
+    return isArrayType(encodedParameterType(program, property));
 }
 /**
  * Whether the values arrive one per OCCURRENCE (RFC 6570 explode) rather than joined into one.
@@ -906,8 +944,8 @@ function isCollectionParameter(property) {
  * refused a conformant request while accepting the same list sent twice, which no document
  * describes. Found by the first consumer's `?topics=ip` (#1).
  */
-function isExplodedCollection(parameter) {
-    return (isCollectionParameter(parameter.param) &&
+function isExplodedCollection(program, parameter) {
+    return (isCollectionParameter(program, parameter.param) &&
         (parameter.type === "query" || parameter.type === "header") &&
         parameter.explode === true);
 }
@@ -919,7 +957,7 @@ function isExplodedCollection(parameter) {
  * Those are the two that looked correct because the document and the validator agreed.
  */
 function collectionDelimiterOf(program, parameter) {
-    if (!isCollectionParameter(parameter.param))
+    if (!isCollectionParameter(program, parameter.param))
         return undefined;
     if (parameter.type !== "query" && parameter.type !== "header")
         return undefined;
@@ -1078,6 +1116,9 @@ function parameterSchemasOf(program, operation, registry, segments,
 /** The names of a query string written into the route itself, which no parameter may gather. */
 literalQueryNames) {
     const byTarget = {};
+    const add = (target, key, expression) => {
+        (byTarget[target] ??= []).push(`\t${objectKey(key)}: ${expression},`);
+    };
     let accept;
     /** Form-exploded records and models, gathered back under their names around the query object. */
     const gathered = [];
@@ -1115,8 +1156,21 @@ literalQueryNames) {
          * via `resolveEncodedName` - the document publishes one name per parameter, and it is this one.
          * The TypeSpec property name is an authoring convenience that does not survive to the contract.
          */
+        /**
+         * **Two parameters of one location and one wire name are one value on the wire**, and both
+         * declarations apply to it: their schemas are intersected and the value is decoded once, by
+         * the first declaration's wire form, so each judges the same decoded value. Decoded by each
+         * and then intersected, `@query("x") a: string` beside `@query("x") b: int32` would hand Zod
+         * `"1"` and `1` to merge, which it does not refuse but throws on. An object literal cannot
+         * hold the key twice either. `shared-input-key` reports it.
+         */
+        const sharing = operation.parameters.parameters.filter((other) => other.type === parameter.type && other.name === parameter.name);
+        if (sharing[0] !== parameter)
+            continue;
         const delimiter = collectionDelimiterOf(program, parameter);
-        const declared = registry.expressionForProperty(parameter.param);
+        const declared = sharing
+            .map((other) => registry.expressionForProperty(other.param))
+            .reduce((first, other) => `${first}.and(${other})`);
         /**
          * The wire form is decoded before it is validated, never instead of it. `z.preprocess` undoes
          * exactly the flattening the document's `style` describes and then applies the schema the
@@ -1146,7 +1200,7 @@ literalQueryNames) {
          * occurrences arrive already an array and pass through untouched, exactly as the delimiter
          * arm leaves a pre-split value alone.
          */
-        const boxedOrSplit = isExplodedCollection(parameter)
+        const boxedOrSplit = isExplodedCollection(program, parameter)
             ? `z.preprocess((raw) => (typeof raw === "string" ? [raw] : raw), ${decoded})`
             : delimiter === undefined
                 ? decoded
@@ -1156,11 +1210,12 @@ literalQueryNames) {
          * wire did: `array.a.b` becomes `["a", "b"]`, then the element decoder and the document's schema
          * run on that. See {@link uriExpansionCall}.
          */
-        const shape = expansionShapeOf(parameter.param.type);
-        const values = recordValuesOf(program, parameter.param.type);
+        const wire = encodedParameterType(program, parameter.param);
+        const shape = expansionShapeOf(wire);
+        const values = recordValuesOf(program, wire);
         let expression = boxedOrSplit;
         if (parameter.type === "path") {
-            const segment = decodedSegmentOf(parameter, segments);
+            const segment = decodedSegmentOf(program, parameter, segments);
             if (segment !== undefined) {
                 expression = `z.preprocess(${uriExpansionCall({ ...segment, name: parameter.name, shape, values })}, ${decoded})`;
             }
@@ -1171,9 +1226,7 @@ literalQueryNames) {
                  * `{?param*}` over an object expands to the object's own keys, so there is no `param` key for
                  * this entry to read; the gatherer around the query object puts one back.
                  */
-                const model = parameter.param.type.kind === "Model" && parameter.param.type.indexer === undefined
-                    ? parameter.param.type
-                    : undefined;
+                const model = wire.kind === "Model" && wire.indexer === undefined ? wire : undefined;
                 const properties = model === undefined ? [] : modelPropertiesOf(model);
                 gathered.push(explodedQueryCall({
                     name: parameter.name,
@@ -1182,10 +1235,10 @@ literalQueryNames) {
                         ? undefined
                         : properties.map((property) => resolveEncodedName(program, property, "application/json")),
                     numbers: properties
-                        .filter((property) => wireKindOf(program, property.type) === "number")
+                        .filter((property) => wireKindOf(program, encodedParameterType(program, property)) === "number")
                         .map((property) => resolveEncodedName(program, property, "application/json")),
                     booleans: properties
-                        .filter((property) => wireKindOf(program, property.type) === "boolean")
+                        .filter((property) => wireKindOf(program, encodedParameterType(program, property)) === "boolean")
                         .map((property) => resolveEncodedName(program, property, "application/json")),
                     values,
                 }));
@@ -1194,8 +1247,7 @@ literalQueryNames) {
                 expression = `z.preprocess(${uriExpansionCall({ prefix: "", suffix: "", operator: "", name: parameter.name, explode: false, shape, values })}, ${decoded})`;
             }
         }
-        const entry = `\t${objectKey(parameter.name)}: ${expression},`;
-        (byTarget[parameter.type] ??= []).push(entry);
+        add(parameter.type, parameter.name, expression);
         /**
          * **On a route several operations share, `accept` SELECTS the operation - it is not a
          * constraint on one of them.** Each member declares its own literal, so validating against any
@@ -1210,15 +1262,15 @@ literalQueryNames) {
                 accept = { name: parameter.name, value: declared.value };
         }
         else if (parameter.type === "header") {
-            (byTarget["header-without-accept"] ??= []).push(entry);
+            add("header-without-accept", parameter.name, expression);
         }
     }
     const fileContentType = fileContentTypeOf(operation);
     if (fileContentType !== undefined) {
         // The same decoding a declared `Content-Type` header gets: parameters dropped, lowercased.
-        const entry = `\t${objectKey("Content-Type")}: ${mediaTypeDecoded(registry.expressionFor(fileContentType.type))},`;
-        (byTarget["header"] ??= []).push(entry);
-        (byTarget["header-without-accept"] ??= []).push(entry);
+        const expression = mediaTypeDecoded(registry.expressionFor(fileContentType.type));
+        add("header", "Content-Type", expression);
+        add("header-without-accept", "Content-Type", expression);
     }
     const shape = (target) => {
         const entries = byTarget[target];
@@ -1237,20 +1289,25 @@ literalQueryNames) {
         accept,
     };
 }
-/** What a parameter's value decodes into once its expansion is undone. */
 /**
  * The route segment a path parameter's validator decodes, or `undefined` where it validates the
  * segment's text as the value. The one rule for both the validator and
  * {@link EmittedRoute.decodedPathParameters}, so a consumer reading the route cannot disagree with
  * the validator it describes.
+ *
+ * **Shaped from the encoded type, as the validator's schema is.** `@path
+ * @encode(ArrayEncoding.commaDelimited) ids: string[]` is a string on the wire, published as `type:
+ * string`, and validated by `z.string()`; shaped from the declared list it was expanded into
+ * `["a", "b"]` first, and every request was refused.
  */
-function decodedSegmentOf(parameter, segments) {
+function decodedSegmentOf(program, parameter, segments) {
     const segment = segments.find((candidate) => candidate.kind === "expression" && candidate.parameter === parameter.name);
     return segment !== undefined &&
-        needsExpansionDecoding(segment, expansionShapeOf(parameter.param.type))
+        needsExpansionDecoding(segment, expansionShapeOf(encodedParameterType(program, parameter.param)))
         ? segment
         : undefined;
 }
+/** What a parameter's value decodes into once its expansion is undone. */
 function expansionShapeOf(type) {
     if (isArrayType(type))
         return "list";
@@ -1280,7 +1337,7 @@ function modelPropertiesOf(model) {
  * `undefined` where the body is not a file, or where the operation already declares the header.
  */
 function fileContentTypeOf(operation) {
-    const body = operation.parameters.body;
+    const body = requestBodyParameterOf(operation);
     if (body?.bodyKind !== "file")
         return undefined;
     const declared = operation.parameters.parameters.some((parameter) => parameter.type === "header" && parameter.name.toLowerCase() === "content-type");
@@ -1302,7 +1359,7 @@ function fileContentTypeOf(operation) {
  * body. A read-only property is not sent, so it contributes nothing.
  */
 function mergedBodyKeysOf(program, operation) {
-    const body = operation.parameters.body;
+    const body = requestBodyParameterOf(operation);
     if (body?.bodyKind === "multipart") {
         return body.parts.flatMap((part) => (part.name === undefined ? [] : [part.name]));
     }
@@ -1313,9 +1370,86 @@ function mergedBodyKeysOf(program, operation) {
         .filter((property) => isPayloadProperty(program, property))
         .map((property) => resolveEncodedName(program, property, "application/json")));
 }
+const INPUT_LOCATION_NOUNS = {
+    path: "path parameter",
+    query: "query parameter",
+    header: "header",
+    cookie: "cookie",
+    body: "body",
+};
+/**
+ * The pairs of inputs an operation hands its handler under one key, reported once per pair and
+ * program.
+ *
+ * **Read from the same facts the input is rendered from**: each parameter under its wire name, the
+ * `Content-Type` of an `Http.File` body, and the body where {@link requestBodyPlacementOf} names it.
+ * A merged body is not listed, because that decision already names the body whenever one of its keys
+ * is a parameter's - which is how a `@query("body")` beside a body named `body` stays possible to
+ * write, and why it is caught here rather than there.
+ *
+ * Resolved once per operation, since the route walk and the contract walk both read it and the
+ * warning must be raised once.
+ */
+function sharedInputKeysOf(program, operation) {
+    const resolved = sharedInputKeys.get(operation);
+    if (resolved !== undefined)
+        return resolved;
+    const inputs = [];
+    for (const parameter of operation.parameters.parameters) {
+        if (parameter.type === "path" ||
+            parameter.type === "query" ||
+            parameter.type === "header" ||
+            parameter.type === "cookie") {
+            inputs.push({ key: parameter.name, location: parameter.type, target: parameter.param });
+        }
+    }
+    const fileContentType = fileContentTypeOf(operation);
+    if (fileContentType !== undefined) {
+        inputs.push({ key: "Content-Type", location: "header", target: fileContentType });
+    }
+    const placement = requestBodyPlacementOf(program, operation);
+    const bodyKey = placement.rawBodyProperty ?? placement.bodyProperty;
+    if (bodyKey !== undefined) {
+        inputs.push({
+            key: bodyKey,
+            location: "body",
+            target: requestBodyParameterOf(operation)?.property ?? operation.operation,
+        });
+    }
+    const shared = [];
+    inputs.forEach((input, index) => {
+        const first = inputs.slice(0, index).find((earlier) => earlier.key === input.key);
+        if (first === undefined)
+            return;
+        shared.push({ key: input.key, first: first.location, second: input.location });
+        const format = {
+            operation: operationIdOf(program, operation.operation),
+            key: input.key,
+            first: INPUT_LOCATION_NOUNS[first.location],
+            second: INPUT_LOCATION_NOUNS[input.location],
+        };
+        /**
+         * **Once per program, keyed on what the warning says.** Each emitter that runs the library
+         * collects its own operations, over types a visibility or version projection may have cloned,
+         * so neither the operation nor the declaration is the same object twice: `typespec-hono` beside
+         * `typespec-http-mcp` raised the warning twice per pair.
+         */
+        const reported = sharedInputKeysReported.get(program) ?? new Set();
+        sharedInputKeysReported.set(program, reported);
+        const said = JSON.stringify(format);
+        if (reported.has(said))
+            return;
+        reported.add(said);
+        reportDiagnostic(program, { code: "shared-input-key", target: input.target, format });
+    });
+    sharedInputKeys.set(operation, shared);
+    return shared;
+}
+const sharedInputKeys = new WeakMap();
+const sharedInputKeysReported = new WeakMap();
 function requestBodyPlacementOf(program, operation) {
     const requestType = requestBodyOf(operation);
-    const bodyParameter = operation.parameters.body;
+    const bodyParameter = requestBodyParameterOf(operation);
     const contentTypes = [...(bodyParameter?.contentTypes ?? [])];
     /**
      * A `bytes` body means the BYTES are the contract.
@@ -1506,18 +1640,19 @@ export function collectRoutes(program, registry, service) {
                     .filter((parameter) => parameter.type === "path" && parameter.allowReserved)
                     .map((parameter) => parameter.name),
                 pathSegments: template.segments,
+                sharedInputKeys: sharedInputKeysOf(program, operation),
                 decodedPathParameters: operation.parameters.parameters
-                    .filter((parameter) => decodedSegmentOf(parameter, template.segments) !== undefined)
+                    .filter((parameter) => decodedSegmentOf(program, parameter, template.segments) !== undefined)
                     .map((parameter) => parameter.name),
                 literalQuery: template.literalQuery,
                 responseContentTypes: statusCode === undefined ? [] : responseContentTypesOf(operation, statusCode),
-                requestContentTypes: [...(operation.parameters.body?.contentTypes ?? [])],
+                requestContentTypes: [...(requestBodyParameterOf(operation)?.contentTypes ?? [])],
                 // `isRawBinaryMediaType` is "every declared type is non-JSON", which is the same question
                 // here: a string body under `application/json` IS json, and its reader is the JSON one.
                 requestTextual: requestType !== undefined &&
                     rawBodyProperty === undefined &&
                     isStringType(requestType) &&
-                    isRawBinaryMediaType([...(operation.parameters.body?.contentTypes ?? [])]),
+                    isRawBinaryMediaType([...(requestBodyParameterOf(operation)?.contentTypes ?? [])]),
                 /**
                  * `@summary` first, `@doc` as the fallback.
                  *
@@ -1537,7 +1672,7 @@ export function collectRoutes(program, registry, service) {
                 requestSchema: withVisibility(program, requestVisibility, () => {
                     // Multipart first: its body has no single type to walk, and skipping it left every
                     // such route mounted with nothing checking the request at all.
-                    const parameterBody = operation.parameters.body;
+                    const parameterBody = requestBodyParameterOf(operation);
                     if (parameterBody?.bodyKind === "multipart") {
                         return multipartSchemaOf(program, parameterBody, registry);
                     }
@@ -2135,7 +2270,7 @@ function collectRequestTypes(program, registry, service) {
             const body = requestBodyOf(operation);
             const placement = requestBodyPlacementOf(program, operation);
             /** The parts of a multipart body, which `requestBodyOf` deliberately does not return. */
-            const parameterBody = operation.parameters.body;
+            const parameterBody = requestBodyParameterOf(operation);
             /**
              * Headers are part of the input too.
              *
@@ -2155,11 +2290,24 @@ function collectRequestTypes(program, registry, service) {
                  * `"x-thing"` here too: a consumer checking its handlers against these types otherwise
                  * fails to typecheck against a server that is correct.
                  */
-                .map((parameter) => registry.expressionForProperty(parameter.param, parameter.name));
+                .map((parameter) => ({
+                key: parameter.name,
+                line: registry.expressionForProperty(parameter.param, parameter.name),
+            }));
             const fileContentType = fileContentTypeOf(operation);
             if (fileContentType !== undefined) {
-                extraProperties.push(`${objectKey("Content-Type")}: ${registry.expressionFor(fileContentType.type)};`);
+                extraProperties.push({
+                    key: "Content-Type",
+                    line: `${objectKey("Content-Type")}: ${registry.expressionFor(fileContentType.type)};`,
+                });
             }
+            /**
+             * **A key two parameters share is written once per declaration, each in its own part**,
+             * so the intersection types it as both - what the validators beside it accept - where two
+             * members of one object literal do not compile (TS2300). `shared-input-key` reports it.
+             */
+            const repeated = extraProperties.filter((property, index) => extraProperties.slice(0, index).some((earlier) => earlier.key === property.key));
+            const distinct = extraProperties.filter((property) => !repeated.includes(property));
             const parts = [];
             let streamsBody = false;
             let bodyRef;
@@ -2195,9 +2343,11 @@ function collectRequestTypes(program, registry, service) {
                         : `{\n\t${objectKey(placement.bodyProperty)}${placement.optionalBody ? "?" : ""}: ${expression.replaceAll("\n", "\n\t")};\n}`);
                 }
             }
-            if (extraProperties.length > 0) {
-                parts.push(`{\n${extraProperties.map((line) => `\t${line}`).join("\n")}\n}`);
+            if (distinct.length > 0) {
+                parts.push(`{\n${distinct.map(({ line }) => `\t${line}`).join("\n")}\n}`);
             }
+            for (const { line } of repeated)
+                parts.push(`{\n\t${line}\n}`);
             entries.push({
                 operationId: operationIdOf(program, operation.operation),
                 bodyRef,

package/dist/src/constraints.d.ts

@@ -15,6 +15,21 @@ import { type Program, type Type } from "@typespec/compiler";
  * 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;
+/**
+ * **Whether this diagnostic has already been raised against this declaration.**
+ *
+ * Keyed on the code as well as the target. Keying on the target alone once made the memo shared
+ * between every pattern diagnostic, so whichever ran first claimed the declaration and silenced
+ * the rest: measured on `^(\w+\s?)*\-$`, one warning where two were due. The ReDoS judgement has
+ * since moved to a linter rule, which reports per declaration by construction, so that pairing can
+ * no longer meet here - but a memo keyed on the target alone is the wrong shape for the next
+ * diagnostic added beside this one, and costs nothing to keep right.
+ *
+ * The de-duplication itself is per declaration, because emission reaches a scalar once per USE -
+ * 153 times for a single scalar in the reference service - and repeating one warning that often
+ * is noise a reader learns to skip, which is how a real one gets missed.
+ */
+export declare function firstReportOf(program: Program, code: string, target: Type): boolean;
 /**
  * **Whether a `@pattern` can be proven safe against catastrophic backtracking.**
  *

package/dist/src/constraints.js

@@ -160,7 +160,7 @@ const reported = new WeakMap();
  * 153 times for a single scalar in the reference service - and repeating one warning that often
  * is noise a reader learns to skip, which is how a real one gets missed.
  */
-function firstReportOf(program, code, target) {
+export function firstReportOf(program, code, target) {
     let byCode = reported.get(program);
     if (byCode === undefined) {
         byCode = new Map();

package/dist/src/lib.d.ts

@@ -174,11 +174,17 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
     "inline-cycle": {
         readonly default: import("@typespec/compiler").CallableMessage<["type"]>;
     };
+    "encode-cycle": {
+        readonly default: import("@typespec/compiler").CallableMessage<["type", "chain"]>;
+    };
+    "shared-input-key": {
+        readonly default: import("@typespec/compiler").CallableMessage<["operation", "first", "key", "second", "key", "key"]>;
+    };
     "duplicate-declaration": {
         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" | "inline-cycle" | "non-unicode-pattern" | "optional-prototype-name" | "truncated-doc-comment" | "undeclared-discriminator" | "unenforceable-encoded-bound" | "unenforceable-property-name" | "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" | "encode-cycle" | "inline-cycle" | "non-unicode-pattern" | "optional-prototype-name" | "shared-input-key" | "truncated-doc-comment" | "undeclared-discriminator" | "unenforceable-encoded-bound" | "unenforceable-property-name" | "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"]>;
     };
@@ -224,6 +230,12 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "inline-cycle": {
         readonly default: import("@typespec/compiler").CallableMessage<["type"]>;
     };
+    "encode-cycle": {
+        readonly default: import("@typespec/compiler").CallableMessage<["type", "chain"]>;
+    };
+    "shared-input-key": {
+        readonly default: import("@typespec/compiler").CallableMessage<["operation", "first", "key", "second", "key", "key"]>;
+    };
     "duplicate-declaration": {
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
     };
@@ -273,6 +285,12 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "inline-cycle": {
         readonly default: import("@typespec/compiler").CallableMessage<["type"]>;
     };
+    "encode-cycle": {
+        readonly default: import("@typespec/compiler").CallableMessage<["type", "chain"]>;
+    };
+    "shared-input-key": {
+        readonly default: import("@typespec/compiler").CallableMessage<["operation", "first", "key", "second", "key", "key"]>;
+    };
     "duplicate-declaration": {
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
     };

package/dist/src/lib.js

@@ -380,6 +380,44 @@ const diagnostics = {
             default: paramMessage `'${"type"}' closes a reference cycle without passing through anything this emitter can declare, so the cycle has no name to reference itself by. A template instantiation is inlined rather than declared, exactly as '@typespec/openapi3' inlines it, and that emitter refuses the same spec with its own 'inline-cycle' error. Give the type a name with '@friendlyName' so it becomes a declaration, or break the cycle.`,
         },
     },
+    /**
+     * **An `@encode` chain that returns to where it started never reaches a wire type.**
+     *
+     * `@encode("x", Pong) scalar Ping` and `@encode("x", Ping) scalar Pong` compile cleanly - the
+     * compiler checks neither the encoding's name nor where its type leads - and the walks here
+     * followed `@encode` by calling themselves on the encoded type. Measured before this existed:
+     * `RangeError: Maximum call stack size exceeded`, "Emitter crashed! This is a bug."
+     *
+     * **An error, as `inline-cycle` is.** A value of such a scalar has no form on the wire to validate,
+     * so there is no validator to emit. openapi3 reads one link of the chain and publishes a schema
+     * with no `type` at all - `{ format: "x" }` - which states nothing about the value either.
+     */
+    "encode-cycle": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"type"}' is encoded as ${"chain"}: the '@encode' chain returns to a scalar it already passed, so it never reaches a type that crosses the wire. Encode one of them as a standard scalar such as 'string', or break the cycle.`,
+        },
+    },
+    /**
+     * **Two inputs of one operation handed to its handler under one key.**
+     *
+     * A handler's input is the path, query, header and cookie groups spread into one object, with the
+     * body merged or named beside them. `@header("x") a: string` beside `@query("x") b: int32` therefore
+     * reached the handler as one `x`, the header's string replacing the validated number, while the
+     * input was typed `number & string`. `@typespec/http` refuses only a path and a query parameter of
+     * one name; the rest compiled with no diagnostic (typespec-http-graphql, 2026-10-16).
+     *
+     * **A warning, because the spec is valid and openapi3 publishes it**: the parameters are distinct on
+     * the wire. It is the input this package states that cannot carry both, so the key is typed and
+     * validated as both declarations at once, and the contract types still compile. A server emitter
+     * reading `EmittedRoute.sharedInputKeys` declines to mount the operation.
+     */
+    "shared-input-key": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"operation"}' takes the ${"first"} '${"key"}' and the ${"second"} '${"key"}', and a handler's input holds one value under each key, so '${"key"}' is stated as both declarations at once and accepts only a value satisfying both. Give one of them a different name.`,
+        },
+    },
     "duplicate-declaration": {
         severity: "error",
         messages: {

package/dist/src/registry.js

@@ -451,8 +451,8 @@ export class SchemaRegistry {
      * them.
      *
      * **Subtypes are deliberately NOT walked here, because nothing would be walking them.** A
-     * discriminated base renders as `z.discriminatedUnion` over its subtypes, and rendering that
-     * already asks the registry for each one. A loop here looked load-bearing and was measured not to
+     * discriminated base renders as a dispatch over its subtypes - `z.discriminatedUnion`, beside a base
+     * arm where its discriminator is open - and rendering that already asks the registry for each one. A loop here looked load-bearing and was measured not to
      * be: removing it left all 23 polymorphism and differential arms green.
      *
      * **Wrapped in {@link captureBackEdges} and the result discarded.** This call can land on a

package/dist/src/types.js

@@ -1,7 +1,7 @@
 import { getDiscriminatedUnion, isNeverType, resolveEncodedName, } from "@typespec/compiler";
 import { reportDiagnostic } from "./lib.js";
 import { literal } from "./literal.js";
-import { discriminatedSubtypes, effectiveIndexer, emitsDefault, encodedTypeOf, inheritedAndOwnProperties, isOptionalAt, isPayloadProperty, objectKey, refusalTarget, withDeclarationSite, } from "./zod.js";
+import { discriminatedBaseOf, discriminatedSubtypes, effectiveIndexer, emitsDefault, encodeCycleOf, encodedTypeOf, inheritedAndOwnProperties, isOptionalAt, isPayloadProperty, objectKey, refusalTarget, withDeclarationSite, } from "./zod.js";
 /**
  * TypeSpec type -> plain TypeScript type text.
  *
@@ -75,8 +75,12 @@ function refuse(program, type, why, remedy = "") {
 function scalarToTs(program, scalar) {
     // A scalar declaration can carry the encoding itself - see `scalarToZod`.
     const encoded = encodedTypeOf(program, scalar);
-    if (encoded !== undefined && encoded !== scalar)
-        return scalarToTs(program, encoded);
+    if (encoded !== undefined && encoded !== scalar) {
+        // Reported once, by the schema walk - see `encodeCycleOf`.
+        return encodeCycleOf(program, scalar) === undefined
+            ? scalarToTs(program, encoded)
+            : UNREPRESENTABLE;
+    }
     let current = scalar;
     // Walk `extends` so `scalar TrimmedString extends string` resolves to the primitive underneath.
     while (current !== undefined) {
@@ -153,11 +157,26 @@ function modelToTs(program, model) {
      * the emitter disagreeing with itself - one TypeSpec, walked twice - and this is the second defect
      * of that class it has found. The first was a vocabulary inlined by one walk and referenced by the
      * other.
+     *
+     * **An open base adds itself as the last arm**, as `modelToZod` does: a value whose discriminator
+     * names no subtype is the base's own object. The base arm's discriminator keeps its declared type
+     * here; TypeScript cannot say "a string other than these", and the validator's refinement does not
+     * change what it accepts as input, so `z.input` and this type stay identical.
      */
-    const subtypes = discriminatedSubtypes(program, model);
-    if (subtypes.length > 0) {
-        return subtypes.map((derived) => typeToTs(program, derived)).join(" | ");
+    const base = discriminatedBaseOf(program, model);
+    if (base !== undefined) {
+        const arms = discriminatedSubtypes(program, model).map((derived) => typeToTs(program, derived));
+        if (base.open)
+            arms.push(modelObjectToTs(program, model, base));
+        return arms.join(" | ");
     }
+    return modelObjectToTs(program, model);
+}
+/**
+ * A model as the object of its own properties, inherited ones included - for a discriminated base,
+ * its base arm, with the `string` discriminator openapi3 adds where the base declares none.
+ */
+function modelObjectToTs(program, model, base) {
     const indexer = effectiveIndexer(model);
     const indexerKey = indexer?.key.name;
     // Inherited properties included - see `inheritedAndOwnProperties`. Both artefacts describe the
@@ -214,6 +233,10 @@ function modelToTs(program, model) {
         .filter((property) => isPayloadProperty(program, property))
         .filter((property) => !isNeverType(property.type))
         .map((property) => `\t${withDeclarationSite(property, () => propertyToTs(program, property))}`);
+    if (base !== undefined &&
+        !declared.some((property) => resolveEncodedName(program, property, "application/json") === base.propertyName)) {
+        entries.push(`\t${objectKey(base.propertyName)}: string;`);
+    }
     /**
      * **The indexer is deliberately NOT intersected in.**
      *

package/dist/src/zod.d.ts

@@ -109,6 +109,16 @@ export declare function described(expression: string, doc: string | undefined):
  * 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**.
@@ -142,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,6 @@
-import { getDiscriminatedUnion, getDiscriminator, getDoc, getEncode, resolveEncodedName, isNeverType, isTemplateDeclaration, } from "@typespec/compiler";
+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 } from "./constraints.js";
+import { applyConstraints, firstReportOf } from "./constraints.js";
 import { literal } from "./literal.js";
 import { reportDiagnostic } from "./lib.js";
 /**
@@ -453,10 +453,48 @@ export function scalarDocOf(program, scalar) {
     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) {
+        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;
@@ -726,31 +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) {
-        // `discriminatedSubtypes` is empty unless the model has a discriminator.
-        const discriminator = getDiscriminator(program, model)?.propertyName ?? "";
-        const options = subtypes.map((derived) => typeToZod(program, derived));
-        return `z.discriminatedUnion(${literal(discriminator)}, [${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);
@@ -865,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
@@ -950,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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-http-zod",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "TypeSpec emitter and library: turn an HTTP service definition into Zod validators and framework-free contract types that agree, keyword for keyword, with the OpenAPI document @typespec/openapi3 publishes from the same source.",
   "keywords": [
     "codegen",