typespec-http-zod 0.1.0 → 0.3.0

package/dist/src/registry.js

@@ -1,36 +1,11 @@
 import { getVisibilitySuffix, Visibility } from "@typespec/http";
-import { reportDiagnostic } from "./lib.js";
 import { propertyToTs, typeToTsBody, withTsRefResolver } from "./types.js";
 import { captureBackEdges, currentVisibility, isTransformedBy, noteBackEdge, propertyToZod, typeToZodBody, withRefResolver, withSyntheticDeclarations, } from "./zod.js";
-/**
- * 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 that reaches a declaration through nothing that can defer it.
- *
- * ⚠️ **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`). This placeholder is only for a cycle with no property on its path: a named **union**
- * whose variant refers back to a model that is still being rendered has nowhere to hang a getter, so
- * the reference cannot be deferred and the declaration would read itself while initialising.
- *
- * Reported rather than thrown, so the walk names every such cycle instead of dying inside the first.
- */
-const CYCLE_PLACEHOLDER_SCHEMA = "z.never()";
-function reportCycle(program, type, name) {
-    reportDiagnostic(program, { code: "circular-model", target: type, format: { name } });
-}
 /**
  * The name an ANONYMOUS payload model inherits from the single model it spreads.
  *
- * ⚠️ **`@typespec/http` hands back a synthesised model for a body whose declaration carried
- * metadata**, and it has no name — so `@error model InvalidAuth { @statusCode _: 403; error: string }`
+ * **`@typespec/http` hands back a synthesised model for a body whose declaration carried
+ * metadata**, and it has no name - so `@error model InvalidAuth { @statusCode _: 403; error: string }`
  * reached the registry as `{error}` with `name: ""`, was inlined at its use site, and produced **no
  * validator at all** for a component the document publishes as `InvalidAuth`. Four authentication
  * scenarios, each with an unvalidated 403.
@@ -39,8 +14,8 @@ function reportCycle(program, type, name) {
  * itself, which is why its component keeps the original name. This recovers the same name from
  * `sourceModels`, so both artefacts call the shape the same thing.
  *
- * ⚠️ **Only a PURE spread of one named model.** `{...A, extra: string}` is a different shape and must
- * not claim `A`'s name — so every property has to come from the source. Metadata-stripping removes
+ * **Only a PURE spread of one named model.** `{...A, extra: string}` is a different shape and must
+ * not claim `A`'s name - so every property has to come from the source. Metadata-stripping removes
  * properties and never adds them, which is exactly the asymmetry this tests for. A collision would be
  * caught by the differential's `component-name-collision` arm regardless.
  */
