typespec-http-zod 0.1.0 → 0.3.0

package/dist/src/constraints.d.ts

@@ -1,12 +1,12 @@
 import { type Program, type Type } from "@typespec/compiler";
 /**
- * Constraint decorators → the Zod modifiers that enforce them.
+ * Constraint decorators -> the Zod modifiers that enforce them.
  *
- * These are **first-party** TypeSpec decorators (`@minLength`, `@pattern`, …), which matters twice
+ * These are **first-party** TypeSpec decorators (`@minLength`, `@pattern`, ...), which matters twice
  * over: the spec author writes standard TypeSpec rather than a dialect, and `@typespec/openapi3`
  * documents them without any help from us.
  *
- * ⚠️ **`@refine` is the ONE that is still ours, and it is on its way out.** It is not a constraint —
+ * **`@refine` is the ONE that is still ours, and it is on its way out.** It is not a constraint -
  * it is an arbitrary predicate, which a type language has no way to say and therefore no document
  * can publish, so a validator enforcing it enforces something no caller can read. `@trimmed` was the
  * other one and is gone: `.trim()` is a transform, and transforming a value before validating it
@@ -15,9 +15,9 @@ import { type Program, type Type } from "@typespec/compiler";
  */
 export declare function applyConstraints(program: Program, expression: string, target: Type): string;
 /**
- * A `@pattern` string becomes a regex literal — **verbatim**.
+ * A `@pattern` string becomes a regex literal - **verbatim**.
  *
- * ⚠️ **This used to add anchors, and that was wrong twice over.**
+ * **This used to add anchors, and that was wrong twice over.**
  *
  * The docblock claimed "TypeSpec's `@pattern` is a full-match assertion (it follows JSON Schema)".
  * JSON Schema says the opposite, in as many words: *"Recall: regular expressions are not implicitly
@@ -26,11 +26,11 @@ export declare function applyConstraints(program: Program, expression: string, t
  *
  * Worse, the anchoring was not even an anchoring. `^` and `$` bind looser than `|`, so a top-level
  * alternation changed meaning rather than being constrained: the spec's `\S|^$` became `^\S|^$`,
- * which is `(^\S)|(^$)` — "starts with a non-space, or is empty". Measured on `"  Alex  "` the
+ * which is `(^\S)|(^$)` - "starts with a non-space, or is empty". Measured on `"  Alex  "` the
  * document said valid and we rejected; on `"Alex  "` we accepted what the pattern's own stated
  * intent forbids. 153 of the 227 emitted `.regex()` calls came from that one scalar.
  *
- * A pattern that means to match the whole string says so in the spec — `^\S(?:[\s\S]*\S)?$`, which
+ * A pattern that means to match the whole string says so in the spec - `^\S(?:[\s\S]*\S)?$`, which
  * is the standard construct for it. That way the document and the validator carry
  * the identical expression, and the conformance differential can assert it character for character
  * instead of guessing at an equivalence.

package/dist/src/constraints.js

@@ -1,12 +1,12 @@
 import { getMaxItems, getMaxLength, getMaxValue, getMinItems, getMinLength, getMinValue, getMinValueExclusive, getMaxValueExclusive, getPattern, } from "@typespec/compiler";
 /**
- * Constraint decorators → the Zod modifiers that enforce them.
+ * Constraint decorators -> the Zod modifiers that enforce them.
  *
- * These are **first-party** TypeSpec decorators (`@minLength`, `@pattern`, …), which matters twice
+ * These are **first-party** TypeSpec decorators (`@minLength`, `@pattern`, ...), which matters twice
  * over: the spec author writes standard TypeSpec rather than a dialect, and `@typespec/openapi3`
  * documents them without any help from us.
  *
- * ⚠️ **`@refine` is the ONE that is still ours, and it is on its way out.** It is not a constraint —
+ * **`@refine` is the ONE that is still ours, and it is on its way out.** It is not a constraint -
  * it is an arbitrary predicate, which a type language has no way to say and therefore no document
  * can publish, so a validator enforcing it enforces something no caller can read. `@trimmed` was the
  * other one and is gone: `.trim()` is a transform, and transforming a value before validating it
@@ -30,7 +30,7 @@ export function applyConstraints(program, expression, target) {
         result += `.min(${min})`;
     if (max !== undefined)
         result += `.max(${max})`;
-    // Exclusive bounds are a distinct question from inclusive ones — `z.number().positive()` is
+    // Exclusive bounds are a distinct question from inclusive ones - `z.number().positive()` is
     // `.gt(0)`, and emitting `.min(0)` for it would accept a zero share count or a zero spot rate.
     const minExclusive = getMinValueExclusive(program, target);
     const maxExclusive = getMaxValueExclusive(program, target);
@@ -43,9 +43,9 @@ export function applyConstraints(program, expression, target) {
     return result;
 }
 /**
- * A `@pattern` string becomes a regex literal — **verbatim**.
+ * A `@pattern` string becomes a regex literal - **verbatim**.
  *
- * ⚠️ **This used to add anchors, and that was wrong twice over.**
+ * **This used to add anchors, and that was wrong twice over.**
  *
  * The docblock claimed "TypeSpec's `@pattern` is a full-match assertion (it follows JSON Schema)".
  * JSON Schema says the opposite, in as many words: *"Recall: regular expressions are not implicitly
@@ -54,11 +54,11 @@ export function applyConstraints(program, expression, target) {
  *
  * Worse, the anchoring was not even an anchoring. `^` and `$` bind looser than `|`, so a top-level
  * alternation changed meaning rather than being constrained: the spec's `\S|^$` became `^\S|^$`,
- * which is `(^\S)|(^$)` — "starts with a non-space, or is empty". Measured on `"  Alex  "` the
+ * which is `(^\S)|(^$)` - "starts with a non-space, or is empty". Measured on `"  Alex  "` the
  * document said valid and we rejected; on `"Alex  "` we accepted what the pattern's own stated
  * intent forbids. 153 of the 227 emitted `.regex()` calls came from that one scalar.
  *
- * A pattern that means to match the whole string says so in the spec — `^\S(?:[\s\S]*\S)?$`, which
+ * A pattern that means to match the whole string says so in the spec - `^\S(?:[\s\S]*\S)?$`, which
  * is the standard construct for it. That way the document and the validator carry
  * the identical expression, and the conformance differential can assert it character for character
  * instead of guessing at an equivalence.

package/dist/src/emitter.d.ts

@@ -2,7 +2,7 @@ import type { EmitContext } from "@typespec/compiler";
 /**
  * This library's own emitter entry point.
  *
- * ⚠️ **It may import `./api.js`, `./lib.js` and external packages, and nothing else — asserted, not
+ * **It may import `./api.js`, `./lib.js` and external packages, and nothing else - asserted, not
  * intended.** An emitter built on this library is written exactly like this one, so "the public API
  * is sufficient to build an emitter on" is proved by construction rather than hoped for. The moment
  * this file needs something `api.ts` does not export, the API is wrong and the fix belongs there.

package/dist/src/emitter.js

@@ -2,7 +2,7 @@ import { emitHttpZod } from "./api.js";
 /**
  * This library's own emitter entry point.
  *
- * ⚠️ **It may import `./api.js`, `./lib.js` and external packages, and nothing else — asserted, not
+ * **It may import `./api.js`, `./lib.js` and external packages, and nothing else - asserted, not
  * intended.** An emitter built on this library is written exactly like this one, so "the public API
  * is sufficient to build an emitter on" is proved by construction rather than hoped for. The moment
  * this file needs something `api.ts` does not export, the API is wrong and the fix belongs there.

package/dist/src/index.d.ts

@@ -1,8 +1,8 @@
 /**
  * The package's entry point: the public API, and the emitter written against it.
  *
- * Split in two deliberately. `api.ts` is everything a consumer may use — including another emitter,
- * which is what `typespec-hono` is — and `emitter.ts` is this package's own `$onEmit`, holding the
+ * Split in two deliberately. `api.ts` is everything a consumer may use - including another emitter,
+ * which is what `typespec-hono` is - and `emitter.ts` is this package's own `$onEmit`, holding the
  * same position any consumer's would. Keeping them apart is what lets a test assert that the second
  * reaches only into the first.
  */

