typespec-http-zod 0.23.0 → 0.25.0

package/dist/src/api.js

@@ -1,4 +1,4 @@
-import { emitFile, getDoc, getEncode, getSummary, isErrorModel, isNeverType, isVoidType, NoTarget, resolvePath, } from "@typespec/compiler";
+import { emitFile, getDoc, getDocData, getEncode, getLocationContext, getSummary, isErrorModel, isNeverType, isVoidType, navigateProgram, NoTarget, resolvePath, } from "@typespec/compiler";
 import { getAuthenticationForOperation, isStatusCode, resolveRequestVisibility, Visibility, } from "@typespec/http";
 import { getOperationId, resolveOperationId } from "@typespec/openapi";
 import { reportDiagnostic } from "./lib.js";
@@ -48,7 +48,7 @@ export { EmitterOptionsSchema } from "./lib.js";
  * emitted module stopped being loadable. This is not a style choice a second emitter may make
  * independently.
  */
-export { objectKey } from "./zod.js";
+export { jsDocComment, objectKey } from "./zod.js";
 /** Named once. The emitted banner and the internal-invariant messages both quote it. */
 const PACKAGE_NAME = "typespec-http-zod";
 /**
@@ -392,15 +392,48 @@ function bodySchemaOf(response, registry) {
     return undefined;
 }
 /**
- * Whether the operation declares `@useAuth(NoAuth)` - no caller is established for it.
+ * Everything the document says about authenticating an operation, read ONCE.
  *
- * **`@useAuth(NoAuth)` reaches OpenAPI as `security: []`, which is why this is derivable at all.**
- * Whether an operation needs a caller is a contract fact the document publishes. What KIND of caller
- * - account-scoped, resource-scoped - is not: no OpenAPI keyword expresses it, and a server emitter
- * that guesses is enforcing something no document states.
+ * **`scopes` and `noAuth` were two lossy projections of this, each with its own read of the same
+ * fact.** A flat scope union cannot say which scheme demanded what, so an emitter that wanted the
+ * gate the document actually publishes had to call `getAuthenticationForOperation` a third time and
+ * rebuild the requirements itself -- which is what both server emitters were doing, in two
+ * hand-written copies of one rule.
+ *
+ * `scopes` is unchanged in meaning and is now derived from `security` rather than separately read:
+ * the union of every scope any requirement demands, which is what it always was.
  */