@@ -48,11 +23,11 @@ function spreadSourceOf(type, seen = new Set(),
 /**
  * The properties the ORIGINAL type has, carried down the chain rather than re-derived.
  *
- * ⚠️ **Re-deriving them at each link is what blocked `Alias.InnerModel`.** The intermediate model
+ * **Re-deriving them at each link is what blocked `Alias.InnerModel`.** The intermediate model
  * an operation builds holds the spread body's properties AND the operation's own `@path` and
  * `@header` parameters, so checking THAT set against the named ancestor fails on properties the
  * body never had. The question is whether every property of the shape being named comes from the
- * ancestor — `{name}` does — not whether some intermediate did.
+ * ancestor - `{name}` does - not whether some intermediate did.
  *
  * The guard is unchanged in what it refuses: `{...A, extra}` still fails, because `extra` is in
  * the original set and not in `A`.
@@ -74,9 +49,9 @@ required = [...type.properties.keys()]) {
             return undefined;
     }
     /**
-     * ⚠️ **Follow the chain through ANONYMOUS links.** TypeSpec puts an unnamed model between an
+     * **Follow the chain through ANONYMOUS links.** TypeSpec puts an unnamed model between an
      * operation's parameter model and the model that was spread into it, so stopping at the first
-     * source finds `""` and gives up — measured: the bodies for `Alias.InnerModel` and
+     * source finds `""` and gives up - measured: the bodies for `Alias.InnerModel` and
      * `Model.CompositeRequestMix` both reported `sources: [{ usage: "spread", name: "" }]` while the
      * document published both as components, and the one case that already worked
      * (`Model.BodyParameter`) was the one whose source happened to be named directly.
@@ -88,14 +63,14 @@ required = [...type.properties.keys()]) {
     return model.name === "" ? spreadSourceOf(model, new Set([...seen, type]), required) : model;
 }
 const spreadSourceName = (type) => spreadSourceOf(type)?.name;
-/** A type earns a name when the spec gave it one — anonymous shapes stay inline where they are used. */
+/** A type earns a name when the spec gave it one - anonymous shapes stay inline where they are used. */
 function declaredNameOf(type) {
     if (type.kind === "Enum")
         return type.name;
     /**
      * A named union earns a declaration too.
      *
-     * Without this a union request body is inlined at its use site, so it exports no type — and
+     * Without this a union request body is inlined at its use site, so it exports no type - and
      * `backend/contract.ts` and the wire assertions both pair a model with a schema **by name**. A
      * cross-field rule modelled as a discriminated union (which is how `@refine` is being replaced)
      * would silently stop being checked at the boundary.
@@ -110,10 +85,10 @@ function declaredNameOf(type) {
     if (type.name === "")
         return spreadSourceName(type);
     /**
-     * ⚠️ **A template INSTANTIATION carries the template's name, and it is not a declaration.**
+     * **A template INSTANTIATION carries the template's name, and it is not a declaration.**
      *
      * `PublicSuccess<PublicCompanyDetail>` and `PublicSuccess<PublicOfficers>` are both called
-     * `PublicSuccess`, so naming them would export eleven consts called `publicSuccessSchema` — the
+     * `PublicSuccess`, so naming them would export eleven consts called `publicSuccessSchema` - the
      * file does not compile, and if it did, one shape would validate every response. `@typespec/openapi3`
      * inlines instantiations for the same reason (the public document has no `PublicSuccess*`
      * component), so both artefacts agree about what has a name and what does not.
@@ -128,11 +103,11 @@ const lowerFirst = (value) => value.charAt(0).toLowerCase() + value.slice(1);
 /**
  * One model can need MORE THAN ONE declaration.
  *
- * ⚠️ **Keyed on `(type, visibility)`, because a model is not one shape.** `@visibility` and HTTP
+ * **Keyed on `(type, visibility)`, because a model is not one shape.** `@visibility` and HTTP
  * metadata both mean the same declaration projects differently by position: `@typespec/openapi3`
  * emits `VisibilityModel` and `VisibilityModelCreate` as separate components for exactly this
  * reason. Keyed on the type alone, whichever position was walked first won and every other position
- * silently got its shape — measured on the corpus, one strict model carrying all six lifecycle
+ * silently got its shape - measured on the corpus, one strict model carrying all six lifecycle
  * properties, so a create request was required to send read-only fields.
  *
  * The suffix rule is openapi3's: canonical (`Read`) keeps the bare name, and another visibility only
@@ -141,10 +116,10 @@ const lowerFirst = (value) => value.charAt(0).toLowerCase() + value.slice(1);
  */
 function keyFor(type, visibility) {
     /**
-     * ⚠️ **Keyed on the SPREAD SOURCE where there is one, or one component gets two declarations.**
+     * **Keyed on the SPREAD SOURCE where there is one, or one component gets two declarations.**
      *
      * `@typespec/http` synthesises a fresh anonymous model per position, so two operations taking the
-     * same body produce two distinct types that both resolve to the name `BodyModel` — and
+     * same body produce two distinct types that both resolve to the name `BodyModel` - and
      * `parameters/body-optionality` emitted `export const bodyModelSchema` twice, a file that does not
      * parse. The document has exactly one `BodyModel` component; collapsing onto the source is what
      * makes the two artefacts agree about how many things there are.
@@ -173,13 +148,15 @@ export class SchemaRegistry {
     #program;
     #declarations = new Map();
     #order = [];
-    /** Key → the identifier it is *going* to bind, so a back edge can name a declaration in flight. */
+    /** Key -> the identifier it is *going* to bind, so a back edge can name a declaration in flight. */
     #inProgress = new Map();
+    /** Keys on a cycle - every one needs a structural type rather than a `z.infer` alias. */
+    #cyclic = new Set();
     constructor(program) {
         this.#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.
      */
@@ -188,7 +165,7 @@ export class SchemaRegistry {
         if (bare === undefined)
             return this.#inline(type);
         /**
-         * ⚠️ **A type not reshaped at this visibility IS the canonical declaration — not a copy of it.**
+         * **A type not reshaped at this visibility IS the canonical declaration - not a copy of it.**
          *
          * Keying on the requested visibility while only suffixing transformed types produced two cache
          * entries sharing one identifier, and the emitted file stopped parsing:
@@ -207,15 +184,24 @@ export class SchemaRegistry {
         if (existing !== undefined)
             return existing.identifier;
         /**
-         * ⚠️ **A declaration already in flight is REFERENCED, not re-entered.**
+         * **A declaration already in flight is REFERENCED, not re-entered.**
          *
          * Returning the identifier is what turns a recursive model into the self-`$ref` the document
-         * publishes. The back edge is noted so the enclosing object knows to defer it behind a getter —
+         * publishes. The back edge is noted so the enclosing object knows to defer it behind a getter -
          * and if nothing does, {@link captureBackEdges} below still sees it and the cycle is named.
          */
         const pending = this.#inProgress.get(key);
         if (pending !== undefined) {
             noteBackEdge();
+            /**
+             * **Every declaration currently in flight is ON this cycle**, and all of them need a
+             * structural type - not only the one that ends up deferred. `#inProgress` is exactly the path
+             * from the cycle's entry point down to here, so recording it wholesale is both correct and
+             * cheap. Recording only the deferred declaration leaves the others as `z.infer` aliases and
+             * closes the loop again at the type level - `TS2456`, measured.
+             */
+            for (const inFlight of this.#inProgress.keys())
+                this.#cyclic.add(inFlight);
             return pending;
         }
         const name = `${bare}${at === Visibility.Read ? "" : getVisibilitySuffix(at, Visibility.Read)}`;
@@ -225,16 +211,17 @@ export class SchemaRegistry {
         this.#inProgress.delete(key);
         /**
          * A back edge that survived the whole body reached this declaration by a path with no object
-         * property on it — a named union variant, or a dictionary value — so nothing could make it
-         * lazy and the emitted `const` would read itself while initialising.
+         * property on it - a named union variant, or a dictionary value - so nothing could make it lazy
+         * and the emitted `const` would read itself while initialising. `z.lazy()` defers the whole body
+         * instead, which is the only place left to put the deferral once no property can hold it.
          */
-        if (rendered.deferred)
-            reportCycle(this.#program, type, bare);
-        const source = rendered.deferred ? CYCLE_PLACEHOLDER_SCHEMA : rendered.value;
+        const source = rendered.deferred ? `z.lazy(() => ${rendered.value})` : rendered.value;
         const declaration = {
             identifier,
             typeName: name,
             source,
+            ...(this.#cyclic.has(key) ? { structural: this.#structuralBodyOf(type) } : {}),
+            ...(rendered.deferred ? { annotated: true } : {}),
         };
         this.#declarations.set(key, declaration);
         this.#order.push(declaration);
@@ -244,18 +231,18 @@ export class SchemaRegistry {
     /**
      * Declare the BASE CHAIN a component's own declaration implies.
      *
-     * ⚠️ **Reachability from an operation is not the same set the document publishes.** openapi3 emits
+     * **Reachability from an operation is not the same set the document publishes.** openapi3 emits
      * a component for every base in an `allOf` chain whether or not an operation names it, so `Pet` and
-     * `Cat` — bases of a `Siamese` that IS named — had no validator at all while the document declared
+     * `Cat` - bases of a `Siamese` that IS named - had no validator at all while the document declared
      * them.
      *
-     * ⚠️ **Subtypes are deliberately NOT walked here, because nothing would be walking them.** A
+     * **Subtypes are deliberately NOT walked here, because nothing would be walking them.** A
      * discriminated base renders as `z.discriminatedUnion` over its subtypes, and rendering that
      * already asks the registry for each one. A loop here looked load-bearing and was measured not to
      * be: removing it left all 23 polymorphism and differential arms green.
      *
-     * ⚠️ **Wrapped in {@link captureBackEdges} and the result discarded.** This call can land on a
-     * declaration still in flight — a subtype's base is, by construction, the model that asked for it —
+     * **Wrapped in {@link captureBackEdges} and the result discarded.** This call can land on a
+     * declaration still in flight - a subtype's base is, by construction, the model that asked for it -
      * and that is not a reference in anyone's emitted expression. Letting the back edge escape would
      * have the enclosing declaration report a cycle it does not have and emit `z.never()`.
      */
@@ -268,7 +255,7 @@ export 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.
      */
@@ -282,14 +269,14 @@ export 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, build) {
         return this.#declareSynthetic(name, build);
@@ -310,11 +297,28 @@ export class SchemaRegistry {
         this.#order.push(declaration);
         return identifier;
     }
+    /**
+     * The structural TypeScript body for a type on a cycle.
+     *
+     * **The same walk `requests.gen.ts` uses, resolving named types to their NAMES rather than
+     * declaring them.** A cyclic declaration cannot take its type from `z.infer<typeof ...>` - that is
+     * the loop - so it needs a type written out. Every name this body references is declared in the
+     * same file either structurally (if it is on the cycle too) or as the ordinary `z.infer` alias (if
+     * it is not), so nothing further has to be emitted for it.
+     *
+     * Sharing `types.ts` rather than writing a second TypeScript renderer is what keeps the annotation
+     * agreeing with the validator: those two walks are already paired against each other by
+     * `wire-contract.gen.ts`, and a third spelling of "what this shape is" would be a third thing to
+     * drift.
+     */
+    #structuralBodyOf(type) {
+        return withTsRefResolver((candidate) => declaredNameOf(candidate), () => typeToTsBody(this.#program, type));
+    }
     /**
      * Render `type` without consulting its own declaration, but letting nested types use theirs.
      *
-     * ⚠️ **The "not itself" rule belongs to the TOP of the walk, not to every depth.** It used to live
-     * in the resolver, which is asked at every node — so a model reaching itself through a property
+     * **The "not itself" rule belongs to the TOP of the walk, not to every depth.** It used to live
+     * in the resolver, which is asked at every node - so a model reaching itself through a property
      * was inlined again, and again: `type/array` and `type/dictionary` in the conformance corpus both
      * declare `children?: InnerModel[]` and both died with
      * `RangeError: Maximum call stack size exceeded`. Skipping the resolver once, here, is what makes
@@ -336,7 +340,7 @@ export class SchemaRegistry {
  * 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.
  */
@@ -356,9 +360,9 @@ export class TypeRegistry {
         if (existing !== undefined)
             return existing.name;
         /**
-         * ⚠️ **No laziness is needed on this side, and no refusal either.** A TypeScript `interface`
-         * may refer to itself — `interface InnerModel { children?: InnerModel[] }` is the ordinary way
-         * to write a tree — so the name alone is the whole answer. The Zod registry has to defer the
+         * **No laziness is needed on this side, and no refusal either.** A TypeScript `interface`
+         * may refer to itself - `interface InnerModel { children?: InnerModel[] }` is the ordinary way
+         * to write a tree - so the name alone is the whole answer. The Zod registry has to defer the
          * same edge behind a getter only because a `const` cannot read itself while initialising.
          */
         if (this.#inProgress.has(type))
@@ -370,21 +374,21 @@ export class TypeRegistry {
             name,
             /**
              * Only a plain object literal can be an `interface`. A permissive response is
-             * `{ …pinned } & Record<string, unknown>`, and `export interface X { … } & …` does not parse —
+             * `{ ...pinned } & Record<string, unknown>`, and `export interface X { ... } & ...` does not parse -
              * so an intersection is emitted as a type alias instead.
              */
             isObject: source.startsWith("{") && !source.includes("} & "),
             /**
-             * ⚠️ **A vocabulary alias is NOT exported.**
+             * **A vocabulary alias is NOT exported.**
              *
              * It restates a vocabulary enum's members from the spec, and the vocabularies artefact already
-             * exports the same 27 names derived from the runtime tuples — exporting both collides on
+             * exports the same 27 names derived from the runtime tuples - exporting both collides on
              * every one of them the moment the package re-exports this file.
              *
              * Restating rather than referencing is deliberate, and it is what makes the drift visible:
              * the emitted **Zod** defers to the runtime tuple while this type says what the spec
              * *declares*, so the two disagreeing is exactly the lie the document is telling. Referencing
-             * the contracts type instead would make every assertion pass and publish the lie unchecked —
+             * the contracts type instead would make every assertion pass and publish the lie unchecked -
              * which is how `FilingState` came to advertise a `failed` state that cannot occur while
              * omitting the generated one a consumer actually uses.
              */
@@ -396,16 +400,17 @@ export class TypeRegistry {
         return declaration.name;
     }
     /**
-     * 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) {
+    /** `wireName` names an HTTP parameter as the wire does - see {@link propertyToTs}. */
+    expressionForProperty(property, wireName) {
         return withTsRefResolver((candidate) => {
             if (declaredNameOf(candidate) === undefined)
                 return undefined;
             return this.expressionFor(candidate);
-        }, () => propertyToTs(this.#program, property));
+        }, () => propertyToTs(this.#program, property, wireName));
     }
     #inline(type) {
         return withTsRefResolver((candidate) => {

package/dist/src/runtime.d.ts

@@ -1,10 +1,10 @@
 import type { ZodType } from "zod";
 /**
- * **What generated code imports at run time — and the only thing this package puts in its output.**
+ * **What generated code imports at run time - and the only thing this package puts in its output.**
  *
- * ⚠️ **Kept deliberately tiny, and deliberately free of every TypeSpec import.** The main entry point
+ * **Kept deliberately tiny, and deliberately free of every TypeSpec import.** The main entry point
  * is an emitter: it pulls in `@typespec/compiler` and exists at build time. This module is what an
- * *application* touches — an Express or Fastify service reading the arms this emitter wrote — and
+ * *application* touches - an Express or Fastify service reading the arms this emitter wrote - and
  * making it reach the compiler would put a build-time dependency into a server's runtime graph for
  * the sake of two declarations. `test/packaging.test.ts` asserts the separation rather than trusting
  * it.
@@ -17,41 +17,41 @@ import type { ZodType } from "zod";
  * One status an operation may answer with, and the schema the document publishes for it.
  *
  * `when` is present only where an operation declares two success arms discriminated by a property of
- * the result — the application reads that property, because only it knows how to see inside its own
+ * the result - the application reads that property, because only it knows how to see inside its own
  * result envelope. Everything else about the choice is decided at generation time.
  *
- * ⚠️ **Failure arms are here too, and for a while they were not.** The document declares what an
- * error response looks like, and the generated server passed on only the success statuses — so an
+ * **Failure arms are here too, and for a while they were not.** The document declares what an
+ * error response looks like, and the generated server passed on only the success statuses - so an
  * application could not check what it sends when something goes wrong, because the schema never
  * arrived. Measured on one service: `401` and two `default` responses declared, zero emitted.
  *
- * ⚠️ **The arms arrive in OpenAPI's precedence order, so the FIRST match is the right one.** An exact
+ * **The arms arrive in OpenAPI's precedence order, so the FIRST match is the right one.** An exact
  * code, then a range, then the catch-all. That ordering is not a convention invented here: the
  * Responses Object says "if a response is defined using an explicit code, the explicit code
  * definition takes precedence over the range definition for that code", and `default` means every
  * status not otherwise listed. Sorting once at generation time is what keeps every application from
- * re-deriving the rule — and from getting it silently wrong when a `404` and a `4XX` both apply.
+ * re-deriving the rule - and from getting it silently wrong when a `404` and a `4XX` both apply.
  *
- * ⚠️ **`schema: undefined` is a statement, not an absence.** A response the document says carries no
+ * **`schema: undefined` is a statement, not an absence.** A response the document says carries no
  * body has no validator, and that is the truthful answer. It is also why the generated arms are
  * annotated with `satisfies readonly ResponseArm[]` rather than `as const`: measured, `as const`
  * catches a wrong `status` but is **blind** to a misspelled or omitted `schema`, because a bodyless
- * arm is legitimate — so the typo produces a valid-looking arm that validates nothing.
+ * arm is legitimate - so the typo produces a valid-looking arm that validates nothing.
  */
 export interface ResponseArm {
     /**
      * The status this arm answers with: an exact code, a `4XX`-style range, or the catch-all.
      *
-     * ⚠️ **`"default"` is carried as itself, not resolved to a number.** OpenAPI's `default` response
+     * **`"default"` is carried as itself, not resolved to a number.** OpenAPI's `default` response
      * means "any status not listed", and an emitter picking one would be answering a question the
      * contract deliberately left to the application. The application maps its own failure to a status;
      * this says which schema the body must match once it has.
      *
-     * ⚠️ **A range is carried as itself for the same reason, and it used to be dropped entirely.**
+     * **A range is carried as itself for the same reason, and it used to be dropped entirely.**
      * `@minValue(400) @maxValue(499) @statusCode _: int32` is a `4XX` entry in the document; the
      * emitter handled `"*"` and exact numbers and emitted nothing at all for the third case, so a
      * service could publish a whole class of failures with no arm to check them against. Expanding
-     * `4XX` to a hundred arms would be inventing statuses the contract never listed — the range IS
+     * `4XX` to a hundred arms would be inventing statuses the contract never listed - the range IS
      * what the document says, and matching against it is the application's to do, once, here.
      */
     readonly status: number | "default" | `${1 | 2 | 3 | 4 | 5}XX`;
@@ -62,7 +62,7 @@ export interface ResponseArm {
     };
 }
 /**
- * The arm that governs a status — **the rule the OpenAPI specification states, applied once here.**
+ * The arm that governs a status - **the rule the OpenAPI specification states, applied once here.**
  *
  * An application knows which status it is answering with; the document knows which schema that status
  * has to match. Joining the two means resolving an overlap, because `404`, `4XX` and `default` can
@@ -71,8 +71,8 @@ export interface ResponseArm {
  * code, the explicit code definition takes precedence over the range definition for that code".
  * `default` is by definition every status not otherwise listed, so it is last.
  *
- * ⚠️ **Shipped beside the arms rather than left to the caller, because this is where it goes wrong.**
- * Left to applications it gets written as "the first arm with a status ≥ 400" — which is literally
+ * **Shipped beside the arms rather than left to the caller, because this is where it goes wrong.**
+ * Left to applications it gets written as "the first arm with a status >= 400" - which is literally
  * what one consumer's wiring did before ranges existed, and which silently skips every range arm
  * while looking correct. A package that emits an array containing `4XX` and `default` and does not
  * ship the rule for reading it has shipped a footgun.

package/dist/src/runtime.js

@@ -1,5 +1,5 @@
 /**
- * The arm that governs a status — **the rule the OpenAPI specification states, applied once here.**
+ * The arm that governs a status - **the rule the OpenAPI specification states, applied once here.**
  *
  * An application knows which status it is answering with; the document knows which schema that status
  * has to match. Joining the two means resolving an overlap, because `404`, `4XX` and `default` can
@@ -8,8 +8,8 @@
  * code, the explicit code definition takes precedence over the range definition for that code".
  * `default` is by definition every status not otherwise listed, so it is last.
  *
- * ⚠️ **Shipped beside the arms rather than left to the caller, because this is where it goes wrong.**
- * Left to applications it gets written as "the first arm with a status ≥ 400" — which is literally
+ * **Shipped beside the arms rather than left to the caller, because this is where it goes wrong.**
+ * Left to applications it gets written as "the first arm with a status >= 400" - which is literally
  * what one consumer's wiring did before ranges existed, and which silently skips every range arm
  * while looking correct. A package that emits an array containing `4XX` and `default` and does not
  * ship the rule for reading it has shipped a footgun.

package/dist/src/streams.d.ts

@@ -2,39 +2,39 @@ import type { Program, Type } from "@typespec/compiler";
 /**
  * Optional support for `@typespec/streams`.
  *
- * ⚠️ **Lazily imported, and absent is a normal answer.** It is a separate library most specs never
+ * **Lazily imported, and absent is a normal answer.** It is a separate library most specs never
  * install, so a static import would make this emitter unusable without it. The structure follows
- * `@typespec/openapi3`'s own `sse-module.js` — an optional peer dependency, a guarded `import()`,
- * and `undefined` when it is missing — because an emitter that resolves it differently from the
+ * `@typespec/openapi3`'s own `sse-module.js` - an optional peer dependency, a guarded `import()`,
+ * and `undefined` when it is missing - because an emitter that resolves it differently from the
  * reference implementation will disagree with it about which specs it can serve. openapi3 needs
  * `@typespec/events` and `@typespec/sse` as well, to build the per-event `itemSchema` OpenAPI 3.2
  * carries; this emitter only needs to know WHAT is streamed, so one is enough.
  *
  * **Why this exists at all.** An SSE operation returns `SSEStream<UnnamedEvents>`, and under
- * OpenAPI 3.1 its response body is `{"type": "string"}` — the event stream itself. The event
- * PAYLOADS (`Unnamed.Info`, `Named.ResponseCreated`, …) are published as components that no path
+ * OpenAPI 3.1 its response body is `{"type": "string"}` - the event stream itself. The event
+ * PAYLOADS (`Unnamed.Info`, `Named.ResponseCreated`, ...) are published as components that no path
  * references: openapi3 builds `itemSchema` describing them for OpenAPI 3.2, and under 3.1 emits the
  * components as a by-product. Measured: the 3.1 document mentions neither `itemSchema` nor
  * `contentSchema`, yet declares all five payload models.
  *
  * They are still part of the published vocabulary, and reachable in the TypeSpec graph even though
- * the 3.1 paths do not reach them — `getStreamOf` hands back whatever the stream carries, an
+ * the 3.1 paths do not reach them - `getStreamOf` hands back whatever the stream carries, an
  * `@events` union for SSE and the item model for JSON Lines. So the payloads get validators, and a
  * consumer streaming events has something to check each `data:` against.
  */
 export interface StreamModule {
-    /** The type a stream carries — an `@events` union for SSE, the item model for JSON Lines. */
+    /** The type a stream carries - an `@events` union for SSE, the item model for JSON Lines. */
     readonly streamOf: (program: Program, type: Type) => Type | undefined;
 }
 export declare function resolveStreamModule(): Promise<StreamModule | undefined>;
 export declare function withStreamModule<T>(module: StreamModule | undefined, run: () => T): T;
 /**
- * What an operation streams, or `undefined` when it streams nothing — which is every operation in a
+ * What an operation streams, or `undefined` when it streams nothing - which is every operation in a
  * spec that does not use these libraries, and every ordinary operation in one that does.
  *
- * ⚠️ **Whatever the stream carries, not only an `@events` union.** The first cut required
+ * **Whatever the stream carries, not only an `@events` union.** The first cut required
  * `isEvents`, which fixed SSE and left `JsonlStream<Info>` behind: JSON Lines carries the item model
- * directly. The guard bought nothing — the streamed type is the published vocabulary in both cases —
+ * directly. The guard bought nothing - the streamed type is the published vocabulary in both cases -
  * and dropping it removed a second optional dependency along with the special case.
  */
 export declare function streamedTypeOf(program: Program, returnType: Type): Type | undefined;

package/dist/src/streams.js

@@ -27,12 +27,12 @@ export function withStreamModule(module, run) {
     }
 }
 /**
- * What an operation streams, or `undefined` when it streams nothing — which is every operation in a
+ * What an operation streams, or `undefined` when it streams nothing - which is every operation in a
  * spec that does not use these libraries, and every ordinary operation in one that does.
  *
- * ⚠️ **Whatever the stream carries, not only an `@events` union.** The first cut required
+ * **Whatever the stream carries, not only an `@events` union.** The first cut required
  * `isEvents`, which fixed SSE and left `JsonlStream<Info>` behind: JSON Lines carries the item model
- * directly. The guard bought nothing — the streamed type is the published vocabulary in both cases —
+ * directly. The guard bought nothing - the streamed type is the published vocabulary in both cases -
  * and dropping it removed a second optional dependency along with the special case.
  */
 export function streamedTypeOf(program, returnType) {

package/dist/src/tsp-index.d.ts

@@ -1,8 +1,8 @@
 /**
  * What TypeSpec's compiler loads for this library.
  *
- * ⚠️ **There is deliberately no `$decorators` export.** This emitter's ancestor defined four —
- * `@trimmed`, `@loose`, `@externalValues` and `@refine` — and every one of them let the spec state
+ * **There is deliberately no `$decorators` export.** This emitter's ancestor defined four -
+ * `@trimmed`, `@loose`, `@externalValues` and `@refine` - and every one of them let the spec state
  * something `@typespec/openapi3` could not publish, so the emitted validator enforced a rule no
  * caller reading the contract could see. A decorator here is not a convenience; it is a second
  * contract. If a spec needs to say something, it says it in a way the document carries.

package/dist/src/tsp-index.js

@@ -1,8 +1,8 @@
 /**
  * What TypeSpec's compiler loads for this library.
  *
- * ⚠️ **There is deliberately no `$decorators` export.** This emitter's ancestor defined four —
- * `@trimmed`, `@loose`, `@externalValues` and `@refine` — and every one of them let the spec state
+ * **There is deliberately no `$decorators` export.** This emitter's ancestor defined four -
+ * `@trimmed`, `@loose`, `@externalValues` and `@refine` - and every one of them let the spec state
  * something `@typespec/openapi3` could not publish, so the emitted validator enforced a rule no
  * caller reading the contract could see. A decorator here is not a convenience; it is a second
  * contract. If a spec needs to say something, it says it in a way the document carries.

package/dist/src/types.d.ts

@@ -1,10 +1,19 @@
 import { type ModelProperty, type Program, type Type } from "@typespec/compiler";
-/** A property line, including its optionality marker. */
-export declare function propertyToTs(program: Program, property: ModelProperty): string;
+/**
+ * A property line, including its optionality marker.
+ *
+ * `wireName` overrides the key for an HTTP PARAMETER, whose wire name comes from `@header("x-thing")`
+ * or `@query("$select")` rather than from any JSON encoding. `resolveEncodedName` cannot see those,
+ * so a header renamed on the wire was keyed here by its TypeScript property name while the emitted
+ * validator keyed it by the wire name. A consumer checking its handlers against the generated input
+ * types then failed to typecheck against a server that was correct: `z.object({ "x-thing": ... })`
+ * on one side and `{ thing: string }` on the other.
+ */
+export declare function propertyToTs(program: Program, property: ModelProperty, wireName?: string): string;
 export declare function withTsRefResolver<T>(resolver: (type: Type) => string | undefined, run: () => T): T;
 export declare function typeToTs(program: Program, type: Type): string;
 /**
- * The same walk, except that `type` is never resolved to its own name — see `SchemaRegistry.#inline`
+ * The same walk, except that `type` is never resolved to its own name - see `SchemaRegistry.#inline`
  * for why the "not itself" rule has to sit at the top of the walk rather than inside the resolver.
  */
 export declare function typeToTsBody(program: Program, type: Type): string;