typespec-http-zod 0.1.0 → 0.3.0

package/dist/src/zod.js

@@ -5,7 +5,7 @@ import { reportDiagnostic } from "./lib.js";
 /**
  * What a walk returns after reporting a refusal.
  *
- * ⚠️ **Reporting does not unwind, which is the point.** A throw abandoned the compile at the first
+ * **Reporting does not unwind, which is the point.** A throw abandoned the compile at the first
  * unrepresentable construct; reporting lets the walk carry on and name every one of them in a single
  * run. The walk still has to return a `string`, and `z.never()` is the honest placeholder: valid
  * Zod, rejects everything, and unreachable in practice because the error diagnostic has already
@@ -13,53 +13,53 @@ import { reportDiagnostic } from "./lib.js";
  */
 const UNREPRESENTABLE = "z.never()";
 /**
- * TypeSpec type → Zod source text.
+ * TypeSpec type -> Zod source text.
  *
- * **Deliberately partial, and it fails loudly rather than guessing.** A general TypeSpec→Zod
+ * **Deliberately partial, and it fails loudly rather than guessing.** A general TypeSpec->Zod
  * converter has to answer for every construct the language can express; this one only has to answer
  * for the constructs our own specs are allowed to use, which is what makes it a bounded problem
  * rather than an open-ended dependency (see the ADR on why `typespec-zod@0.0.0-68` is not in the
- * runtime path). Anything outside that set throws with the offending type named — an emitter that
+ * runtime path). Anything outside that set throws with the offending type named - an emitter that
  * silently produced `z.any()` for a construct it did not understand would push a hole all the way
  * into `respond()`, where the whole point is that drift is caught.
  */
 /**
- * External module → the constants the emitted schemas reference from it.
+ * External module -> the constants the emitted schemas reference from it.
  *
  * Collected during emission rather than pre-scanned: only the enums actually reachable from an
  * operation should produce an import, and reachability is exactly what the walk already computes.
  *
- * ⚠️ **Scoped to one emission, not module-global-and-cleared.** The previous shape was a module
+ * **Scoped to one emission, not module-global-and-cleared.** The previous shape was a module
  * `Map` emptied by whoever read it first, which is correct only while there is exactly one service
- * and one read. A second `@service` namespace — a public surface beside an internal one — would
+ * and one read. A second `@service` namespace - a public surface beside an internal one - would
  * have merged one surface's imports into the other's file: an unused import if lucky, a missing one
  * if not. Neither is discoverable while there is only one service, so it is fixed before there are
  * two rather than found by them. Same save/restore idiom as {@link withRefResolver}.
  */
 let externalImports;
 /**
- * Enum name → its declared members, for every vocabulary the surface actually reaches.
+ * Enum name -> its declared members, for every vocabulary the surface actually reaches.
  *
  * The spec is the single source for these. A consumer's shared package used to hold them as tuples
- * and the spec merely *described* them for the document's benefit — two lists that agreed only by
+ * and the spec merely *described* them for the document's benefit - two lists that agreed only by
  * inspection, and by the time this flipped, two of them did not: `PersonalAttribute` published four
  * of six values wrong (the charge-authentication answers an MR01 cannot be filed without) and
  * `SubmissionStatusCode` published all five wrong. Generating them removes the second list.
  */
 let vocabularies;
 /**
- * Whether a model is SEALED — closed to properties nobody declared.
+ * Whether a model is SEALED - closed to properties nobody declared.
  *
- * ⚠️ **A property of the model's own shape, not of where it is used.** This was previously "the
+ * **A property of the model's own shape, not of where it is used.** This was previously "the
  * model is reachable from a request body", computed by a whole-graph pre-pass. That rule is wrong in
  * a way that is invisible while it happens to agree: there is one declaration per model, so adding a
  * single operation that accepts `ProblemItem` in a body would flip `problemItemSchema` from
  * stripping to rejecting **in every response that uses it too**. Strictness would be decided by the
  * rest of the spec rather than by the model.
  *
- * ⚠️ **This mirrors `@typespec/openapi3`'s `shouldSealSchema` deliberately, line for line.** The
+ * **This mirrors `@typespec/openapi3`'s `shouldSealSchema` deliberately, line for line.** The
  * emitted validator and the published document have to answer the same question the same way, and
- * the only way to guarantee that is to ask it the same way — not to arrive at the same answer by a
+ * the only way to guarantee that is to ask it the same way - not to arrive at the same answer by a
  * different route and measure that they still agree. The exception for models with derived models is
  * theirs: sealing a base would make a subtype's own properties "unevaluated" against it.
  *
@@ -69,7 +69,7 @@ let vocabularies;
  * `seal-object-schemas` in `EmitterOptions`, defaulting to openapi3's own default.
  */
 function isSealed(model) {
-    // `Record<never>` is closed whatever the option says — the spec has stated it outright, and
+    // `Record<never>` is closed whatever the option says - the spec has stated it outright, and
     // openapi3 seals it for the same reason.
     if (model.indexer !== undefined)
         return isNeverType(model.indexer.value);
@@ -80,11 +80,11 @@ function isSealed(model) {
 /**
  * Whether `@typespec/openapi3` is sealing object schemas for this compile.
  *
- * ⚠️ **This emitter cannot see the other emitter's options, so the consumer states it twice.**
+ * **This emitter cannot see the other emitter's options, so the consumer states it twice.**
  * Awkward, and the alternative is worse: assume sealing is on and a project running openapi3 with
  * its default gets validators that reject properties its published document permits. Whichever way
  * the two are configured, the conformance differential compares openness in both directions and
- * fails on a mismatch — so a project that sets one and forgets the other is told immediately rather
+ * fails on a mismatch - so a project that sets one and forgets the other is told immediately rather
  * than shipping a contradiction.
  */
 let sealObjectSchemas = false;
@@ -99,7 +99,7 @@ export function withSealedObjects(sealed, run) {
     }
 }
 /**
- * The visibility the current walk is emitting for — which decides what counts as HTTP metadata.
+ * The visibility the current walk is emitting for - which decides what counts as HTTP metadata.
  *
  * Visibility decides **which** metadata applies: `@statusCode` is applicable to a response and not
  * to a request, so the same model projects differently in the two directions. `createMetadataInfo`
@@ -107,7 +107,7 @@ export function withSealedObjects(sealed, run) {
  * from answering differently. Measured on `type/model/visibility`: openapi3 emits five components
  * for one model, and before this we emitted one carrying every lifecycle property at once.
  *
- * ⚠️ **Position is a SECOND axis, and this only handles the first.** `@header` is metadata at a
+ * **Position is a SECOND axis, and this only handles the first.** `@header` is metadata at a
  * payload root and ordinary data nested inside a `@body`; `isPayloadProperty` takes a third
  * argument, `ignoreMetadataAnnotations`, which openapi3 threads as emitter context
  * (`schema-emitter.js:210`) and this does not pass. A metadata-carrying model used in **both**
@@ -116,11 +116,11 @@ export function withSealedObjects(sealed, run) {
  * That shape is rare rather than theoretical: it raises `metadata-ignored` from `@typespec/http`,
  * which fires **zero** times across all 65 `@typespec/http-specs` scenarios,
  * and one variant of it makes openapi3 itself fail with `duplicate-type-name`. It is a real gap with
- * no known occurrence — recorded here rather than described as an incident, because it has not been
+ * no known occurrence - recorded here rather than described as an incident, because it has not been
  * one.
  *
  * Scoped rather than threaded through six signatures, matching the idiom the rest of this module
- * already uses — the walk is deeply recursive and a parameter would have to be carried by every
+ * already uses - the walk is deeply recursive and a parameter would have to be carried by every
  * function whether it cared or not.
  */
 let visibility = Visibility.Read;
@@ -138,7 +138,7 @@ export function withVisibility(program, next, run) {
         metadataInfo = previousInfo;
     }
 }