-function noAuthFor(program, operation) {
-    return (getAuthenticationForOperation(program, operation.operation)?.options.some((option) => option.schemes.some((scheme) => scheme.type === "noAuth")) === true);
+function authenticationFor(program, operation) {
+    const options = getAuthenticationForOperation(program, operation.operation)?.options ?? [];
+    const security = [];
+    let noAuth = false;
+    for (const option of options) {
+        const requirement = {};
+        let anonymous = false;
+        for (const scheme of option.schemes) {
+            /**
+             * **`NoAuth` inside an option means that option needs nothing**, which is how a spec says
+             * authentication is optional here. It is not a scheme to demand, and publishing it as one
+             * would make an emitter refuse the anonymous callers the document permits.
+             */
+            if (scheme.type === "noAuth") {
+                anonymous = true;
+                noAuth = true;
+                continue;
+            }
+            /** Scopes belong to the flows of an OAuth2 scheme; every other kind has none. */
+            requirement[scheme.id] =
+                scheme.type === "oauth2"
+                    ? [...new Set(scheme.flows.flatMap((flow) => flow.scopes.map((scope) => scope.value)))]
+                    : [];
+        }
+        if (anonymous && Object.keys(requirement).length === 0)
+            continue;
+        if (Object.keys(requirement).length > 0)
+            security.push(requirement);
+    }
+    const scopes = [...new Set(security.flatMap((requirement) => Object.values(requirement).flat()))];
+    return { security, scopes, noAuth };
 }
 /**
  * The body every `@error` response in the service declares, when they all declare the same one.
@@ -680,7 +713,9 @@ function multipartSchemaOf(body, registry) {
                     : registry.expressionFor(type);
         // `multi` is `HttpPart<T>[]` - the same part repeated, which arrives as an array.
         const value = part.multi === true ? `z.array(${inner})` : inner;
-        return `\t${objectKey(part.name ?? "")}: ${part.optional === true ? `${value}.optional()` : value},`;
+        // `.exactOptional()` for the same reason as a model property: `parseBody` yields present keys
+        // only, so an absent part is an absent key rather than an explicit `undefined`.
+        return `\t${objectKey(part.name ?? "")}: ${part.optional === true ? `${value}.exactOptional()` : value},`;
     });
     const shape = entries.length === 0 ? "z.object({})" : `z.object({\n${entries.join("\n")}\n})`;
     /**
@@ -1098,9 +1133,36 @@ export function collectRoutes(program, registry, service) {
              * express "absent". See {@link EmittedRoute.optionalBody}.
              */
             const optionalBody = bodyParameter?.property?.optional === true;
-            const bodyProperty = requestType?.kind === "Model" && (requestType.indexer !== undefined || optionalBody)
+            /**
+             * **An optional MULTIPART body reaches the same rule by a second route, because
+             * `requestType` cannot see it.** `requestBodyOf` resolves a type only for
+             * `bodyKind === "single"`, so `requestType` is `undefined` for every multipart operation
+             * and the `optionalBody` disjunct above was unreachable however the document declared it.
+             *
+             * The emitted server for such an operation did not compile. Measured, and the mechanism is
+             * worth stating because it is not a union: spreading a value typed `Parts | undefined`
+             * makes every part OPTIONAL, so `{ file?: ...; pages?: ... }` was passed where
+             * `{ file: ...; pages: ... }` was required. `TS2345`, inside `app.gen.ts` itself.
+             *
+             * That is the failure {@link EmittedRoute.optionalBody} predicts in prose - a merge has no
+             * way to say "these properties are here only sometimes" without making every one of them
+             * optional, which is a weaker and different claim about the body that IS sent. So this is
+             * the stated rule reaching the one body kind it had never been applied to, not a new rule.
+             *
+             * **The REQUIRED arm is deliberately excluded.** The indexed reason does not apply to a
+             * parts model, so a required multipart body merges as safely as a required single one, and
+             * `typespec-hono/test/filepart/` compiles a handler that reads `input.file` directly.
+             * Widening this to "multipart is always named" would rewrite that directory for no defect.
+             *
+             * This is the third hole the `"single"` gate has produced, after `multipartSchemaOf` and
+             * `multipartTsOf`, both recorded above.
+             */
+            const optionalMultipartBody = bodyParameter?.bodyKind === "multipart" && optionalBody;
+            const bodyProperty = (requestType?.kind === "Model" && (requestType.indexer !== undefined || optionalBody)) ||
+                optionalMultipartBody
                 ? (bodyParameter?.property?.name ?? "body")
                 : undefined;
+            const authentication = authenticationFor(program, operation);
             routes.push({
                 operationId: operationIdOf(program, operation.operation),
                 verb: operation.verb.toUpperCase(),
@@ -1186,12 +1248,9 @@ export function collectRoutes(program, registry, service) {
                 errorArms: withVisibility(program, Visibility.Read, () => errorArmsOf(program, operation, registry)),
                 responseHeaders: responseHeadersOf(program, operation),
                 responseMediaTypes: responseMediaTypesOf(operation),
-                scopes: [
-                    ...new Set((getAuthenticationForOperation(program, operation.operation)?.options ?? []).flatMap((option) => option.schemes.flatMap((scheme) => scheme.type === "oauth2"
-                        ? scheme.flows.flatMap((flow) => flow.scopes.map((scope) => scope.value))
-                        : []))),
-                ],
-                noAuth: noAuthFor(program, operation),
+                scopes: authentication.scopes,
+                security: authentication.security,
+                noAuth: authentication.noAuth,
                 statusBy: discriminator,
                 statusSelector,
                 /**
@@ -1266,7 +1325,26 @@ function renderExternalImports(externals, ...bodies) {
  * validate a request or a response against, and every oracle that graded those validators had to read
  * a server to find them. See {@link nameRouteSchemas}.
  */
-function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
+/**
+ * **`z.compile(...)` around a validator, when `compile-schemas` asks for it.**
+ *
+ * Zod walks the schema once and emits a flat, loop-free function through `new Function`, falling back
+ * to the ordinary parser for anything it cannot handle. Measured on zod 4.5.2 before this was written:
+ * `z.toJSONSchema` output is byte-identical, `_zod.def` is unchanged and still readable, and verdicts
+ * AND parsed output match for every construct this emitter writes - including `z.preprocess`,
+ * `.exactOptional()` and a `z.lazy()` cycle. So the two oracles that read a schema rather than run it
+ * are unaffected, and the wrapper is transparent.
+ *
+ * **A cyclic declaration is wrapped too, and that was worth checking rather than assuming.** The
+ * emitted form names the const being defined from inside its own `z.lazy()` body, and this repository
+ * has already shipped a break of exactly that shape - `.strict()` reads `shape` eagerly and throws
+ * `Cannot access 'X' before initialization` during module initialisation. Measured on the emitted
+ * shape: `z.compile()` does not force the lazy body, and the declaration parses.
+ */
+function compiled(expression, on) {
+    return on ? `z.compile(${expression})` : expression;
+}
+function renderSchemas(registry, externals, routeDeclarations, runtimeModule, compileSchemas) {
     const declarations = registry.declarations().map((d) => {
         /**
          * **A declaration on a CYCLE cannot take its type from `z.infer`, because that is the loop.**
@@ -1277,7 +1355,7 @@ function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
          * with no cycle emits byte-identical output to before.
          */
         if (d.structural === undefined) {
-            return `\nexport const ${d.identifier} = ${d.source};\nexport type ${d.typeName} = Exact<z.infer<typeof ${d.identifier}>>;\n`;
+            return `\nexport const ${d.identifier} = ${compiled(d.source, compileSchemas)};\nexport type ${d.typeName} = z.infer<typeof ${d.identifier}>;\n`;
         }
         const declared = d.structural.startsWith("{")
             ? `export interface ${d.typeName} ${d.structural}`
@@ -1308,7 +1386,22 @@ function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
          * than from this type, so no handler signature is affected.
          */
         const annotation = d.annotated === true ? `: z.ZodType<${d.typeName}, ${d.typeName}>` : "";
-        return `\n${declared}\nexport const ${d.identifier}${annotation} = ${d.source};\n`;
+        /**
+         * **A deferred declaration is NEVER compiled, and this was measured rather than reasoned.**
+         *
+         * `z.lazy()` is on Zod's own list of constructs the compiler cannot handle, and here the body
+         * forward-references a `const` declared further down the module. Wrapping it emitted output that
+         * loaded fine and then threw `Cannot read properties of undefined (reading '_zod')` on the first
+         * parse - the walk captures the reference while it is still in the temporal dead zone, so the
+         * failure surfaces at request time rather than at import.
+         *
+         * **Keyed on `annotated`, the fact the registry already holds** - it is set exactly when the
+         * declaration is deferred, which is exactly when `z.lazy()` is written - rather than on the
+         * shape of the emitted text. A model on a cycle whose back edge sits on a GETTER is a different
+         * case and is compiled like any other: measured, it parses, because a getter is not resolved
+         * until something reads it.
+         */
+        return `\n${declared}\nexport const ${d.identifier}${annotation} = ${compiled(d.source, compileSchemas && d.annotated !== true)};\n`;
     });
     /**
      * **Written only when something in the file names it**, like the `ResponseArm` import below and for
@@ -1327,39 +1420,24 @@ function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
      * rendered content for the same reason.
      */
     /**
-     * **`Exact` narrows an inferred optional to what the wire can carry.**
-     *
-     * `z.infer` of `.optional()` gives `p?: T | undefined`, which under `exactOptionalPropertyTypes`
-     * admits an explicitly-undefined property. **JSON has no `undefined`**, and the document says the
-     * same thing by leaving the property out of `required`, so the inferred type is wider than the
-     * wire and a consumer reading a payload had to strip it at the boundary.
+     * **`Exact<>` lived here until `0.24.0`, and `z.exactOptional()` replaced it.**
      *
-     * **It does NOT match the contract type, and this docblock used to claim it did.** The
-     * contract types in `requests.gen.ts` keep `?: T | undefined` on purpose: they are the floor a
-     * PRODUCER supplies, and `{ p: undefined }` serialises identically to omitting `p`, so refusing
-     * it would cost every producer a conditional spread and buy the wire nothing. Measured when this
-     * was "fixed" to agree: `(ctx, input) => ok(input)` - return what you were given - stopped
-     * compiling.
+     * It was a mapped type over `z.infer` that stripped `| undefined` off every optional property,
+     * because `.optional()` infers `p?: T | undefined` and **JSON has no `undefined`** - the document
+     * says "absent or a value" by leaving the property out of `required`, so the inferred type was
+     * wider than both the document and the wire.
      *
-     * So the two surfaces differ on this axis deliberately, exactly as they differ on openness: this
-     * one is the narrow view of what ARRIVES, the contract type is the permissive floor for what you
-     * may SEND. A reader comparing them will find them unequal and should - the emitted assertion
-     * pairs the contract against raw `z.input`, not against this. They differ on a second axis for
-     * the same reason: a defaulted property is present here, because a default has fired by the time
-     * a value arrives, and optional in the contract type, because a caller may omit it.
+     * The reasoning was right and it was applied to only one of the two artefacts. The VALIDATOR went
+     * on accepting `{ p: undefined }`, so one program published a type refusing a value beside a
+     * validator admitting it, compared by nothing. Emitting `.exactOptional()` makes `z.infer` produce
+     * `p?: T` directly - at every depth, which a shallow mapped type never reached - so the narrowing
+     * happens once, in the schema, and this helper has nothing left to do.
      *
-     * Derived from the same schema rather than hand-written beside it, so there is still one source of
-     * truth: a mapped type cannot drift from the thing it maps.
-     *
-     * Emitted only where a declaration names it, like the imports beside it.
+     * The contract types in `requests.gen.ts` still keep `?: T | undefined` on purpose: they are the
+     * floor a PRODUCER supplies, and `{ p: undefined }` serialises identically to omitting `p`, so
+     * refusing it there would cost every producer a conditional spread and buy the wire nothing.
+     * Narrowing THAT surface was tried in `0.19.0` and reverted - it broke `(ctx, input) => ok(input)`.
      */
-    const EXACT_HELPER = `
-/** An inferred type narrowed to what JSON can carry: an optional property is absent or a value. */
-type Exact<T> = { [K in keyof T as undefined extends T[K] ? never : K]: T[K] } & {
-	[K in keyof T as undefined extends T[K] ? K : never]?: Exclude<T[K], undefined>;
-};
-`;
-    const usesExact = declarations.some((d) => d.includes("Exact<"));
     const usesZod = new Set([...declarations, ...routeDeclarations].join("").match(/[A-Za-z_$][\w$]*/g) ?? []).has("z");
     const parts = [generatedBanner()];
     if (usesZod)
@@ -1376,8 +1454,6 @@ type Exact<T> = { [K in keyof T as undefined extends T[K] ? never : K]: T[K] } &
         parts.push(`import type { ResponseArm } from ${JSON.stringify(runtimeModule)};\n`);
     }
     parts.push(renderExternalImports(externals, [...declarations, ...routeDeclarations].join("")));
-    if (usesExact)
-        parts.push(EXACT_HELPER);
     parts.push(declarations.join(""));
     if (routeDeclarations.length > 0)
         parts.push(`\n${routeDeclarations.join("\n")}\n`);
@@ -1394,7 +1470,7 @@ type Exact<T> = { [K in keyof T as undefined extends T[K] ? never : K]: T[K] } &
 const isIdentifier = (expression) => /^[A-Za-z_$][\w$]*$/.test(expression);
 const schemaConst = (operationId, suffix) => `${operationId}${suffix}`;
 /** `[the name to refer to it by, the `const` line to emit]` - the line is absent when none is needed. */
-function namedSchema(operationId, suffix, expression) {
+function namedSchema(operationId, suffix, expression, compileSchemas) {
     if (expression === undefined)
         return { name: undefined, declaration: undefined };
     if (isIdentifier(expression))
@@ -1411,7 +1487,7 @@ function namedSchema(operationId, suffix, expression) {
      * Exporting also gives an application the request shape by name, which is what the per-operation
      * type aliases will be built from.
      */
-    return { name, declaration: `export const ${name} = ${expression};` };
+    return { name, declaration: `export const ${name} = ${compiled(expression, compileSchemas)};` };
 }
 /**
  * Which `verb path` slots carry more than one operation.
@@ -1453,13 +1529,13 @@ function sharedSlots(routes) {
  * Declaring them here dissolves all three: the library mints the names AND emits them, and a server
  * emitter imports what it is told rather than agreeing about it.
  */
-function nameRouteSchemas(routes) {
+function nameRouteSchemas(routes, compileSchemas) {
     const shared = sharedSlots(routes);
     const declarations = [];
     const names = new Map();
     for (const route of routes) {
         const declare = (suffix, expression) => {
-            const resolved = namedSchema(route.operationId, suffix, expression);
+            const resolved = namedSchema(route.operationId, suffix, expression, compileSchemas);
             if (resolved.declaration !== undefined)
                 declarations.push(resolved.declaration);
             return resolved.name;
@@ -1611,61 +1687,83 @@ function collectRequestTypes(program, registry, service) {
         for (const operation of service.operations) {
             if (successStatusOf(operation) === undefined)
                 continue;
-            const body = requestBodyOf(operation);
-            /** The parts of a multipart body, which `requestBodyOf` deliberately does not return. */
-            const multipartBody = operation.parameters.body;
-            const multipart = multipartBody?.bodyKind === "multipart" ? { parts: multipartBody.parts } : undefined;
             /**
-             * Headers are part of the input too.
+             * **Walked at the operation's REQUEST visibility, which is the whole point of this file.**
+             *
+             * `resolveRequestVisibility` is `@typespec/http`'s own answer - POST is Create, PATCH is
+             * Update, PUT is CreateOrUpdate - and it is what the Zod walk already uses at the route
+             * level. Without it this walk ran at the default `Read`, so a POST body's contract type
+             * carried the canonical property set while the validator beside it accepted the create
+             * projection. A caller satisfying the published type sent read-only fields and a strict
+             * validator answered 400.
              *
-             * The webhook's three Standard-Webhooks headers are inside the MAC - they are not metadata
-             * beside the payload, they are arguments to the verification. Leaving them out of the wire
-             * type would describe an input the application cannot act on.
+             * It is also what keeps `metadataInfo` scoped: the predicates `propertyToTs` consults live
+             * behind `withVisibility`, and calling them outside one leaves a module-level singleton
+             * built for the wrong program.
              */
-            const extraProperties = operation.parameters.parameters
-                .filter((parameter) => parameter.type === "path" || parameter.type === "query" || parameter.type === "header")
+            withVisibility(program, resolveRequestVisibility(program, operation.operation, operation.verb), () => {
+                const body = requestBodyOf(operation);
+                /** The parts of a multipart body, which `requestBodyOf` deliberately does not return. */
+                const multipartBody = operation.parameters.body;
+                const multipart = multipartBody?.bodyKind === "multipart" ? { parts: multipartBody.parts } : undefined;
                 /**
-                 * Named as the WIRE names it, which is what the emitted validator keys on.
-                 * `@header("x-thing") thing: string` is `"x-thing"` in `schemas.gen.ts`, so it has to be
-                 * `"x-thing"` here too: a consumer checking its handlers against these types otherwise
-                 * fails to typecheck against a server that is correct.
+                 * Headers are part of the input too.
+                 *
+                 * The webhook's three Standard-Webhooks headers are inside the MAC - they are not metadata
+                 * beside the payload, they are arguments to the verification. Leaving them out of the wire
+                 * type would describe an input the application cannot act on.
                  */
-                .map((parameter) => registry.expressionForProperty(parameter.param, parameter.name));
-            if (body === undefined && extraProperties.length === 0)
-                continue;
-            /**
-             * A `bytes` body reaches the use-case as a NAMED property holding the unparsed body, not as
-             * a bare value, so the wire type is `{ rawBody: ... }`, matching what a server actually
-             * builds. Referencing the scalar directly would type the whole input as that value and
-             * quietly drop the headers beside it.
-             */
-            const rawBody = body?.kind === "Scalar" && body.name === "bytes"
-                ? (operation.parameters.body?.property?.name ?? "body")
-                : undefined;
-            /**
-             * **Raw binary is `ArrayBuffer`; base64 inside a JSON payload is `string`.** The same
-             * `isRawBinaryMediaType` rule the response side and the multipart parts already follow,
-             * applied here for the first time.
-             *
-             * This type said `string` for every `bytes` body whatever it was served as. A server reading
-             * an `application/octet-stream` body hands the handler bytes, so a consumer checking its
-             * handlers against these types could not typecheck against a correct server. It is the
-             * request half of the corruption already fixed on the reader: decoding raw bytes as text
-             * replaces every byte outside ASCII, and typing them as text is what invites it.
-             */
-            const rawBodyType = isRawBinaryMediaType([...(operation.parameters.body?.contentTypes ?? [])])
-                ? "ArrayBuffer"
-                : "string";
-            entries.push({
-                operationId: operationIdOf(program, operation.operation),
-                bodyRef: rawBody !== undefined
-                    ? `{\n\t${rawBody}: ${rawBodyType};\n}`
-                    : multipart !== undefined
-                        ? multipartTsOf(multipart, registry)
-                        : body === undefined
-                            ? undefined
-                            : registry.expressionFor(body),
-                extraProperties,
+                const extraProperties = operation.parameters.parameters
+                    .filter((parameter) => parameter.type === "path" ||
+                    parameter.type === "query" ||
+                    parameter.type === "header")
+                    /**
+                     * Named as the WIRE names it, which is what the emitted validator keys on.
+                     * `@header("x-thing") thing: string` is `"x-thing"` in `schemas.gen.ts`, so it has to be
+                     * `"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));
+                // `return` rather than `continue`: this body is a callback now, and returning from it
+                // skips the operation exactly as the `continue` did.
+                if (body === undefined && extraProperties.length === 0)
+                    return;
+                /**
+                 * A `bytes` body reaches the use-case as a NAMED property holding the unparsed body, not as
+                 * a bare value, so the wire type is `{ rawBody: ... }`, matching what a server actually
+                 * builds. Referencing the scalar directly would type the whole input as that value and
+                 * quietly drop the headers beside it.
+                 */
+                const rawBody = body?.kind === "Scalar" && body.name === "bytes"
+                    ? (operation.parameters.body?.property?.name ?? "body")
+                    : undefined;
+                /**
+                 * **Raw binary is `ArrayBuffer`; base64 inside a JSON payload is `string`.** The same
+                 * `isRawBinaryMediaType` rule the response side and the multipart parts already follow,
+                 * applied here for the first time.
+                 *
+                 * This type said `string` for every `bytes` body whatever it was served as. A server reading
+                 * an `application/octet-stream` body hands the handler bytes, so a consumer checking its
+                 * handlers against these types could not typecheck against a correct server. It is the
+                 * request half of the corruption already fixed on the reader: decoding raw bytes as text
+                 * replaces every byte outside ASCII, and typing them as text is what invites it.
+                 */
+                const rawBodyType = isRawBinaryMediaType([
+                    ...(operation.parameters.body?.contentTypes ?? []),
+                ])
+                    ? "ArrayBuffer"
+                    : "string";
+                entries.push({
+                    operationId: operationIdOf(program, operation.operation),
+                    bodyRef: rawBody !== undefined
+                        ? `{\n\t${rawBody}: ${rawBodyType};\n}`
+                        : multipart !== undefined
+                            ? multipartTsOf(multipart, registry)
+                            : body === undefined
+                                ? undefined
+                                : registry.expressionFor(body),
+                    extraProperties,
+                });
             });
         }
     }
@@ -1682,7 +1780,15 @@ function collectRequestTypes(program, registry, service) {
  */
 function collectResponseTypes(program, registry, service) {
     const entries = [];
-    {
+    /**
+     * **Pinned to `Read` explicitly, rather than inheriting whatever the caller last set.**
+     *
+     * A response is the canonical projection whatever verb produced it, and the same rule is stated
+     * for the route walk: resolving responses under the ambient REQUEST visibility declared six
+     * components under the wrong suffix. Saying it here rather than relying on the default is what
+     * makes that impossible from either direction.
+     */
+    withVisibility(program, Visibility.Read, () => {
         for (const operation of service.operations) {
             const status = successStatusOf(operation);
             if (status === undefined)
@@ -1695,7 +1801,7 @@ function collectResponseTypes(program, registry, service) {
                 ref: registry.expressionFor(body),
             });
         }
-    }
+    });
     return entries;
 }
 /**
@@ -1709,10 +1815,23 @@ function collectResponseTypes(program, registry, service) {
  */
 function renderRequestTypes(entries, responses, registry) {
     const declarations = registry.declarations().map((declaration) => {
-        // A vocabulary alias stays module-local: the vocabularies artefact already exports these names
-        // as runtime tuples, and exporting both collides on every one.
+        /**
+         * **A vocabulary alias is exported like any other declaration.**
+         *
+         * It used to stay module-local, on the stated ground that "the vocabularies artefact already
+         * exports these names as runtime tuples, and exporting both collides on every one". That was
+         * true of a shape this emitter no longer produces: `vocabularies.gen.ts` has exactly one
+         * top-level export, `SPEC_VOCABULARIES`, and the enum names are KEYS inside it - see the
+         * docblock on `renderVocabularies`, which records why the keyed form replaced individually
+         * named tuples. There is nothing left to collide with.
+         *
+         * The stale rationale was load-bearing: `wire-contract.gen.ts` names `Contracts.<EnumName>`
+         * for an enum used as a request body, and a barrel cannot re-export a declaration that is not
+         * exported. So that file did not compile for any such spec. `TS2694`, found the first time
+         * anything compiled the conformance corpus rather than reading it.
+         */
         if (declaration.isVocabulary)
-            return `\ntype ${declaration.name} = ${declaration.source};\n`;
+            return `\nexport type ${declaration.name} = ${declaration.source};\n`;
         return declaration.isObject
             ? `\nexport interface ${declaration.name} ${declaration.source}\n`
             : `\nexport type ${declaration.name} = ${declaration.source};\n`;
@@ -1913,6 +2032,26 @@ type Identical<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends
  * dropped from a shape that has other keys, and kept - with its value type still mapped - from one
  * that does not.
  */
+/**
+ * \u26a0\ufe0f **An optional property is \`?: T\` here and \`?: T | undefined\` in the contract type, and that is
+ * deliberate on both sides.**
+ *
+ * The validator emits \`.exactOptional()\`, so what ARRIVES is absent or a value - JSON cannot carry an
+ * \`undefined\` and the document says exactly that by leaving the property out of \`required\`. The
+ * contract type is the floor a PRODUCER supplies, and \`{ p: undefined }\` serialises identically to
+ * omitting \`p\`, so refusing it would cost every producer a conditional spread and buy the wire
+ * nothing. Narrowing THAT surface was tried in \`0.19.0\` and reverted: it broke
+ * \`(ctx, input) => ok(input)\`.
+ *
+ * So the two disagree on exactly one axis, on purpose, and this widens the inferred side to the
+ * producer floor before comparing - the same job \`Declared\` does for openness, in the same pass
+ * rather than a second deep one. Every other kind of drift still fails: a property that changes type,
+ * appears, disappears or changes optionality is untouched by this.
+ */
+type Supplied<T, K extends keyof T> = {} extends Pick<T, K>
+	? Declared<T[K]> | undefined
+	: Declared<T[K]>;
+
 type DeclaredKeyOf<T> = keyof {
 	[K in keyof T as string extends K
 		? never
@@ -1931,7 +2070,20 @@ type Declared<T> = T extends (...args: never[]) => unknown
 			: readonly Declared<Element>[]
 		: T extends object
 			? [DeclaredKeyOf<T>] extends [never]
-				? { [K in keyof T]: Declared<T[K]> }
+				? [T[keyof T]] extends [never]
+					? // **An indexer whose VALUE type is \`never\` admits no property, so it is an EMPTY
+						// OBJECT rather than a dictionary.** Zod spells an empty object that way:
+						// \`z.strictObject({})\` infers \`Record<string, never>\` under Zod 4, while this
+						// walk emits \`{}\` for the same model. The two describe one shape and compared
+						// unequal, so \`wire-contract.gen.ts\` did not compile for any spec declaring an
+						// empty model. Normalising both to \`{}\` is what makes them agree, and it cannot
+						// equate a real dictionary with an empty object: a dictionary whose values are
+						// \`never\` accepts nothing either.
+						{}
+					: // A shape with no declared keys is a dictionary: it has no optional property to
+						// widen, and an index signature satisfies \`{} extends Pick<T, K>\` for every
+						// value type.
+						{ [K in keyof T]: Declared<T[K]> }
 				: {
 						[K in keyof T as string extends K
 							? never
@@ -1939,7 +2091,7 @@ type Declared<T> = T extends (...args: never[]) => unknown
 								? never
 								: symbol extends K
 									? never
-									: K]: Declared<T[K]>;
+									: K]: Supplied<T, K>;
 					}
 			: T;
 
@@ -1990,6 +2142,49 @@ export const DEFAULT_RUNTIME_MODULE = "typespec-http-zod/runtime";
  * copies that will not, and the symptom would be a subtly different set of declarations in a file
  * whose name is the contract.
  */
+/**
+ * The doc tags TypeSpec understands. Anything else parses as an unknown tag, and the description
+ * ends where it began. Written out rather than imported: `SyntaxKind` lives behind
+ * `@typespec/compiler/ast`, whose exports map declares no `types` condition, and comparing the tag
+ * NAME needs no AST import at all.
+ */
+const KNOWN_DOC_TAGS = new Set(["param", "template", "prop", "returns", "return", "errors"]);
+/** See the `truncated-doc-comment` docblock in `lib.ts` for why this reads the node, not the string. */
+function reportTruncatedDocComments(program) {
+    const check = (type) => {
+        if (getLocationContext(program, type).type !== "project")
+            return;
+        // An `@doc(...)` decorator wins, and `@` inside a string literal truncates nothing.
+        if (getDocData(program, type)?.source !== "comment")
+            return;
+        const docs = type.node?.docs;
+        for (const doc of docs ?? []) {
+            for (const tag of doc.tags) {
+                if (KNOWN_DOC_TAGS.has(tag.tagName.sv))
+                    continue;
+                reportDiagnostic(program, {
+                    code: "truncated-doc-comment",
+                    target: type,
+                    format: {
+                        name: typeof type.name === "string" && type.name !== "" ? type.name : "(anonymous)",
+                        tag: tag.tagName.sv,
+                    },
+                });
+            }
+        }
+    };
+    navigateProgram(program, {
+        model: check,
+        modelProperty: check,
+        operation: check,
+        enum: check,
+        enumMember: check,
+        union: check,
+        unionVariant: check,
+        interface: check,
+        scalar: check,
+    });
+}
 export async function emitHttpZod(context, wrapper = {}) {
     const options = context.options;
     const defaultRuntimeModule = wrapper.defaultRuntimeModule ?? DEFAULT_RUNTIME_MODULE;
@@ -2064,6 +2259,11 @@ export async function emitHttpZod(context, wrapper = {}) {
             format: { sealed: sealed.join(", "), open: open.join(", ") },
         });
     }
+    /**
+     * Once per program, before the per-service loop: a doc comment belongs to a type, not to a
+     * service, and a type reachable from two services would otherwise be named twice.
+     */
+    reportTruncatedDocComments(context.program);
     for (const snapshot of snapshots) {
         beginOperationIds();
         const service = snapshot.service;
@@ -2077,6 +2277,7 @@ export async function emitHttpZod(context, wrapper = {}) {
             contractsOutputDir: perService?.["contracts-output-dir"] ?? options["contracts-output-dir"],
             contractsPackage: perService?.["contracts-package"] ?? options["contracts-package"],
             sealObjectSchemas: perService?.["seal-object-schemas"] ?? options["seal-object-schemas"] ?? false,
+            compileSchemas: perService?.["compile-schemas"] ?? options["compile-schemas"] ?? false,
             keyVocabularies: perService?.["key-vocabularies"] ?? options["key-vocabularies"] ?? [],
             runtimeModule: perService?.["runtime-module"] ?? options["runtime-module"] ?? defaultRuntimeModule,
             regenerateHint: perService?.["regenerate-hint"] ?? options["regenerate-hint"],
@@ -2133,10 +2334,10 @@ export async function emitHttpZod(context, wrapper = {}) {
          * anything is written - and it has to happen HERE rather than in a server emitter, or the
          * validators it produces never reach this package's own output.
          */
-        const { names, declarations } = nameRouteSchemas(routes);
+        const { names, declarations } = nameRouteSchemas(routes, resolved.compileSchemas);
         await emitFile(context.program, {
             path: resolvePath(outputDir, "schemas.gen.ts"),
-            content: renderSchemas(registry, externals, declarations, resolved.runtimeModule),
+            content: renderSchemas(registry, externals, declarations, resolved.runtimeModule, resolved.compileSchemas),
         });
         if (resolved.contractsOutputDir !== undefined) {
             const types = new TypeRegistry(context.program);