package/dist/src/index.js

@@ -1,8 +1,8 @@
 /**
  * The package's entry point: the public API, and the emitter written against it.
  *
- * Split in two deliberately. `api.ts` is everything a consumer may use — including another emitter,
- * which is what `typespec-hono` is — and `emitter.ts` is this package's own `$onEmit`, holding the
+ * Split in two deliberately. `api.ts` is everything a consumer may use - including another emitter,
+ * which is what `typespec-hono` is - and `emitter.ts` is this package's own `$onEmit`, holding the
  * same position any consumer's would. Keeping them apart is what lets a test assert that the second
  * reaches only into the first.
  */

package/dist/src/lib.d.ts

@@ -13,16 +13,16 @@ export interface EmitterOptions {
      * importing the server**. Resolving one from the other with `../../..` would encode a particular
      * layout in the emitter, which is the sort of thing that breaks silently when a package moves.
      *
-     * Omitted, the contract types are simply not emitted — the emitter stays usable in a project that
+     * Omitted, the contract types are simply not emitted - the emitter stays usable in a project that
      * wants validators and nothing else.
      */
     "contracts-output-dir"?: string;
     /**
      * The package specifier the emitted Zod and wire assertions import their shared types from.
      *
-     * ⚠️ **There is deliberately no default.** It used to default to one repository's own package
+     * **There is deliberately no default.** It used to default to one repository's own package
      * name, so a consumer who configured nothing got validators importing from a package they had
-     * never heard of — output that looks right and does not resolve. There is no honest default for
+     * never heard of - output that looks right and does not resolve. There is no honest default for
      * "the caller's own package", so the absence is the answer: with no package named, an enum is
      * emitted inline and the output depends on nothing.
      */
@@ -31,10 +31,10 @@ export interface EmitterOptions {
      * Whether a model closed in the spec becomes a validator that REJECTS an undeclared property,
      * rather than one that strips it.
      *
-     * ⚠️ **Set this to whatever `@typespec/openapi3`'s `seal-object-schemas` is set to.** The two
+     * **Set this to whatever `@typespec/openapi3`'s `seal-object-schemas` is set to.** The two
      * emitters answer the same question about the same models, and this one cannot read the other's
      * configuration. Left mismatched, the published document and the runtime disagree about whether a
-     * property may exist — and the direction matters: sealing here while the document stays silent
+     * property may exist - and the direction matters: sealing here while the document stays silent
      * gives callers a `400` on a payload the contract permits.
      *
      * Defaults to `false`, which is openapi3's own default, so the two agree until somebody changes
@@ -45,14 +45,14 @@ export interface EmitterOptions {
     /**
      * Models whose PROPERTY NAMES are also emitted as a runtime tuple.
      *
-     * ⚠️ **For a key set that is a contract fact but cannot be a `Record` key type.** TypeSpec has no
+     * **For a key set that is a contract fact but cannot be a `Record` key type.** TypeSpec has no
      * key-constrained `Record` and OpenAPI's `propertyNames` is unreachable from it, so a closed set
-     * of attribute names is stated by naming the properties — which publishes the constraint, and
+     * of attribute names is stated by naming the properties - which publishes the constraint, and
      * leaves a consumer that needs the set at RUN time with nothing to iterate, because a generated
      * type is not a value. Naming the model here writes the keys beside the types as well.
      *
-     * ⚠️ **An option rather than a decorator, and the distinction is the whole point.** It changes no
-     * schema, states nothing in the document and enforces nothing — it selects an output. A mark in
+     * **An option rather than a decorator, and the distinction is the whole point.** It changes no
+     * schema, states nothing in the document and enforces nothing - it selects an output. A mark in
      * the spec that no document carries is what got this package's last four decorators deleted; see
      * `tsp-index.ts`.
      *
@@ -64,10 +64,10 @@ export interface EmitterOptions {
      * The specifier the generated files import their runtime contract from. Defaults to
      * `typespec-http-zod/runtime`.
      *
-     * ⚠️ **This is here because the emitted response arms are annotated, and the annotation earns its
+     * **This is here because the emitted response arms are annotated, and the annotation earns its
      * keep.** `schemas.gen.ts` declares what each operation may answer with as
-     * `… satisfies readonly ResponseArm[]`. Measured against the alternative: `as const` needs no
-     * import at all, and catches a wrong `status` — but it is **blind** to a misspelled or omitted
+     * `... satisfies readonly ResponseArm[]`. Measured against the alternative: `as const` needs no
+     * import at all, and catches a wrong `status` - but it is **blind** to a misspelled or omitted
      * `schema`, because `schema: undefined` is legitimate for a bodyless response. The typo then
      * produces a valid-looking arm that validates nothing, which is the failure this package exists to
      * prevent. `satisfies` reports both, at the declaration, naming the key.
@@ -81,7 +81,7 @@ export interface EmitterOptions {
     /**
      * Per-`@service` overrides, keyed by the service namespace name.
      *
-     * Two surfaces in one spec do not have to share a destination — an internal API and a public one
+     * Two surfaces in one spec do not have to share a destination - an internal API and a public one
      * typically publish to different packages, and the public one is built against by people who must
      * never receive the internal shapes. Falling back to the top-level values keeps a single-service
      * project configured exactly as if this key did not exist.
@@ -96,16 +96,13 @@ export interface EmitterOptions {
     }>;
 }
 /**
- * ⚠️ **Exported, because an emitter built on this library must DERIVE its option schema from this
+ * **Exported, because an emitter built on this library must DERIVE its option schema from this
  * one rather than restate it.** A server emitter adds its own keys and forwards the rest; two schemas
- * that have to agree are two lists that will not, and the failure is silent — an option the consumer
+ * that have to agree are two lists that will not, and the failure is silent - an option the consumer
  * sets, the wrapping emitter rejects as unknown, or accepts and never passes on.
  */
 export declare const EmitterOptionsSchema: JSONSchemaType<EmitterOptions>;
 export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
-    "unsupported-scalar": {
-        readonly default: import("@typespec/compiler").CallableMessage<["artefact", "name"]>;
-    };
     "unsupported-type": {
         readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why"]>;
     };
@@ -118,9 +115,6 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
     "empty-union": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;
     };
-    "circular-model": {
-        readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
-    };
     "unknown-key-vocabulary": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "service"]>;
     };
