typespec-http-zod 0.25.1 → 0.27.0

package/dist/src/registry.js

@@ -1,7 +1,8 @@
+import { getFriendlyName, } from "@typespec/compiler";
 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";
+import { propertyToTs, propertyTypeToTs, typeToTsBody, withTsRefResolver } from "./types.js";
+import { captureBackEdges, currentVisibility, isOptionalAt, isTransformedBy, noteBackEdge, propertyToZod, UNREPRESENTABLE, typeToZodBody, withDeferredAnnotator, withRefResolver, withSyntheticDeclarations, } from "./zod.js";
 /**
  * The name an ANONYMOUS payload model inherits from the single model it spreads.
  *
@@ -145,7 +146,7 @@ function safeDeclarationName(name) {
     return RESERVED_DECLARATION_NAMES.has(name) ? `${name}_` : name;
 }
 /** A type earns a name when the spec gave it one - anonymous shapes stay inline where they are used. */
-function declaredNameOf(type) {
+function declaredNameOf(program, type) {
     if (type.kind === "Enum")
         return safeDeclarationName(type.name);
     /**
@@ -168,18 +169,29 @@ function declaredNameOf(type) {
         return spread === undefined ? undefined : safeDeclarationName(spread);
     }
     /**
-     * **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 - unless
+     * `@friendlyName` gives it one of its own.**
      *
      * `PublicSuccess<PublicCompanyDetail>` and `PublicSuccess<PublicOfficers>` are both called
      * `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.
+     * file does not compile, and if it did, one shape would validate every response.
+     * `@typespec/openapi3` inlines instantiations for the same reason.
+     *
+     * **But it stops inlining one that has been named, and this used to keep inlining it.** Its rule
+     * is `shouldInline` in `@typespec/openapi`, and the first thing that function does is
+     * `if (getFriendlyName(program, type)) return false`. Measured on
+     * `@friendlyName("{name}Box", T) model Box<T>` used as `Box<string>`: openapi3 publishes a
+     * component `stringBox` and refers to it with `$ref`, while this emitter wrote the object out
+     * inline. So the two artefacts disagreed about what has a name, which is the opposite of what
+     * this docblock used to claim, and `@friendlyName` - the remedy openapi3 names for an inline
+     * cycle, and the one {@link "inline-cycle"} names here - did nothing.
      *
      * Invisible until a spec uses a template; a paged-response envelope is the usual first one.
      */
-    if (type.templateMapper !== undefined)
-        return undefined;
+    if (type.templateMapper !== undefined) {
+        const friendly = getFriendlyName(program, type);
+        return friendly === undefined || friendly === "" ? undefined : safeDeclarationName(friendly);
+    }
     return safeDeclarationName(type.name);
 }
 const lowerFirst = (value) => value.charAt(0).toLowerCase() + value.slice(1);
@@ -269,6 +281,19 @@ export class SchemaRegistry {
     #inProgress = new Map();
     /** Keys on a cycle - every one needs a structural type rather than a `z.infer` alias. */
     #cyclic = new Set();
+    /**
+     * Inlined types currently being walked, by identity, against the number of declarations that were
+     * in flight when each was entered.
+     *
+     * **The count is what tells a real inline cycle from an ordinary recursive model.** `#inProgress`
+     * cannot serve on its own: it is keyed by declaration name and these types have none, which is
+     * the whole reason the cycle has nothing to point at. But `InnerModel[]` re-enters `Array<InnerModel>`
+     * on a perfectly ordinary recursion - array, then the model, then the model's own `children` - and
+     * that cycle closes through `InnerModel`, which IS a declaration and terminates it. Comparing the
+     * count is how this asks openapi3's question, `cycle.containsDeclaration`: if a declaration was
+     * entered since, the cycle has a name to close on and the walk may continue.
+     */
+    #inlineInProgress = new Map();
     constructor(program) {
         this.#program = program;
     }
@@ -278,9 +303,30 @@ export class SchemaRegistry {
      * what lets the generated file be plain `const` declarations with no forward references.
      */
     expressionFor(type) {
-        const bare = declaredNameOf(type);
-        if (bare === undefined)
-            return this.#inline(type);
+        const bare = declaredNameOf(this.#program, type);
+        if (bare === undefined) {
+            /**
+             * **A back edge to an INLINED type is a cycle with no name to close it**, and following it
+             * is a stack overflow rather than a wrong answer: the compiler reports "Emitter crashed!
+             * This is a bug." Tracked by identity because there is no key to track it by.
+             */
+            const entered = this.#inlineInProgress.get(type);
+            if (entered !== undefined && this.#inProgress.size <= entered) {
+                reportDiagnostic(this.#program, {
+                    code: "inline-cycle",
+                    format: { type: "name" in type && type.name !== undefined ? String(type.name) : "" },
+                    target: type,
+                });
+                return UNREPRESENTABLE;
+            }
+            this.#inlineInProgress.set(type, this.#inProgress.size);
+            try {
+                return this.#inline(type);
+            }
+            finally {
+                this.#inlineInProgress.delete(type);
+            }
+        }
         /**
          * **A type not reshaped at this visibility IS the canonical declaration - not a copy of it.**
          *
@@ -335,6 +381,31 @@ export class SchemaRegistry {
             ...(this.#cyclic.has(key) ? { structural: this.#structuralBodyOf(type) } : {}),
             ...(rendered.deferred ? { annotated: true } : {}),
         };
+        /**
+         * **Two different types can resolve to one identifier, and the module then does not parse.**
+         *
+         * The key is `(visibility, name, identity)`, so two models genuinely named the same in
+         * different namespaces are two entries - and both then emit `export const thingSchema`.
+         * Measured on one service declaring `Alpha.Thing` and `Beta.Thing`: the document published
+         * both components under their full names, the emitted module declared `thingSchema` twice,
+         * and `tsc` answered `TS2451: Cannot redeclare block-scoped variable` while `tsp compile`
+         * reported success.
+         *
+         * `duplicate-declaration` already existed for exactly this and already said exactly this, but
+         * only {@link TypeRegistry} raised it - so the contracts files were covered and
+         * `schemas.gen.ts`, which every consumer imports, was not. `@typespec/openapi3` reports the
+         * same class through `checkDuplicateTypeName`, and `@typespec/json-schema` through
+         * `duplicate-id`; neither resolves it for you, because only the author knows which name to
+         * change.
+         */
+        const collision = this.#order.find((candidate) => candidate.identifier === identifier && candidate.source !== declaration.source);
+        if (collision !== undefined) {
+            reportDiagnostic(this.#program, {
+                code: "duplicate-declaration",
+                format: { name },
+                target: type,
+            });
+        }
         this.#declarations.set(key, declaration);
         this.#order.push(declaration);
         this.#declareRelatives(type);
@@ -372,11 +443,18 @@ export class SchemaRegistry {
      * would be documented and never enforced.
      */
     expressionForProperty(property) {
-        return withRefResolver((candidate) => {
-            if (declaredNameOf(candidate) === undefined)
-                return undefined;
-            return this.expressionFor(candidate);
-        }, () => propertyToZod(this.#program, property));
+        return withRefResolver(
+        /**
+         * **Every candidate goes through {@link expressionFor}, including the ones with no name.**
+         *
+         * This used to return `undefined` for an undeclared type, which sent it straight to
+         * `typeToZodBody` and past the only place a cycle is detected. A template instantiation is
+         * undeclared - `declaredNameOf` returns undefined for one, matching openapi3's inlining -
+         * so `model Box<T> { next?: Box<T> }` walked into itself until the stack ran out.
+         * `expressionFor` renders an undeclared type through `#inline` exactly as before, and now
+         * also notices when it is already doing so.
+         */
+        (candidate) => this.expressionFor(candidate), () => propertyToZod(this.#program, property));
     }
     /**
      * A declaration for a shape the spec never wrote, under a name the document publishes.
@@ -424,7 +502,7 @@ export class SchemaRegistry {
      * drift.
      */
     #structuralBodyOf(type) {
-        return withTsRefResolver((candidate) => declaredNameOf(candidate), () => typeToTsBody(this.#program, type));
+        return withTsRefResolver((candidate) => declaredNameOf(this.#program, candidate), () => typeToTsBody(this.#program, type));
     }
     /**
      * Render `type` without consulting its own declaration, but letting nested types use theirs.
@@ -437,11 +515,41 @@ export class SchemaRegistry {
      * a nested occurrence resolve to the identifier while the body still renders as a body.
      */
     #inline(type) {
-        return withRefResolver((candidate) => {
-            if (declaredNameOf(candidate) === undefined)
-                return undefined;
-            return this.expressionFor(candidate);
-        }, () => withSyntheticDeclarations((name, build) => this.#declareSynthetic(name, build), () => typeToZodBody(this.#program, type)));
+        return withRefResolver(
+        /**
+         * **Every candidate goes through {@link expressionFor}, including the ones with no name.**
+         *
+         * This used to return `undefined` for an undeclared type, which sent it straight to
+         * `typeToZodBody` and past the only place a cycle is detected. A template instantiation is
+         * undeclared - `declaredNameOf` returns undefined for one, matching openapi3's inlining -
+         * so `model Box<T> { next?: Box<T> }` walked into itself until the stack ran out.
+         * `expressionFor` renders an undeclared type through `#inline` exactly as before, and now
+         * also notices when it is already doing so.
+         */
+        (candidate) => this.expressionFor(candidate), () => withDeferredAnnotator((property) => this.#deferredAnnotationOf(property), () => withSyntheticDeclarations((name, build) => this.#declareSynthetic(name, build), () => typeToZodBody(this.#program, type))));
+    }
+    /**
+     * The Zod type a property emitted as a getter is annotated with, or `undefined` for none.
+     *
+     * **Written here because naming a type is this class's job.** The walk in `zod.ts` produces the
+     * getter; only the registry resolves a named type to the declaration that carries it, so only it
+     * can write `Record<string, InnerModel>` rather than inlining the model and recursing forever.
+     * `types.ts` is the same walk `propertyToTs` uses, so the annotation cannot drift from the type
+     * the wire contract compares against.
+     *
+     * **A DEFAULTED property is left unannotated.** `propertyToZod` emits `.default(...)` only where
+     * `defaultOf` could render the value and reports a diagnostic where it could not, so an annotation
+     * written here would have to predict that decision; predicting it wrongly would put a type on the
+     * getter that its own value does not satisfy. A recursive property carrying a default is the one
+     * shape this leaves as it was.
+     */
+    #deferredAnnotationOf(property) {
+        if (property.defaultValue !== undefined)
+            return undefined;
+        const declared = withTsRefResolver((candidate) => declaredNameOf(this.#program, candidate), () => propertyTypeToTs(this.#program, property));
+        const core = `z.ZodType<${declared}, ${declared}>`;
+        const optional = property.optional || isOptionalAt(this.#program, property);
+        return `: ${optional ? `z.ZodExactOptional<${core}>` : core}`;
     }
     /** Every declaration, dependencies first. */
     declarations() {
@@ -515,13 +623,31 @@ export class TypeRegistry {
     #declarations = new Map();
     #order = [];
     #inProgress = new Map();
+    /**
+     * The same in-flight tracking {@link SchemaRegistry} keeps, for the same cycle and by the same
+     * rule. Guarding one walk and not the other left the Zod side reporting `inline-cycle` correctly
+     * and the TypeScript side still running off the stack immediately afterwards, which reads to a
+     * consumer as "Emitter crashed! This is a bug." rather than as the error that was raised.
+     * Reported only by the schema walk, so one spec does not produce the same complaint twice.
+     */
+    #inlineInProgress = new Map();
     constructor(program) {
         this.#program = program;
     }
     expressionFor(type) {
-        const bare = declaredNameOf(type);
-        if (bare === undefined)
-            return this.#inline(type);
+        const bare = declaredNameOf(this.#program, type);
+        if (bare === undefined) {
+            const entered = this.#inlineInProgress.get(type);
+            if (entered !== undefined && this.#inProgress.size <= entered)
+                return "never";
+            this.#inlineInProgress.set(type, this.#inProgress.size);
+            try {
+                return this.#inline(type);
+            }
+            finally {
+                this.#inlineInProgress.delete(type);
+            }
+        }
         const at = visibilityFor(this.#program, type, currentVisibility());
         const key = keyFor(type, at);
         const name = nameAt(bare, at);
@@ -604,18 +730,14 @@ export class TypeRegistry {
      */
     /** `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, wireName));
+        return withTsRefResolver(
+        // Through expressionFor even when undeclared, so the cycle guard above is reachable.
+        (candidate) => this.expressionFor(candidate), () => propertyToTs(this.#program, property, wireName));
     }
     #inline(type) {
-        return withTsRefResolver((candidate) => {
-            if (declaredNameOf(candidate) === undefined)
-                return undefined;
-            return this.expressionFor(candidate);
-        }, () => typeToTsBody(this.#program, type));
+        return withTsRefResolver(
+        // Through expressionFor even when undeclared, so the cycle guard above is reachable.
+        (candidate) => this.expressionFor(candidate), () => typeToTsBody(this.#program, type));
     }
     /** Every declaration, dependencies first. */
     declarations() {

package/dist/src/rules/redos-prone-pattern.rule.d.ts

@@ -0,0 +1,27 @@
+import { type CallableMessage, type LinterRuleDefinition } from "@typespec/compiler";
+/**
+ * **A `@pattern` a backtracking engine can be made to spend unbounded time on.**
+ *
+ * **A linter rule, because TypeSpec's own definition puts it there.** A diagnostic says the program
+ * is not valid for this library; a linter says it "could be correct, but there might be room for
+ * improvements", and has to be enabled explicitly. Here the spec is valid, the document is correct,
+ * and the emitted regex is exactly the one `@typespec/openapi3` publishes. What is wrong is a cost no
+ * artefact states. `@typespec/http` puts its own advisory rule in a linter for the same reason.
+ *
+ * **This is a server-side denial of service, not a style note.** Measured on a generated server
+ * under `workerd`: `@pattern("^(\w+\s?)*$")`, which reads as "words", answers a 31-byte query
+ * parameter in 7.8 seconds against 2.9 milliseconds for a conformant one, and the cost doubles per
+ * added byte. The caller needs no credential and the parameter is validated before any handler runs.
+ * That is why the package's `recommended` ruleset enables it, and why the documentation says to.
+ *
+ * **The emitted regex is not changed, and cannot be.** Anchoring or bounding it here would make the
+ * validator enforce something the document does not state. What is left is to say so while the author
+ * can still change the spec.
+ *
+ * **Reported once per DECLARATION.** A linter walks declarations rather than uses, so a scalar used
+ * in 153 places is one report - and an instantiated template's properties share their declaration's
+ * node, which is what the de-duplication keys on.
+ */
+export declare const redosPronePatternRule: LinterRuleDefinition<"redos-prone-pattern", {
+    readonly default: CallableMessage<["pattern"]>;
+}>;

package/dist/src/rules/redos-prone-pattern.rule.js

@@ -0,0 +1,47 @@
+import { createRule, getPattern, paramMessage, } from "@typespec/compiler";
+import { patternIsProvablySafe } from "../constraints.js";
+/**
+ * **A `@pattern` a backtracking engine can be made to spend unbounded time on.**
+ *
+ * **A linter rule, because TypeSpec's own definition puts it there.** A diagnostic says the program
+ * is not valid for this library; a linter says it "could be correct, but there might be room for
+ * improvements", and has to be enabled explicitly. Here the spec is valid, the document is correct,
+ * and the emitted regex is exactly the one `@typespec/openapi3` publishes. What is wrong is a cost no
+ * artefact states. `@typespec/http` puts its own advisory rule in a linter for the same reason.
+ *
+ * **This is a server-side denial of service, not a style note.** Measured on a generated server
+ * under `workerd`: `@pattern("^(\w+\s?)*$")`, which reads as "words", answers a 31-byte query
+ * parameter in 7.8 seconds against 2.9 milliseconds for a conformant one, and the cost doubles per
+ * added byte. The caller needs no credential and the parameter is validated before any handler runs.
+ * That is why the package's `recommended` ruleset enables it, and why the documentation says to.
+ *
+ * **The emitted regex is not changed, and cannot be.** Anchoring or bounding it here would make the
+ * validator enforce something the document does not state. What is left is to say so while the author
+ * can still change the spec.
+ *
+ * **Reported once per DECLARATION.** A linter walks declarations rather than uses, so a scalar used
+ * in 153 places is one report - and an instantiated template's properties share their declaration's
+ * node, which is what the de-duplication keys on.
+ */
+export const redosPronePatternRule = createRule({
+    name: "redos-prone-pattern",
+    severity: "warning",
+    description: "Flag a @pattern that cannot be proven safe against catastrophic backtracking.",
+    messages: {
+        default: paramMessage `'${"pattern"}' cannot be proven safe against catastrophic backtracking: one input can match it more than one way, so a caller can choose a value that takes exponentially long to reject. The emitted validator runs it on every request, before any handler, and the pattern is published verbatim so it cannot be rewritten for you. Remove the ambiguity, usually by taking out a quantifier nested inside another or an optional separator between repeated groups, or add a SMALL '@maxLength' to bound the work.`,
+    },
+    create(context) {
+        const seen = new WeakSet();
+        const check = (target) => {
+            const pattern = getPattern(context.program, target);
+            if (pattern === undefined || patternIsProvablySafe(pattern))
+                return;
+            const declaration = target.node ?? target;
+            if (seen.has(declaration))
+                return;
+            seen.add(declaration);
+            context.reportDiagnostic({ format: { pattern }, target });
+        };
+        return { scalar: check, modelProperty: check };
+    },
+});

package/dist/src/runtime.d.ts

@@ -9,16 +9,12 @@ import type { ZodType } from "zod";
  * the sake of two declarations. `test/packaging.test.ts` asserts the separation rather than trusting
  * it.
  *
- * A consumer may substitute this entirely: the `runtime-module` option decides the specifier the
- * generated files import from, so an application that wants its own declarations points at its own
- * module and re-declares these names.
+ * The emitted `schemas.gen.ts` does not import it: the arm lists there are annotated with a copy of
+ * {@link ResponseArm} declared in that file, so the output depends on no runtime at all. This module
+ * is what an application reading those arms imports, and `armFor` is the rule it reads them by.
  */
 /**
- * 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
- * result envelope. Everything else about the choice is decided at generation time.
+ * One status an operation may answer with, and what the document publishes for it.
  *
  * **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
@@ -32,6 +28,11 @@ import type { ZodType } from "zod";
  * 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.
  *
+ * **Nothing here says how to choose an arm from a value.** An application names the status it is
+ * answering with, and {@link armFor} says which arm governs it. A `when` field used to name a
+ * property of the result to read the choice from; that made the choice depend on a TypeSpec property
+ * name the document never states, and it is gone.
+ *
  * **`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`
@@ -40,34 +41,31 @@ import type { ZodType } from "zod";
  */
 export interface ResponseArm {
     /**
-     * The media types this response offers, where the document names more than one.
+     * Every media type this response offers, including a single one.
      *
-     * Absent where it names one, which is what an application already assumes. Present, it is the set
-     * to negotiate against: `selectContentType` takes the caller's `Accept` and these.
+     * **A single type is carried too.** Omitting it assumed the one type is JSON, and a generic
+     * responder could then not tell a `text/plain` arm from a JSON one: the document knew and the
+     * runtime did not. Absent only where the response carries no body.
      */
     readonly contentTypes?: readonly string[];
     /**
-     * The headers this response declares, as the document publishes them.
-     *
-     * **Two names, because two different things need them.** `name` is the WIRE name, which is what
-     * the response sets; `property` is the name on the value the handler returned, which is where the
-     * value is read from. `@header("x-correlation-id") correlationId: string` is `x-correlation-id`
-     * on the wire and `correlationId` in the result.
+     * The headers this response declares, by the WIRE name the response sets.
      *
-     * Absent where the response declares none, so "none declared" and "none carried" are the same
-     * thing rather than two states an application has to tell apart.
+     * `optional` is the document's `required: false`. Absent where the response declares none, so
+     * "none declared" and "none carried" are the same thing rather than two states an application has
+     * to tell apart.
      */
     readonly headers?: readonly {
         readonly name: string;
-        readonly property: string;
+        readonly optional: boolean;
     }[];
     /**
      * 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
      * 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.
+     * contract deliberately left to the application. The application names its own 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.**
      * `@minValue(400) @maxValue(499) @statusCode _: int32` is a `4XX` entry in the document; the
@@ -78,18 +76,6 @@ export interface ResponseArm {
      */
     readonly status: number | "default" | `${1 | 2 | 3 | 4 | 5}XX`;
     readonly schema: ZodType | undefined;
-    /**
-     * How a handler said WHICH arm it meant, where an operation declares more than one success.
-     *
-     * **`number` too, because a `@statusCode` union selects by the status itself.**
-     * `model Created { @statusCode statusCode: 200 | 201 }` names the property that chooses and its
-     * values are the statuses; the discriminator case carries a boolean or string literal off the body
-     * instead. Both answer the same question, so both use this one field.
-     */
-    readonly when?: {
-        readonly property: string;
-        readonly value: boolean | number | string;
-    };
 }
 /**
  * The arm that governs a status - **the rule the OpenAPI specification states, applied once here.**

package/dist/src/types.d.ts

@@ -9,6 +9,13 @@ import { type ModelProperty, type Program, type Type } from "@typespec/compiler"
  * types then failed to typecheck against a server that was correct: `z.object({ "x-thing": ... })`
  * on one side and `{ thing: string }` on the other.
  */
+/**
+ * The TypeScript type of a property's VALUE, without its key or its optionality.
+ *
+ * Shared with the annotation the registry writes on a deferred (getter) property, so the type that
+ * annotation claims is by construction the type this walk renders for the same property.
+ */
+export declare function propertyTypeToTs(program: Program, property: ModelProperty): string;
 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;

package/dist/src/types.js

@@ -254,14 +254,23 @@ function modelToTs(program, model) {
  * types then failed to typecheck against a server that was correct: `z.object({ "x-thing": ... })`
  * on one side and `{ thing: string }` on the other.
  */
+/**
+ * The TypeScript type of a property's VALUE, without its key or its optionality.
+ *
+ * Shared with the annotation the registry writes on a deferred (getter) property, so the type that
+ * annotation claims is by construction the type this walk renders for the same property.
+ */
+export function propertyTypeToTs(program, property) {
+    // `@encode` changes the wire TYPE, resolved exactly as `zod.ts` resolves it - a property encoded as
+    // a string on one side and an array on the other fails the emitted assertion, and deserves to.
+    const encoded = getEncode(program, property)?.type;
+    return typeToTs(program, encoded ?? property.type);
+}
 export function propertyToTs(program, property, wireName) {
     // The WIRE name, resolved exactly as `zod.ts` resolves it - `wire-contract.gen.ts` asserts the
     // emitted Zod infers this type, so the two must name every property identically or it fails.
     const key = objectKey(wireName ?? resolveEncodedName(program, property, "application/json"));
-    // `@encode` changes the wire TYPE, resolved exactly as `zod.ts` resolves it - a property encoded as
-    // a string on one side and an array on the other fails the emitted assertion, and deserves to.
-    const encoded = getEncode(program, property)?.type;
-    const value = typeToTs(program, encoded ?? property.type);
+    const value = propertyTypeToTs(program, property);
     /**
      * **A defaulted property used to be REQUIRED here, and that was the OUTPUT type's answer to a
      * question this file does not ask.**

package/dist/src/uri-template.d.ts

@@ -0,0 +1,106 @@
+/**
+ * RFC 6570 URI templates, read for what a server has to mount and what it has to decode.
+ *
+ * **`HttpOperation.uriTemplate`, never `HttpOperation.path`.** `path` drops every operator, so
+ * `array{.param*}`, `array{;param}` and `array{/param}` all become `array{param}`, and a route mounted
+ * from it answers 404 to the URL its own contract declares. Measured on `@typespec/http-specs`
+ * `routes`: 30 of its mock server's URIs, plus the query-continuation six.
+ *
+ * `parseUriTemplate` is copied from `@typespec/http` 1.16.0 (`dist/src/uri-template.js`, MIT), which
+ * implements it but does not export it, so the template is split exactly as the library that built
+ * it splits it.
+ */
+/**
+ * One `/`-delimited segment of a route, as a server has to mount it.
+ *
+ * - `literal`: fixed text.
+ * - `expression`: exactly one parameter, with the literal text written before and after it inside
+ *   the same segment, its RFC 6570 operator (`""` for simple expansion) and whether it explodes. A
+ *   `/` expression opens a segment of its own, and one that explodes spans every segment after it.
+ * - `unsupported`: a segment holding more than one expression, which no segment router can split.
+ */
+export type EmittedPathSegment = {
+    readonly kind: "literal";
+    readonly text: string;
+} | {
+    readonly kind: "expression";
+    /** The parameter's WIRE name, the one `pathSchema` keys on. */
+    readonly parameter: string;
+    readonly prefix: string;
+    readonly suffix: string;
+    readonly operator: "" | "+" | "#" | "." | "/" | ";";
+    readonly explode: boolean;
+    readonly optional: boolean;
+    readonly reserved: boolean;
+} | {
+    readonly kind: "unsupported";
+    readonly text: string;
+};
+/** What the path segments need to know about each path parameter the operation resolves. */
+export interface PathParameterFacts {
+    readonly name: string;
+    readonly optional: boolean;
+    readonly reserved: boolean;
+}
+/** A route template as the segments a server mounts, and the literal query pairs it carries. */
+export declare function routeTemplateOf(uriTemplate: string, parameters: readonly PathParameterFacts[]): {
+    readonly segments: readonly EmittedPathSegment[];
+    readonly literalQuery: readonly (readonly [string, string])[];
+};
+/** What a value decodes into: one value, a list, or name/value pairs (a record or a model). */
+export type ExpansionShape = "scalar" | "list" | "record";
+/**
+ * Whether a path value needs decoding at all. **An ordinary whole-segment parameter does not**, and
+ * leaving its validator untouched keeps every spec without an RFC 6570 form byte-identical.
+ */
+export declare function needsExpansionDecoding(segment: Extract<EmittedPathSegment, {
+    kind: "expression";
+}>, shape: ExpansionShape): boolean;
+/**
+ * The call that decodes one expansion, as a `z.preprocess` argument. The decoder itself is
+ * {@link URI_EXPANSION_SOURCE}, declared once in `schemas.gen.ts` when something calls it.
+ */
+export declare function uriExpansionCall(spec: {
+    readonly prefix: string;
+    readonly suffix: string;
+    readonly operator: string;
+    readonly name: string;
+    readonly explode: boolean;
+    readonly shape: ExpansionShape;
+    readonly values: "number" | "boolean" | "";
+}): string;
+/**
+ * **RFC 6570 section 3.2, run backwards.** A router hands over the text of the segment an expression
+ * sits in (or, for an exploding `/` expression, every segment after its literal), and this undoes
+ * the expansion: the literal around it, the operator's leading character, a matrix parameter's
+ * `name=`, then the joiner the operator and explode modifier chose.
+ *
+ * Text that is not the expansion the route declares is REFUSED with an issue of its own, not passed
+ * on: a string parameter's schema would accept `primitive;other=a` as the string it is, so leaving
+ * the refusal to the schema admitted a request the route does not match. A list's element values
+ * are decoded by the element decoder inside, as a query list's are; a record's values are decoded
+ * here, because no schema expression reaches them one by one.
+ */
+export declare const URI_EXPANSION_SOURCE = "\n/** RFC 6570 section 3.2 in reverse: one expression's expansion, decoded into the value it expanded. */\nfunction uriExpansion(\n\traw: unknown,\n\tctx: { addIssue(issue: { code: \"custom\"; message: string }): void },\n\tspec: {\n\t\treadonly prefix: string;\n\t\treadonly suffix: string;\n\t\treadonly operator: string;\n\t\treadonly name: string;\n\t\treadonly explode: boolean;\n\t\treadonly shape: \"scalar\" | \"list\" | \"record\";\n\t\treadonly values: \"number\" | \"boolean\" | \"\";\n\t},\n): unknown {\n\tif (typeof raw !== \"string\") return raw;\n\tconst refuse = (): unknown => {\n\t\tctx.addIssue({ code: \"custom\", message: `Not the expansion of {${spec.operator}${spec.name}${spec.explode ? \"*\" : \"\"}} this route declares` });\n\t\treturn z.NEVER;\n\t};\n\tif (raw.length < spec.prefix.length + spec.suffix.length) return refuse();\n\tif (!raw.startsWith(spec.prefix) || !raw.endsWith(spec.suffix)) return refuse();\n\tlet text = raw.slice(spec.prefix.length, raw.length - spec.suffix.length);\n\tif (spec.operator === \".\" || spec.operator === \";\") {\n\t\tif (!text.startsWith(spec.operator)) return refuse();\n\t\ttext = text.slice(1);\n\t}\n\tif (spec.operator === \";\" && !(spec.shape === \"record\" && spec.explode)) {\n\t\tconst named = text\n\t\t\t.split(\";\")\n\t\t\t.map((part) => (part === spec.name ? \"\" : part.startsWith(`${spec.name}=`) ? part.slice(spec.name.length + 1) : undefined));\n\t\tif (named.some((part) => part === undefined)) return refuse();\n\t\tif (spec.shape === \"list\" && spec.explode) return named;\n\t\tif (named.length !== 1) return refuse();\n\t\ttext = named[0] ?? \"\";\n\t}\n\tif (spec.shape === \"scalar\") return text;\n\tconst joiner = spec.explode && (spec.operator === \".\" || spec.operator === \"/\" || spec.operator === \";\") ? spec.operator : \",\";\n\tif (spec.shape === \"list\") return text === \"\" ? [] : text.split(joiner);\n\tconst value = (item: string): unknown =>\n\t\tspec.values === \"number\" && item.trim() !== \"\" && Number.isFinite(Number(item))\n\t\t\t? Number(item)\n\t\t\t: spec.values === \"boolean\" && (item === \"true\" || item === \"false\")\n\t\t\t\t? item === \"true\"\n\t\t\t\t: item;\n\tconst entries: [string, unknown][] = [];\n\tif (spec.explode) {\n\t\tfor (const pair of text === \"\" ? [] : text.split(joiner)) {\n\t\t\tconst at = pair.indexOf(\"=\");\n\t\t\tif (at === -1) return refuse();\n\t\t\tentries.push([pair.slice(0, at), value(pair.slice(at + 1))]);\n\t\t}\n\t} else {\n\t\tconst items = text === \"\" ? [] : text.split(\",\");\n\t\tif (items.length % 2 !== 0) return refuse();\n\t\tfor (let index = 0; index < items.length; index += 2) {\n\t\t\tentries.push([items[index] ?? \"\", value(items[index + 1] ?? \"\")]);\n\t\t}\n\t}\n\treturn Object.fromEntries(entries);\n}\n";
+/**
+ * The call that gathers a form-exploded record or model back under its parameter name. The
+ * gatherer itself is {@link EXPLODED_QUERY_SOURCE}.
+ */
+export declare function explodedQueryCall(spec: {
+    readonly name: string;
+    /** For a record, every OTHER query parameter's wire name; its own keys are whatever is left. */
+    readonly others: readonly string[];
+    /** For a model, its own properties' wire names; `undefined` for a record. */
+    readonly keys: readonly string[] | undefined;
+    readonly numbers: readonly string[];
+    readonly booleans: readonly string[];
+    /** For a record, how every value decodes. */
+    readonly values: "number" | "boolean" | "";
+}): string;
+/**
+ * **`{?param*}` over a record or a model expands to the object's own keys**, `?a=1&b=2` and
+ * `?field=status&value=active`, so there is no `param` key for a query validator to find. This
+ * gathers those keys back under the parameter's name before the query object is validated: a model
+ * takes exactly its declared properties, a record every key no other query parameter claims.
+ */
+export declare const EXPLODED_QUERY_SOURCE = "\n/** RFC 6570 form expansion of an exploded record or model, gathered back under its parameter. */\nfunction explodedQuery(\n\traw: unknown,\n\tspec: {\n\t\treadonly name: string;\n\t\treadonly others: readonly string[];\n\t\treadonly keys: readonly string[] | null;\n\t\treadonly numbers: readonly string[];\n\t\treadonly booleans: readonly string[];\n\t\treadonly values: \"number\" | \"boolean\" | \"\";\n\t},\n): unknown {\n\tif (raw === null || typeof raw !== \"object\" || Array.isArray(raw) || spec.name in raw) return raw;\n\tconst gathered: Record<string, unknown> = {};\n\tconst rest: Record<string, unknown> = {};\n\tfor (const [key, value] of Object.entries(raw)) {\n\t\tconst own = spec.keys === null ? !spec.others.includes(key) : spec.keys.includes(key);\n\t\tif (!own) {\n\t\t\trest[key] = value;\n\t\t\tcontinue;\n\t\t}\n\t\tconst kind = spec.values !== \"\" ? spec.values : spec.numbers.includes(key) ? \"number\" : spec.booleans.includes(key) ? \"boolean\" : \"\";\n\t\tgathered[key] =\n\t\t\ttypeof value !== \"string\"\n\t\t\t\t? value\n\t\t\t\t: kind === \"number\" && value.trim() !== \"\" && Number.isFinite(Number(value))\n\t\t\t\t\t? Number(value)\n\t\t\t\t\t: kind === \"boolean\" && (value === \"true\" || value === \"false\")\n\t\t\t\t\t\t? value === \"true\"\n\t\t\t\t\t\t: value;\n\t}\n\treturn Object.keys(gathered).length === 0 ? raw : { ...rest, [spec.name]: gathered };\n}\n";