-/** Whether a property is optional AT THE CURRENT POSITION — PATCH makes update fields optional. */
+/** Whether a property is optional AT THE CURRENT POSITION - PATCH makes update fields optional. */
 function isOptionalAt(program, property) {
     metadataInfo ??= createMetadataInfo(program);
     return metadataInfo.isOptional(property, visibility);
@@ -153,12 +153,12 @@ export function isTransformedBy(program, model, at) {
     metadataInfo ??= createMetadataInfo(program);
     return metadataInfo.isTransformed(model, at);
 }
-/** The visibility the current walk is emitting for — the registry keys declarations on it. */
+/** The visibility the current walk is emitting for - the registry keys declarations on it. */
 export function currentVisibility() {
     return visibility;
 }
 /**
- * openapi3's own rule for which derived models count — `@typespec/openapi3`'s `util.ts`.
+ * openapi3's own rule for which derived models count - `@typespec/openapi3`'s `util.ts`.
  *
  * A template declaration is not a real subtype, and neither is an uninstantiated template; both
  * would otherwise stop a base from being sealed for no reason a reader could see.
@@ -176,8 +176,8 @@ function noteVocabulary(name, values) {
 /**
  * Record every enum a service DECLARES, not merely every one its success bodies happen to reach.
  *
- * ⚠️ **A vocabulary is a fact about the contract, not about a code path.** Collecting them during the
- * Zod walk meant an enum reachable only through an ERROR body was never emitted — which is exactly
+ * **A vocabulary is a fact about the contract, not about a code path.** Collecting them during the
+ * Zod walk meant an enum reachable only through an ERROR body was never emitted - which is exactly
  * what happened to one surface's error-code enum: declared in the spec, published on every
  * operation's failure responses, and absent from the generated vocabularies, so the one list a
  * consumer branches on had to be hand-written beside the generated ones. Walking declarations removes
@@ -191,16 +191,16 @@ export function noteDeclaredVocabularies(enums) {
 /**
  * Record a named model's PROPERTY NAMES as a runtime vocabulary.
  *
- * ⚠️ **This exists because "a `Record` keyed by an enum" is inexpressible, and the workaround was
+ * **This exists because "a `Record` keyed by an enum" is inexpressible, and the workaround was
  * about to cost a duplicated list.** `ProfileAttributes` is 150-odd known keys; naming them in the
  * spec is what makes the published document state the constraint instead of hiding it behind a
  * hand-written predicate. But a *type* cannot be iterated, and more than one layer usually needs
- * the set at RUN time — so without this the keys would live in the spec AND as a hand-maintained
- * tuple in a shared package — one vocabulary stated twice, which is precisely the
+ * the set at RUN time - so without this the keys would live in the spec AND as a hand-maintained
+ * tuple in a shared package - one vocabulary stated twice, which is precisely the
  * drift the deleted predicate existed to prevent.
  *
- * ⚠️ **Selected by an emitter OPTION, deliberately not by a decorator.** A decorator would put a
- * mark in the spec that no document carries — the exact objection that deleted the last four. This
+ * **Selected by an emitter OPTION, deliberately not by a decorator.** A decorator would put a
+ * mark in the spec that no document carries - the exact objection that deleted the last four. This
  * changes no schema, states nothing in the contract and enforces nothing; it decides which
  * convenience artefact gets written beside the types, which is what an emitter option is for.
  *
@@ -228,16 +228,16 @@ export function noteExternalImport(module, name) {
     externalImports.set(module, names);
 }
 /**
- * Which package the generated Zod imports its vocabularies from — `undefined` when there is none.
+ * Which package the generated Zod imports its vocabularies from - `undefined` when there is none.
  *
- * ⚠️ **Not a constant, and no longer defaulted.** Each `@service` publishes its own contracts
+ * **Not a constant, and no longer defaulted.** Each `@service` publishes its own contracts
  * package, so a hardcoded specifier makes the second service's schemas import names that package
  * does not export. Scoped the same way the strict-model set is, so a nested emission cannot leak
  * into its parent.
  *
- * ⚠️ **It used to default to one repository's own package name.** A
+ * **It used to default to one repository's own package name.** A
  * consumer who configured nothing got validators importing `SPEC_VOCABULARIES` from a package they
- * had never heard of — output that looks right and does not resolve. There is no honest default for
+ * had 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.
  */
@@ -331,24 +331,38 @@ function scalarToZod(program, scalar) {
     while (current !== undefined) {
         const mapped = SCALARS[current.name];
         // Constraints are read from the scalar the property NAMED, not from the primitive it resolves
-        // to, so `@pattern(…) scalar TrimmedString extends string` carries its rules to every use.
+        // to, so `@pattern(...) scalar TrimmedString extends string` carries its rules to every use.
         if (mapped !== undefined)
             return applyConstraints(program, mapped, scalar);
         current = current.baseScalar;
     }
-    reportDiagnostic(program, {
-        code: "unsupported-scalar",
-        target: scalar,
-        format: { artefact: "Zod", name: scalar.name },
-    });
-    return UNREPRESENTABLE;
+    /**
+     * **A scalar with no known base is `z.unknown()`, and it used to be a refusal.**
+     *
+     * **`z.never()` was the exact inversion of what the document says.** `scalar Mystery;` is
+     * published by `@typespec/openapi3` as `"Mystery": {}` - the empty schema, which under JSON Schema
+     * asserts nothing and therefore accepts **everything**. This emitter refused the compile and, on the
+     * way, wrote `value: z.never()`, which accepts **nothing**. Measured against the emitted schema:
+     * `"hello"`, `42` and `null` were all rejected, so a service built on it would answer 400 to every
+     * request the document calls valid.
+     *
+     * Refusing was the wrong answer twice over: the document represents the spec perfectly, so under the
+     * governing rule this emitter must too - the same source has to be representable by both or by
+     * neither. And `z.unknown()` is not a guess, it is the precise reading of `{}`: a validator that
+     * enforces nothing is what a schema asserting nothing means.
+     *
+     * No diagnostic, because openapi3 raises none. Copying its rule includes copying its silence; a
+     * warning here would report a problem the published contract does not have. This is the same
+     * treatment a raw binary body already gets, for the same reason.
+     */
+    return applyConstraints(program, "z.unknown()", scalar);
 }
 /**
  * A TypeSpec `enum` becomes a Zod enum over its member values, resolved through the generated
  * vocabulary constant so the document and the runtime cannot describe different sets.
  *
- * ⚠️ **`@externalValues` used to be able to point that arrow the other way** — the spec deferring to
- * a hand-written TypeScript tuple — and while it did, the members here described only the
+ * **`@externalValues` used to be able to point that arrow the other way** - the spec deferring to
+ * a hand-written TypeScript tuple - and while it did, the members here described only the
  * *document*. It is gone, and the tuples are generated from the spec.
  */
 function enumToZod(_program, target) {
@@ -359,7 +373,7 @@ function enumToZod(_program, target) {
     /**
      * Every string vocabulary resolves through the generated constant rather than being restated.
      *
-     * The members are declared once, in the spec, and the vocabularies artefact is generated from them —
+     * The members are declared once, in the spec, and the vocabularies artefact is generated from them -
      * so the document and the runtime cannot describe different vocabularies. This replaces the
      * `@externalValues` decorator, which pointed the arrow the other way: the spec deferred to a
      * hand-written TypeScript constant, which is the opposite of a spec being a source of truth.
@@ -368,7 +382,7 @@ function enumToZod(_program, target) {
     /**
      * Inline unless the consumer named a package to share the tuple through.
      *
-     * The indirection exists so a SECOND package — another layer, a client — can branch on the same
+     * The indirection exists so a SECOND package - another layer, a client - can branch on the same
      * values without restating them. A consumer who has no such package wants a self-contained
      * validator, and emitting a reference to one they never configured is the only way to get output
      * that cannot resolve.
@@ -390,7 +404,7 @@ function enumToZod(_program, target) {
 /**
  * Register a declaration the SPEC never wrote, under a name the document publishes.
  *
- * A `@discriminated` union with an envelope has no TypeSpec type for its wrapper — openapi3
+ * A `@discriminated` union with an envelope has no TypeSpec type for its wrapper - openapi3
  * synthesises one (`tk.model.create`, `schema-emitter.js:436`) and publishes it as
  * `PetWithEnvelopeCat`. The registry keys declarations on a `Type`, and there is no type to key on,
  * so this is the seam that lets one be declared by name instead. Falls back to inlining when no
@@ -418,17 +432,17 @@ function declaresDiscriminator(program, variant, property) {
 /**
  * One variant of a `@discriminated` union, as it appears ON THE WIRE.
  *
- * ⚠️ **The union is not a choice between its variant types — it is a choice between wrappings of
+ * **The union is not a choice between its variant types - it is a choice between wrappings of
  * them**, and this emitter used to ignore the wrapping entirely. `z.discriminatedUnion("kind",
  * [catSchema, dogSchema])` over models that carry no `kind` at all **matches nothing**: every
  * request to a polymorphic endpoint failed, and the differential could not see it because it read a
  * discriminated component as an object.
  *
- * `envelope: "object"` (the default) wraps the variant — `{kind: "cat", value: {…Cat}}` — and
+ * `envelope: "object"` (the default) wraps the variant - `{kind: "cat", value: {...Cat}}` - and
  * openapi3 publishes each wrapper as a component named `union.type.name + capitalize(variantName)`.
  * Mirrored exactly, so the identifiers line up with the component names.
  *
- * `envelope: "none"` injects the discriminator into the variant — `{kind: "cat", …Cat}` — and is
+ * `envelope: "none"` injects the discriminator into the variant - `{kind: "cat", ...Cat}` - and is
  * emitted **only when the variant declares that property itself**. Otherwise the document does not
  * publish it and the union is refused; see `undeclared-discriminator`.
  */
@@ -452,19 +466,19 @@ function unionToZod(program, union) {
      * Both accept the same values, but a plain union reports "no variant matched" and lists every
      * failure, while a discriminated one reads the tag and reports the single rule that was actually
      * broken. These unions exist to carry cross-field rules that used to hide in a hand-written
-     * predicate — publishing the rule and then reporting it unreadably would only move the problem.
+     * predicate - publishing the rule and then reporting it unreadably would only move the problem.
      */
     const [discriminated] = getDiscriminatedUnion(program, union);
     if (discriminated !== undefined) {
         const options = discriminated.options;
         if (discriminated.defaultVariant !== undefined) {
             // "Anything else" has no discriminator value to switch on. Refused by name rather than
-            // silently dropped — no corpus scenario exercises it, so guessing would be untested code.
+            // silently dropped - no corpus scenario exercises it, so guessing would be untested code.
             return refuse(program, union, "a discriminated union with a default variant");
         }
         /**
-         * ⚠️ **Refused, not compensated for.** With no envelope the discriminator lives inside the
-         * variant, and openapi3 publishes the variant unchanged — so unless the variant declares the
+         * **Refused, not compensated for.** With no envelope the discriminator lives inside the
+         * variant, and openapi3 publishes the variant unchanged - so unless the variant declares the
          * property, the document names a discriminator it never requires, which OpenAPI 3.1 forbids.
          * Injecting it here would enforce a rule the contract does not state: correct against the wire,
          * derived from nothing anybody published, and indistinguishable from a bug to every other
@@ -512,25 +526,25 @@ function unionToZod(program, union) {
 /**
  * TypeSpec models arrays and dictionaries as a `Model` carrying an **indexer**.
  *
- * ⚠️ **Keyed on the indexer, not on the model's name.** This used to test `name === "Record"`, which
- * silently lost the indexer of any model *derived* from one — `model ProfileAttributes is
+ * **Keyed on the indexer, not on the model's name.** This used to test `name === "Record"`, which
+ * silently lost the indexer of any model *derived* from one - `model ProfileAttributes is
  * Record<string | float64 | boolean>` emitted `z.object({})`, a schema that accepts an object and
  * then strips every key in it. For the profile attributes that is silent data loss on a write, and
  * nothing downstream could have told the difference between "the caller sent nothing" and "we threw
  * it away". A named model is still declared and referenced normally; only its *body* comes from the
  * indexer.
  */
-/** `unknown` — the indexer value of a `...Record<unknown>` spread, which is plain permissiveness. */
+/** `unknown` - the indexer value of a `...Record<unknown>` spread, which is plain permissiveness. */
 function isUnknownType(type) {
     return type.kind === "Intrinsic" && type.name === "unknown";
 }
 /**
  * Every property the model declares, **including the ones it inherits**.
  *
- * ⚠️ **`model.properties` holds only a model's OWN properties, and `baseModel` appeared nowhere in
+ * **`model.properties` holds only a model's OWN properties, and `baseModel` appeared nowhere in
  * this emitter.** `model Extension extends Element` reaches the document as `allOf: [{$ref: Element}]`
- * beside the derived model's own properties, and the sealing keyword openapi3 uses —
- * `unevaluatedProperties` — is chosen precisely because it sees through that. So the document said
+ * beside the derived model's own properties, and the sealing keyword openapi3 uses -
+ * `unevaluatedProperties` - is chosen precisely because it sees through that. So the document said
  * `Extension` carries `level` **and** the inherited `extension`, while this emitter produced
  * `z.object({level}).strict()`: the inherited property gone, and the model closed against it. The
  * conformance scenario's own documented request body would have been rejected with a 400 naming a key
@@ -538,12 +552,12 @@ function isUnknownType(type) {
  *
  * Invisible for two reasons at once. The spec it was first built against declared no `extends` at
  * all, and the differential
- * skipped every schema carrying an `allOf` — so 28 of 226 components were not divergent, they were
+ * skipped every schema carrying an `allOf` - so 28 of 226 components were not divergent, they were
  * never compared.
  *
  * Flattened rather than composed. `z.object(...).extend(...)` would mirror the document's structure
  * more literally and cannot be used here: `.extend()` reads `shape` eagerly, so a base whose property
- * refers back to the derived model — `type/model/inheritance/recursive`, the exact case — would throw
+ * refers back to the derived model - `type/model/inheritance/recursive`, the exact case - would throw
  * during module initialisation. Flattening asks nothing of the base but its properties.
  */
 export function inheritedAndOwnProperties(model) {
@@ -559,7 +573,7 @@ export function inheritedAndOwnProperties(model) {
     }
     return [...byName.values()];
 }
-/** The indexer in force, which a model can inherit — `model X extends Record<unknown>`. */
+/** The indexer in force, which a model can inherit - `model X extends Record<unknown>`. */
 export function effectiveIndexer(model) {
     for (let link = model; link !== undefined; link = link.baseModel) {
         if (link.indexer !== undefined)
@@ -571,7 +585,7 @@ export function effectiveIndexer(model) {
  * The subtypes a `@discriminator` base stands for, in declaration order.
  *
  * Filtered by openapi3's own {@link includeDerivedModel} so a template declaration is not mistaken
- * for a real subtype — the same rule that decides whether a base may be sealed.
+ * for a real subtype - the same rule that decides whether a base may be sealed.
  */
 export function discriminatedSubtypes(program, model) {
     if (getDiscriminator(program, model) === undefined)
@@ -580,18 +594,18 @@ export function discriminatedSubtypes(program, model) {
 }
 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, not a shape of its own.**
      *
      * `@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})`,
-     * which accepts `{kind: "eagle"}` while ignoring everything `Eagle` actually declares — a
+     * 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
-     * `Fish → Shark → SawShark` works; and an option carrying a getter that refers back to the union
+     * `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.
@@ -609,10 +623,10 @@ function modelToZod(program, model) {
         return applyConstraints(program, `z.array(${typeToZod(program, indexer.value)})`, model);
     }
     /**
-     * ⚠️ **A string indexer only means "dictionary" when the model declares NO properties.**
+     * **A string indexer only means "dictionary" when the model declares NO properties.**
      *
-     * `model X { id: string; ...Record<unknown> }` — the standard TypeSpec way to say "these fields,
-     * plus anything else", and what `@loose` was replaced by — carries both. Returning
+     * `model X { id: string; ...Record<unknown> }` - the standard TypeSpec way to say "these fields,
+     * plus anything else", and what `@loose` was replaced by - carries both. Returning
      * `z.record(...)` for it emits a schema that accepts an object and then **strips every declared
      * field**, so `respond()`'s drift detection degrades to "is it an object" and the pinned fields
      * silently stop being checked. This function's own history is the other half of the same mistake:
@@ -625,8 +639,8 @@ function modelToZod(program, model) {
      * Permissiveness, read from the INDEXER and from nothing else.
      *
      * `...Record<unknown>` is the standard TypeSpec construct and the one `@typespec/openapi3` can
-     * see, so it is the only source. There was a second — `@loose`, a decorator of ours, invisible to
-     * the document — and it is gone: a model that accepted unknown properties while the published
+     * see, so it is the only source. There was a second - `@loose`, a decorator of ours, invisible to
+     * the document - and it is gone: a model that accepted unknown properties while the published
      * schema said otherwise is a runtime disagreeing with its own contract.
      *
      * An indexer over something other than `unknown` is a typed catchall, where `.loose()` would drop
@@ -648,29 +662,45 @@ function modelToZod(program, model) {
      */
     const strict = suffix === "" && isSealed(model) ? ".strict()" : "";
     /**
-     * ⚠️ **HTTP metadata is not payload.** A `@header` or `@statusCode` property describes the envelope,
-     * so it never appears in the body — `@typespec/openapi3` strips it from the schema it emits, and a
+     * **HTTP metadata is not payload.** A `@header` or `@statusCode` property describes the envelope,
+     * so it never appears in the body - `@typespec/openapi3` strips it from the schema it emits, and a
      * validator that kept it would demand a field the wire never carries.
      *
      * Found the moment a model carried its own content-type: RFC 9457 puts
      * `@header("content-type") contentType: "application/problem+json"` on the problem model, the
      * document correctly described a body without it, and this emitter produced
-     * `contentType: z.literal(…)` as a required member. Two artefacts from one source, disagreeing
-     * about the shape of a body — the exact contradiction ADR 0005 exists to make impossible.
+     * `contentType: z.literal(...)` as a required member. Two artefacts from one source, disagreeing
+     * about the shape of a body - the exact contradiction ADR 0005 exists to make impossible.
      */
     /**
-     * ⚠️ **A property that refers back into an unfinished declaration is emitted as a GETTER.**
+     * **A property that refers back into an unfinished declaration is emitted as a GETTER.**
      *
      * `model InnerModel { children?: InnerModel[] }` is a plain recursive tree, and openapi3 publishes
      * it as a self-`$ref`. Emitting `children: z.array(innerModelSchema)` reads the `const` inside its
      * own initialiser, so the module throws on import; deferring the reference behind a getter is the
      * idiom Zod documents for exactly this, and it is the only one that keeps `z.infer` inferring the
      * recursive type rather than collapsing to `any`. `z.lazy(() => innerModelSchema)` runs correctly
-     * but does not typecheck — measured: `TS7022`, "implicitly has type 'any' because it does not have
+     * but does not typecheck - measured: `TS7022`, "implicitly has type 'any' because it does not have
      * a type annotation and is referenced directly or indirectly in its own initializer".
      */
     const members = declared
         .filter((property) => isPayloadProperty(program, property))
+        /**
+         * **A `never` property is DROPPED, exactly as the document drops it.** `model N { value:
+         * never; other: string }` is published by `@typespec/openapi3` as `{other}` with
+         * `required: ["other"]` - `value` is absent entirely, because a property that can hold no value
+         * is not part of the payload.
+         *
+         * This emitter kept it and wrote `value: z.never()`, which made the model unsatisfiable: measured,
+         * `{"other":"x"}` - the exact body the document describes - was REJECTED with "expected never,
+         * received undefined". So the validator generated from a document rejected every request that
+         * document calls valid, which is the divergence class this package exists to prevent.
+         *
+         * Dropping it makes the two artefacts agree and leaves nothing to refuse. `never` in a position
+         * that is not a property - a body, a variant - is still refused by `typeToZodBody`, because there
+         * it is not something the document quietly omits.
+         */
+        .filter((property) => !isNeverType(property.type))
         .map((property) => {
         const key = propertyKey(program, property);
         const { value, deferred } = captureBackEdges(() => propertyToZod(program, property));
@@ -683,46 +713,45 @@ function modelToZod(program, model) {
     /**
      * A model-level `@refine` goes through the same path as every other constraint, so the predicate's
      * import is recorded exactly once, in one place. Handling it separately here is what dropped the
-     * import the first time — the emitted schema referenced a name it never imported, and only the
+     * import the first time - the emitted schema referenced a name it never imported, and only the
      * compile check in `test/emit.test.ts` noticed.
      *
      * `.refine()` returns an effect rather than an object, so `applyConstraints` appending it after
      * `.loose()` is also the only order that works.
      */
     /**
-     * ⚠️ **A deferred property forces the CONSTRUCTOR form of the object.**
+     * **A deferred property forces the CONSTRUCTOR form of the object.**
      *
      * Measured on Zod 4.4.3: `.strict()`, `.loose()` and `.catchall()` all read `shape` eagerly, so
      * each one fires the getter during module initialisation and throws `Cannot access 'X' before
-     * initialization` — the very thing the getter exists to avoid. `z.strictObject` and
+     * initialization` - the very thing the getter exists to avoid. `z.strictObject` and
      * `z.looseObject` take the same shape without reading it. The suffix form stays everywhere else,
      * so a model that does not recurse emits exactly the text it emitted before.
      *
-     * A **typed** catchall has no constructor form to move to, so there is nowhere safe to put the
-     * getter and the cycle is genuinely unrepresentable here — that is a refusal, and it is named.
+     * **A TYPED catchall has no constructor form, and that used to be a refusal.** There is nowhere
+     * safe to put the getter - `.catchall()` reads `shape` eagerly - so the cycle was reported as
+     * `circular-model`. `z.lazy()` is the place to put it: wrapping the whole expression defers the
+     * getter past module initialisation, and by the time the schema is forced every declaration exists.
+     * Measured on 4.4.3: `z.lazy(() => z.object({ get kid() {...} }).catchall(z.number()))` parses a
+     * nested value and still applies the catchall.
      */
     const lazily = members.some((member) => member.deferred);
     const constructible = suffix === "" || suffix === ".loose()";
-    if (lazily && !constructible) {
-        reportDiagnostic(program, {
-            code: "circular-model",
-            target: model,
-            format: { name: model.name === "" ? "an anonymous model" : model.name },
-        });
-    }
     const shape = entries.length === 0 ? "{}" : `{\n${entries.join("\n")}\n}`;
-    const body = lazily && constructible
-        ? `${suffix === ".loose()" ? "z.looseObject" : strict === ".strict()" ? "z.strictObject" : "z.object"}(${shape})`
+    const body = lazily
+        ? constructible
+            ? `${suffix === ".loose()" ? "z.looseObject" : strict === ".strict()" ? "z.strictObject" : "z.object"}(${shape})`
+            : `z.lazy(() => z.object(${shape})${suffix}${strict})`
         : `z.object(${shape})${suffix}${strict}`;
     return applyConstraints(program, body, model);
 }
 /**
- * A name as an object key — quoted when it is not a legal JavaScript identifier.
+ * A name as an object key - quoted when it is not a legal JavaScript identifier.
  *
- * ⚠️ **A TypeSpec property can be named anything**, and the corpus proves it: `parameters/spread`
+ * **A TypeSpec property can be named anything**, and the corpus proves it: `parameters/spread`
  * declares `` `x-ms-test-header`: string ``. A parameter walk assumed the property name was always
- * safe — its docblock even argued that using the property name rather than the wire name was what
- * avoided this — and emitted `x-ms-test-header: z.string()`, a file that does not parse.
+ * safe - its docblock even argued that using the property name rather than the wire name was what
+ * avoided this - and emitted `x-ms-test-header: z.string()`, a file that does not parse.
  *
  * Exported so there is one answer to this question. There were two sites and only one of them knew.
  */
@@ -732,24 +761,24 @@ export function objectKey(name) {
 /**
  * The name a property carries **on the wire**, which is not always the name the spec gave it.
  *
- * ⚠️ **`@encodedName` is a first-party decorator, and a decorator is a declaration rather than a
+ * **`@encodedName` is a first-party decorator, and a decorator is a declaration rather than a
  * behaviour.** It attaches metadata to the type graph and does nothing on its own; every emitter has
- * to go and ask. `@typespec/openapi3` asks — `resolveEncodedName` at `schema-emitter.js:214` — so the
+ * to go and ask. `@typespec/openapi3` asks - `resolveEncodedName` at `schema-emitter.js:214` - so the
  * document publishes the wire name. This emitter did not, so the validator was keyed on the TypeSpec
  * name and a request carrying exactly what the contract required failed twice over: the declared
  * property was missing, and the one actually sent was an unrecognised key a sealed model rejects.
  *
  * The corpus scenario for this is called "Testing that you send the right JSON name on the wire",
- * and it sat in the green column throughout — compiling cleanly while emitting the wrong key.
+ * and it sat in the green column throughout - compiling cleanly while emitting the wrong key.
  *
  * **The domain therefore sees the wire name too**, because `types.ts` resolves it identically. A
  * validator that renamed on the way through would be a transform, which JSON Schema cannot express
- * and no document could state — the same reason `@trimmed` was removed.
+ * and no document could state - the same reason `@trimmed` was removed.
  */
 function propertyKey(program, property) {
     return objectKey(rawPropertyKey(program, property));
 }
-/** The same wire name, unquoted — for a vocabulary tuple, where the value is data rather than code. */
+/** The same wire name, unquoted - for a vocabulary tuple, where the value is data rather than code. */
 function rawPropertyKey(program, property) {
     return resolveEncodedName(program, property, JSON_MEDIA_TYPE);
 }
@@ -758,13 +787,13 @@ function rawPropertyKey(program, property) {
  *
  * Fixed rather than threaded: everything this emitter produces validates a JSON body, and
  * `@encodedName` is per-media-type. A surface serving XML as well would need this carried from the
- * operation's content type, as openapi3 does — and would need far more than a name to be correct.
+ * operation's content type, as openapi3 does - and would need far more than a name to be correct.
  */
 const JSON_MEDIA_TYPE = "application/json";
 /**
  * The type a value takes **on the wire**, which `@encode` can make different from its declared one.
  *
- * ⚠️ **A first-party decorator, and a decorator is a declaration rather than a behaviour** — every
+ * **A first-party decorator, and a decorator is a declaration rather than a behaviour** - every
  * emitter has to go and ask. `@typespec/openapi3` asks, so the document publishes the encoded type;
  * this emitter did not, and validated the DECLARED one. Measured across the corpus, 30 properties
  * where the two disagreed, and each disagreement rejects a body the contract calls valid:
@@ -774,10 +803,10 @@ const JSON_MEDIA_TYPE = "application/json";
  *   `@encode(string) int32`              document `string`   we emitted a number
  *   `@encode(unixTimestamp) utcDateTime` document `integer`  we emitted a string
  *
- * Exactly the shape of the `@encodedName` defect, found by exactly the same kind of arm — there, the
+ * Exactly the shape of the `@encodedName` defect, found by exactly the same kind of arm - there, the
  * key a property goes by; here, the type it goes as.
  *
- * ⚠️ **An array encoding on a QUERY parameter is a style, not a type change — and this docblock used
+ * **An array encoding on a QUERY parameter is a style, not a type change - and this docblock used
  * to say the opposite.** It claimed the array encodings needed no special case "because a
  * comma-delimited list IS a string on the wire". True of the wire, and the wrong conclusion: the
  * document keeps `type: array` and publishes `style: pipeDelimited` beside it, because the parameter
@@ -792,8 +821,8 @@ const JSON_MEDIA_TYPE = "application/json";
  * }
  * ```
  *
- * Everywhere else the encoding really does change the type — `@encode(unixTimestamp) utcDateTime` is
- * an integer — so this narrows to exactly the case the reference implementation narrows to. The
+ * Everywhere else the encoding really does change the type - `@encode(unixTimestamp) utcDateTime` is
+ * an integer - so this narrows to exactly the case the reference implementation narrows to. The
  * flattening is undone at the parameter, by {@link COLLECTION_DELIMITERS}.
  */
 const PARAMETER_STYLE_ENCODINGS = new Set([
@@ -815,9 +844,9 @@ function encodedTypeOf(program, target) {
 }
 export function propertyToZod(program, property) {
     /**
-     * ⚠️ **Constraints go INSIDE `.nullable()`, not after it.**
+     * **Constraints go INSIDE `.nullable()`, not after it.**
      *
-     * `z.string().nullable().min(1)` does not compile — `.min` is not on `ZodNullable` — so a property
+     * `z.string().nullable().min(1)` does not compile - `.min` is not on `ZodNullable` - so a property
      * typed `string | null` with `@minLength(1)` has to emit `z.string().min(1).nullable()`. The
      * nullability is peeled off here, the constraints applied to what is underneath, and the wrapper
      * put back. Found by a consumer's own typecheck on a nullable-and-constrained property.
@@ -826,7 +855,7 @@ export function propertyToZod(program, property) {
      * to the value.
      */
     const nullable = nullableInnerOf(property.type);
-    // `@encode` on the property wins over its declared type — see `encodedTypeOf`. The nullable
+    // `@encode` on the property wins over its declared type - see `encodedTypeOf`. The nullable
     // wrapper is kept: `@encode` changes what the value IS, not whether it may be absent.
     const encoded = encodedTypeOf(program, property);
     const declared = encoded ?? nullable ?? property.type;
@@ -834,70 +863,95 @@ export function propertyToZod(program, property) {
         ? applyConstraints(program, typeToZod(program, declared), property)
         : `${applyConstraints(program, typeToZod(program, declared), property)}.nullable()`;
     /**
-     * A TypeSpec default (`basis: string = "s1159"`) becomes `.default(…)`, which in Zod also makes
+     * A TypeSpec default (`basis: string = "s1159"`) becomes `.default(...)`, which in Zod also makes
      * the field optional on the way in. Dropping it turned an optional field with a fallback into a
-     * required one — callers omitting it would start getting a 400 for a request that used to work.
+     * required one - callers omitting it would start getting a 400 for a request that used to work.
      */
     const defaulted = defaultOf(program, property);
     if (defaulted !== undefined)
         return `${base}.default(${defaulted})`;
     /**
-     * ⚠️ **Optionality is a function of the position too, not only of the `?` in the spec.**
+     * **Optionality is a function of the position too, not only of the `?` in the spec.**
      *
      * TypeSpec's PATCH semantics make a property optional in an update request even where the model
-     * declares it required — an update sends the fields it is changing. The document says so
+     * declares it required - an update sends the fields it is changing. The document says so
      * (`VisibilityModelUpdate` requires nothing) and a validator that still demanded the property
      * would reject every partial update the contract invites. `metadataInfo.isOptional` is the same
      * predicate `@typespec/openapi3` uses to decide the `required` list.
      */
     return property.optional || isOptionalAt(program, property) ? `${base}.optional()` : base;
 }
-/** A property's declared default, as a JS literal, or `undefined` when it has none. */
-function defaultOf(program, property) {
-    const value = property.defaultValue;
-    if (value === undefined)
-        return undefined;
+/**
+ * A default value as a JS literal, or `undefined` where this emitter cannot render one.
+ *
+ * **Composite defaults used to be REFUSED, and the refusal was wrong on the emitter's own
+ * governing rule.** `#["a", "b"]` and `#{ x: 1 }` were reported as `unsupported-default` with the
+ * reason "a populated literal default would need each element rendered, and no schema here has one".
+ * That was a statement about this function rather than about what can be represented: `.default()`
+ * takes any JS value, and `@typespec/openapi3` publishes these exactly -
+ * `default: ["a","b"]`, `default: {"x":1,"label":"hi"}`, and nested arrays too, measured from one
+ * compile of a spec carrying all three. So the document could say it, Zod could enforce it, and only
+ * this emitter refused - which is the same spec being representable by one emitter and not the other,
+ * the one thing a differential between them cannot tolerate.
+ *
+ * **The refusal also emitted `.default(z.never())`**, because `UNREPRESENTABLE` is a schema
+ * expression and this position wants a VALUE. Had the diagnostic ever been downgraded to a warning,
+ * that would have compiled and set every such default to a Zod object.
+ *
+ * A value is pure data - strings, numbers, booleans, null, and arrays and objects of those - so it
+ * renders as JSON. Anything else stays a refusal, and `ScalarValue` is the live case: a default like
+ * `utcDateTime.fromISO(...)` is a constructor call rather than a literal.
+ */
+function renderValue(value) {
     if (value.valueKind === "StringValue")
         return JSON.stringify(value.value);
     if (value.valueKind === "NumericValue")
         return String(value.value.asNumber());
     if (value.valueKind === "BooleanValue")
         return String(value.value);
+    if (value.valueKind === "NullValue")
+        return "null";
     if (value.valueKind === "EnumValue") {
         const member = value.value;
         return JSON.stringify(member.value ?? member.name);
     }
-    // `attendees?: string[] = #[]` — an empty-collection default, emitted as `.default([])`.
-    // Only empty ones: a populated literal default would need each element rendered, and no schema here
-    // has one, so it stays unsupported rather than half-implemented.
     if (value.valueKind === "ArrayValue") {
-        const values = value.values ?? [];
-        if (values.length === 0)
-            return "[]";
-        reportDiagnostic(program, {
-            code: "unsupported-default",
-            target: property,
-            format: { why: "a non-empty array" },
-        });
-        return UNREPRESENTABLE;
+        const rendered = value.values.map(renderValue);
+        // One unrenderable element makes the whole literal unrenderable - a partial array would be a
+        // different default from the one the spec declares, which is worse than refusing.
+        return rendered.some((entry) => entry === undefined) ? undefined : `[${rendered.join(", ")}]`;
     }
     if (value.valueKind === "ObjectValue") {
-        const properties = value.properties;
-        if (properties === undefined || properties.size === 0)
-            return "{}";
-        reportDiagnostic(program, {
-            code: "unsupported-default",
-            target: property,
-            format: { why: "a non-empty object" },
-        });
-        return UNREPRESENTABLE;
+        const entries = [];
+        for (const [name, descriptor] of value.properties) {
+            const rendered = renderValue(descriptor.value);
+            if (rendered === undefined)
+                return undefined;
+            entries.push(`${JSON.stringify(name)}: ${rendered}`);
+        }
+        return `{${entries.join(", ")}}`;
     }
+    return undefined;
+}
+/** A property's declared default, as a JS literal, or `undefined` when it has none. */
+function defaultOf(program, property) {
+    const value = property.defaultValue;
+    if (value === undefined)
+        return undefined;
+    const rendered = renderValue(value);
+    if (rendered !== undefined)
+        return rendered;
     reportDiagnostic(program, {
         code: "unsupported-default",
         target: property,
         format: { why: `kind "${value.valueKind}"` },
     });
-    return UNREPRESENTABLE;
+    /**
+     * **No `.default(...)` at all, rather than a default this emitter invented.** Returning
+     * `UNREPRESENTABLE` here put a schema expression where a value belongs. The property keeps its
+     * declared shape and loses only the fallback, which the diagnostic names.
+     */
+    return undefined;
 }
 /** The non-null half of a two-variant `T | null` union, or `undefined` if it is not one. */
 function nullableInnerOf(type) {
@@ -931,8 +985,8 @@ export function withRefResolver(resolver, run) {
 /**
  * How many references the current walk has made **back into a declaration still being rendered**.
  *
- * A recursive model is an ordinary construct — `@typespec/openapi3` emits a self-`$ref` for
- * `model InnerModel { children?: InnerModel[] }` and the document is valid — so the reference has to
+ * A recursive model is an ordinary construct - `@typespec/openapi3` emits a self-`$ref` for
+ * `model InnerModel { children?: InnerModel[] }` and the document is valid - so the reference has to
  * be emitted, not refused. But a `const` cannot read itself while it is being initialised, so the
  * reference must be made **lazy**, and only the enclosing object knows where to put the getter that
  * does it. The registry counts the back edges; {@link captureBackEdges} is how an object claims them.
@@ -945,8 +999,8 @@ export function noteBackEdge() {
 /**
  * Render `run()`, reporting whether it reached back into a declaration still being rendered.
  *
- * ⚠️ **The count is restored on the way out, and that is the point.** A caller that wraps the
- * reference in a getter has *settled* the back edge — the reference is now lazy and the enclosing
+ * **The count is restored on the way out, and that is the point.** A caller that wraps the
+ * reference in a getter has *settled* the back edge - the reference is now lazy and the enclosing
  * object is safe. Letting it propagate would make every ancestor defer as well, and would make the
  * registry report a cycle that has already been dealt with.
  */
@@ -968,7 +1022,7 @@ export function typeToZod(program, type) {
  *
  * The registry renders a declaration's *body* with this: asking the resolver first would hand back
  * the identifier the declaration is about to bind, emitting `const xSchema = xSchema`. Nested
- * occurrences still go through {@link typeToZod} and do resolve — which is what makes a recursive
+ * occurrences still go through {@link typeToZod} and do resolve - which is what makes a recursive
  * model reference itself instead of inlining itself forever.
  */
 export function typeToZodBody(program, type) {
@@ -990,13 +1044,13 @@ export function typeToZodBody(program, type) {
         case "EnumMember":
             return `z.literal(${JSON.stringify(type.value ?? type.name)})`;
         /**
-         * ⚠️ **A named union VARIANT is a type you can refer to, and it is not the union.**
+         * **A named union VARIANT is a type you can refer to, and it is not the union.**
          *
          * `union DogKind { string, Golden: "golden" }` is TypeSpec's extensible-enum idiom, and
          * `kind: DogKind.Golden` resolves to the variant rather than to its value. Unreachable until
          * discriminated subtypes started being declared, at which point the whole
          * `type/model/inheritance/enum-discriminator` scenario stopped compiling with
-         * "no rule for this kind" — a dormant seam, not a new defect.
+         * "no rule for this kind" - a dormant seam, not a new defect.
          */
         case "UnionVariant":
             return typeToZod(program, type.type);