@@ -128,10 +122,7 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
         readonly default: import("@typespec/compiler").CallableMessage<["start", "end"]>;
     };
 }, EmitterOptions, never>;
-export declare const reportDiagnostic: <C extends "circular-model" | "empty-union" | "undeclared-discriminator" | "unknown-key-vocabulary" | "unsupported-default" | "unsupported-scalar" | "unsupported-status-code-range" | "unsupported-type", M extends keyof {
-    "unsupported-scalar": {
-        readonly default: import("@typespec/compiler").CallableMessage<["artefact", "name"]>;
-    };
+export declare const reportDiagnostic: <C extends "empty-union" | "undeclared-discriminator" | "unknown-key-vocabulary" | "unsupported-default" | "unsupported-status-code-range" | "unsupported-type", M extends keyof {
     "unsupported-type": {
         readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why"]>;
     };
@@ -144,9 +135,6 @@ export declare const reportDiagnostic: <C extends "circular-model" | "empty-unio
     "empty-union": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;
     };
-    "circular-model": {
-        readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
-    };
     "unknown-key-vocabulary": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "service"]>;
     };
@@ -154,9 +142,6 @@ export declare const reportDiagnostic: <C extends "circular-model" | "empty-unio
         readonly default: import("@typespec/compiler").CallableMessage<["start", "end"]>;
     };
 }[C]>(program: import("@typespec/compiler").Program, diag: import("@typespec/compiler").DiagnosticReport<{
-    "unsupported-scalar": {
-        readonly default: import("@typespec/compiler").CallableMessage<["artefact", "name"]>;
-    };
     "unsupported-type": {
         readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why"]>;
     };
@@ -169,9 +154,6 @@ export declare const reportDiagnostic: <C extends "circular-model" | "empty-unio
     "empty-union": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;
     };
-    "circular-model": {
-        readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
-    };
     "unknown-key-vocabulary": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "service"]>;
     };

package/dist/src/lib.js

@@ -1,8 +1,8 @@
 import { createTypeSpecLibrary, paramMessage } from "@typespec/compiler";
 /**
- * ⚠️ **Exported, because an emitter built on this library must DERIVE its option schema from this
+ * **Exported, because an emitter built on this library must DERIVE its option schema from this
  * one rather than restate it.** A server emitter adds its own keys and forwards the rest; two schemas
- * that have to agree are two lists that will not, and the failure is silent — an option the consumer
+ * that have to agree are two lists that will not, and the failure is silent - an option the consumer
  * sets, the wrapping emitter rejects as unknown, or accepts and never passes on.
  */
 export const EmitterOptionsSchema = {
@@ -38,16 +38,16 @@ export const EmitterOptionsSchema = {
 /**
  * What this emitter refuses, and why each refusal is a **diagnostic** rather than an exception.
  *
- * ⚠️ **A thrown error abandons the compile and names no source.** Every refusal here was once
+ * **A thrown error abandons the compile and names no source.** Every refusal here was once
  * `throw new UnsupportedTypeError(...)`, which reaches the user as
- * `Emitter "…" crashed! This is a bug. Please contact library author` — wrong on both counts when the
+ * `Emitter "..." crashed! This is a bug. Please contact library author` - wrong on both counts when the
  * spec asked for something the emitter has decided not to represent. Measured across a 65-scenario
  * corpus, four scenarios failed and a deliberate refusal (`never` has no runtime representation), a
  * design limit and a genuine stack overflow were **indistinguishable**: all three arrived as the same
  * "crashed" banner.
  *
  * A diagnostic points at the offending declaration, carries a code somebody can search for and
- * suppress, and — because reporting does not unwind — lets the walk continue and report *every*
+ * suppress, and - because reporting does not unwind - lets the walk continue and report *every*
  * problem in one compile rather than the first one it meets.
  *
  * **Internal invariant violations stay exceptions**, deliberately: `noteExternalImport` called
@@ -55,12 +55,13 @@ export const EmitterOptionsSchema = {
  * suppressible by the person writing the spec.
  */
 const diagnostics = {
-    "unsupported-scalar": {
-        severity: "error",
-        messages: {
-            default: paramMessage `Cannot emit ${"artefact"} for scalar '${"name"}': this emitter has no rule for it. Give it a known base with 'extends', or encode it with '@encode'.`,
-        },
-    },
+    /*
+     * `unsupported-scalar` was declared here and has been RETIRED. A scalar with no known base is not
+     * unrepresentable: `@typespec/openapi3` publishes `scalar Mystery;` as the empty schema `{}`, which
+     * asserts nothing and therefore accepts everything. Refusing it emitted `z.never()`, the exact
+     * inversion - measured, `"hello"`, `42` and `null` all rejected. Both walks now emit the faithful
+     * reading, `z.unknown()` and `unknown`, and openapi3 raises no diagnostic so neither does this.
+     */
     "unsupported-type": {
         severity: "error",
         messages: {
@@ -70,37 +71,37 @@ const diagnostics = {
     "unsupported-default": {
         severity: "error",
         messages: {
-            default: paramMessage `Cannot emit a default value of ${"why"}. Only scalar defaults and empty collections are representable.`,
+            default: paramMessage `Cannot emit a default value of ${"why"}. Scalars, arrays and objects are emitted as literals; a default built by a scalar constructor has no literal form. The property keeps its declared shape and loses only the fallback.`,
         },
     },
     /**
-     * ⚠️ **A discriminated union whose discriminator the document never publishes.**
+     * **A discriminated union whose discriminator the document never publishes.**
      *
-     * `@discriminated(#{envelope: "none"})` puts the discriminator inside the variant on the wire —
-     * `{kind: "cat", ...Cat}` — and `@typespec/openapi3` emits `oneOf: [Cat, Dog]` with a
+     * `@discriminated(#{envelope: "none"})` puts the discriminator inside the variant on the wire -
+     * `{kind: "cat", ...Cat}` - and `@typespec/openapi3` emits `oneOf: [Cat, Dog]` with a
      * `discriminator` keyword while never adding that property to the variant schema. OpenAPI 3.1
      * forbids exactly this: "the `discriminator` field MUST be a required field". So the published
      * contract cannot require the property, and under `seal-object-schemas` it forbids it outright.
      *
-     * ⚠️ **Confirmed upstream, not inferred here:** `microsoft/typespec#7141`, open since 2025-04-27,
+     * **Confirmed upstream, not inferred here:** `microsoft/typespec#7141`, open since 2025-04-27,
      * labelled `[Bug]` / `design:needed` / `emitter:openapi3` and filed by a maintainer against these
      * exact shapes. Nothing here needs raising; the refusal stands until that lands.
      *
-     * ⚠️ **Refused rather than compensated for, and that distinction is the whole point.** This
-     * emitter did briefly inject the discriminator itself — the validator was right, the document was
+     * **Refused rather than compensated for, and that distinction is the whole point.** This
+     * emitter did briefly inject the discriminator itself - the validator was right, the document was
      * wrong, and it was recorded as a "declared divergence" with a warning and a committed list. That
      * is a custom track with a label on it: runtime behaviour derived from nothing the document
      * states. A validator may only enforce what the contract says.
      *
-     * **It is avoidable, and the message says how.** Declaring the discriminator on the variant —
-     * `model Cat { kind: "cat"; … }` — makes openapi3 publish it as required, and everything works
+     * **It is avoidable, and the message says how.** Declaring the discriminator on the variant -
+     * `model Cat { kind: "cat"; ... }` - makes openapi3 publish it as required, and everything works
      * with no divergence and no refusal. The refusal lands only on the spelling that cannot produce
      * an honest contract.
      */
     "undeclared-discriminator": {
         severity: "error",
         messages: {
-            default: paramMessage `'${"name"}' serialises with '${"property"}' inside each variant, but '${"variant"}' does not declare it — so the OpenAPI document omits it, which OpenAPI 3.1 forbids for a discriminator ("the discriminator field MUST be a required field"). Emitting a validator that required it anyway would enforce a rule the published contract does not state. Declare '${"property"}' on '${"variant"}'.`,
+            default: paramMessage `'${"name"}' serialises with '${"property"}' inside each variant, but '${"variant"}' does not declare it - so the OpenAPI document omits it, which OpenAPI 3.1 forbids for a discriminator ("the discriminator field MUST be a required field"). Emitting a validator that required it anyway would enforce a rule the published contract does not state. Declare '${"property"}' on '${"variant"}'.`,
         },
     },
     "empty-union": {
@@ -109,27 +110,18 @@ const diagnostics = {
             default: paramMessage `A union with no representable variants (${"why"}) has nothing to validate against.`,
         },
     },
-    /**
-     * ⚠️ **Most cycles are not this.** A recursive model is an ordinary construct — `@typespec/openapi3`
-     * publishes a self-`$ref` and the document is valid — so it is emitted as a reference, deferred
-     * behind a getter on the property that closes the loop. This diagnostic is for the remainder: a
-     * cycle whose path holds **no object property**, and so has nowhere to put that getter. A named
-     * union whose variant refers back to a model still being rendered is the reachable case.
-     *
-     * Reported rather than thrown so the walk names every such cycle instead of dying inside the
-     * first — and, before the getters existed, so an inline cycle produced this rather than a
-     * `RangeError: Maximum call stack size exceeded`.
+    /*
+     * `circular-model` was declared here and has been RETIRED, because it refused something that can
+     * be represented. It fired on a cycle whose path holds no object property - a union variant or a
+     * dictionary value - on the grounds that a getter needs a property to sit on. True, and beside the
+     * point: `z.lazy()` needs no property, and deferring the whole declaration is where the laziness
+     * goes once nothing smaller can hold it. See `registry.ts` for the measurements, including why the
+     * fix needs a structural type and an annotation rather than `z.lazy()` alone.
      */
-    "circular-model": {
-        severity: "error",
-        messages: {
-            default: paramMessage `'${"name"}' closes a cycle through a declaration that cannot defer it — a union variant or a dictionary value, neither of which is a property a getter can sit on, so the emitted schema would read itself while initialising. Route the cycle through a model property, or break it in the spec.`,
-        },
-    },
     /**
      * A `key-vocabularies` entry naming no model in the service.
      *
-     * ⚠️ **Reported rather than ignored, because the failure mode is silence.** The option exists so a
+     * **Reported rather than ignored, because the failure mode is silence.** The option exists so a
      * consumer can iterate a closed key set at run time; a typo would emit no tuple at all, and "the
      * vocabulary is missing" looks exactly like "the vocabulary is empty" at the point it is used.
      */
@@ -142,19 +134,19 @@ const diagnostics = {
     /**
      * A status RANGE that OpenAPI cannot key.
      *
-     * ⚠️ **This replaced `mixed-error-bodies`, which was a different refusal for the same scenario and
+     * **This replaced `mixed-error-bodies`, which was a different refusal for the same scenario and
      * the wrong diagnosis of it.** That one said "a service must answer every failure with one body
-     * shape" — an assumption this emitter no longer makes, since each declared response resolves its
+     * shape" - an assumption this emitter no longer makes, since each declared response resolves its
      * own body. What is genuinely unrepresentable is narrower and is not ours: OpenAPI keys a range as
-     * `1XX`…`5XX`, so `@minValue(494) @maxValue(499)` has nowhere to go.
+     * `1XX`...`5XX`, so `@minValue(494) @maxValue(499)` has nowhere to go.
      *
-     * ⚠️ **Refused because `@typespec/openapi3` refuses it**, with the same rule copied from its
+     * **Refused because `@typespec/openapi3` refuses it**, with the same rule copied from its
      * `rangeToOpenAPI`. Bucketing `494-499` into `4XX` anyway would make a server claim a `400`
-     * carries that body — a rule no document states, because openapi3 declines to publish a document
+     * carries that body - a rule no document states, because openapi3 declines to publish a document
      * for this spec at all. The same source is then either representable by both emitters or neither,
      * which is the only arrangement under which a differential between them means anything.
      *
-     * A range that covers a bucket exactly — `@minValue(400) @maxValue(499)` — is supported and emits
+     * A range that covers a bucket exactly - `@minValue(400) @maxValue(499)` - is supported and emits
      * a `4XX` arm.
      */
     "unsupported-status-code-range": {

package/dist/src/registry.d.ts

@@ -1,14 +1,64 @@
 import type { ModelProperty, Program, Type } from "@typespec/compiler";
+/**
+ * Assigns each named TypeSpec model/enum a single Zod declaration, emitted in dependency order.
+ *
+ * Without this, a model used by twelve operations is inlined twelve times: the generated file grows
+ * quadratically, and - worse - the *type* it infers is a fresh structural type at each site, so
+ * `apps/web` gets twelve `Company`s that are only accidentally the same. One declaration per model
+ * is what makes the emitted types usable as a shared vocabulary rather than as twelve coincidences.
+ */
+/**
+ * **A cycle with no property on its path - and it used to be refused.**
+ *
+ * **A recursive model is NOT this.** `model InnerModel { children?: InnerModel[] }` is an ordinary
+ * tree - `@typespec/openapi3` publishes a self-`$ref` for it and the document is valid - so it is
+ * emitted as a reference, made lazy by a getter on the property that closes the loop (see
+ * `modelToZod`). What this handles is a cycle with no property to hang a getter on: a named **union**
+ * whose variant refers back to a model still being rendered, or a dictionary VALUE that does.
+ *
+ * **`circular-model` claimed this was unrepresentable, and it was merely unimplemented.** Measured
+ * on Zod 4.4.3, `z.lazy()` closes every one of these at run time - a union-variant cycle and a
+ * dictionary-value cycle both parse nested values and, importantly, still **reject at depth**, so the
+ * schema has not quietly degraded to something that accepts anything.
+ *
+ * **But `z.lazy()` alone does not TYPECHECK, and that is the whole difficulty.** Measured with
+ * `tsc` under `strict`:
+ *
+ * ```
+ * TS7022: 'branchSchema' implicitly has type 'any' because it does not have a type annotation
+ *         and is referenced directly or indirectly in its own initializer.
+ * TS7022: 'nodeSchema'   implicitly has type 'any' ...        <- it poisons the sibling too
+ * ```
+ *
+ * Inferring `any` is worse than failing to compile, because `wire-contract.gen.ts` asserts
+ * `Identical<z.infer<typeof X>, Contracts.X>` - against `any` that assertion PASSES while proving
+ * nothing, which is the one outcome this package treats as worse than a red test.
+ *
+ * The fix is the recipe Zod documents: give the deferred declaration an explicit `z.ZodType<T>` and
+ * declare `T` structurally. Measured, `tsc` exit 0 with the identity assertion still holding.
+ *
+ * **EVERY member of the cycle needs its structural type, not only the deferred one.** Leaving the
+ * others as `export type X = z.infer<typeof xSchema>` reintroduces the loop through the annotation -
+ * measured: `TS2456: Type alias 'Branch' circularly references itself` plus `TS2502` and `TS7022`. So
+ * cycle membership, not merely deferral, decides which declarations are emitted structurally.
+ */
 interface Declaration {
     readonly identifier: string;
     readonly typeName: string;
     readonly source: string;
+    /**
+     * The structural TypeScript body for a declaration on a cycle, emitted INSTEAD of the
+     * `z.infer<typeof ...>` alias - which cannot be used here without closing the type-level loop.
+     */
+    readonly structural?: string;
+    /** Whether the declaration is annotated `: z.ZodType<typeName>`, which `z.lazy()` requires. */
+    readonly annotated?: boolean;
 }
 export declare class SchemaRegistry {
     #private;
     constructor(program: Program);
     /**
-     * The Zod expression for a type — a bare identifier once the type has a declaration, otherwise
+     * The Zod expression for a type - a bare identifier once the type has a declaration, otherwise
      * inline source. Declaring is depth-first so a model's dependencies are emitted above it, which is
      * what lets the generated file be plain `const` declarations with no forward references.
      */
@@ -16,7 +66,7 @@ export declare class SchemaRegistry {
     /**
      * The Zod for a single property, constraints and optionality included.
      *
-     * Used for path/query parameters, which are `ModelProperty`s that belong to no model — so they
+     * Used for path/query parameters, which are `ModelProperty`s that belong to no model - so they
      * need the property-level walk rather than the type-level one, or `@minLength` on a path param
      * would be documented and never enforced.
      */
@@ -24,14 +74,14 @@ export declare class SchemaRegistry {
     /**
      * A declaration for a shape the spec never wrote, under a name the document publishes.
      *
-     * `@discriminated` with an envelope has no TypeSpec type for its wrapper — openapi3 synthesises
+     * `@discriminated` with an envelope has no TypeSpec type for its wrapper - openapi3 synthesises
      * one and publishes it as `PetWithEnvelopeCat`, so there is a component with no `Type` to key on.
      * Keyed by name instead, and pushed in the same dependency-first order as everything else, so the
      * envelope declarations land above the union that references them.
      *
      * `declareNamed` exposes the same seam to the route emitter, which needs it for a **multipart**
      * body: the document publishes `MultiPartRequest` as a component, and there is no walkable type
-     * for it — the parts have to be assembled from `@typespec/http`'s own view of the payload.
+     * for it - the parts have to be assembled from `@typespec/http`'s own view of the payload.
      */
     declareNamed(name: string, build: () => string): string;
     /** Every declaration, dependencies first. */
@@ -41,7 +91,7 @@ export interface TsDeclaration {
     readonly name: string;
     /** `true` when the body is an object literal and can be emitted as an `interface`. */
     readonly isObject: boolean;
-    /** `true` for an enum-derived alias — declared but not exported, see below. */
+    /** `true` for an enum-derived alias - declared but not exported, see below. */
     readonly isVocabulary: boolean;
     readonly source: string;
 }
@@ -49,7 +99,7 @@ export interface TsDeclaration {
  * The same walk as {@link SchemaRegistry}, emitting plain TypeScript instead of Zod.
  *
  * Kept as a separate class rather than a mode on the schema registry because the two produce
- * different *kinds* of declaration — an `interface` versus a `const` — and their reference resolvers
+ * different *kinds* of declaration - an `interface` versus a `const` - and their reference resolvers
  * hand back different text. Sharing {@link declaredNameOf} is the part that matters: a model named in
  * one artefact is named the same way in the other, so the emitted assertion can pair them by name.
  */
@@ -58,11 +108,12 @@ export declare class TypeRegistry {
     constructor(program: Program);
     expressionFor(type: Type): string;
     /**
-     * The Zod-free type for a single property — used for path and query parameters, which are
+     * The Zod-free type for a single property - used for path and query parameters, which are
      * `ModelProperty`s belonging to no model. Without routing them through the registry a named model
      * or enum in a parameter position is inlined rather than referenced.
      */
-    expressionForProperty(property: ModelProperty): string;
+    /** `wireName` names an HTTP parameter as the wire does - see {@link propertyToTs}. */
+    expressionForProperty(property: ModelProperty, wireName?: string): string;
     /** Every declaration, dependencies first. */
     declarations(): readonly TsDeclaration[];
 }