typespec-http-zod 0.30.0 → 0.31.0

package/dist/src/zod.d.ts

@@ -1,5 +1,5 @@
-import { type Enum, type Model, type ModelProperty, type Program, type Scalar, type Type } from "@typespec/compiler";
-import { Visibility } from "@typespec/http";
+import { type Enum, type Model, type ModelProperty, type Program, type Scalar, type Type, type Union } from "@typespec/compiler";
+import { type MetadataInfo, Visibility } from "@typespec/http";
 /**
  * What a walk returns after reporting a refusal.
  *
@@ -10,17 +10,101 @@ import { Visibility } from "@typespec/http";
  * failed the compile that would have written it.
  */
 export declare const UNREPRESENTABLE = "z.never()";
-export declare function withDeferredAnnotator<T>(annotator: (property: ModelProperty) => string | undefined, run: () => T): T;
+export declare function withDeferredAnnotator<T>(annotator: (property: ModelProperty, position: PropertyPosition) => string | undefined, typeAnnotator: (type: Type) => string | undefined, run: () => T): T;
 export declare function withSealedObjects<T>(sealed: boolean, run: () => T): T;
-export declare function withVisibility<T>(program: Program, next: Visibility, run: () => T): T;
+/**
+ * **openapi3's own metadata view: `Read` is canonical, and a read-only property is shareable.**
+ *
+ * Built with `@typespec/http`'s defaults, the canonical visibility was `All`, so a model whose
+ * create-only property is visible at `All` was not transformed at `Create`: its create body
+ * collapsed onto the bare declaration, and every response was then validated as the CREATE view -
+ * `{name}` refused for want of the `secret` no response carries. And a read-only `id` made a model
+ * transformed at `Create`, where openapi3 shares the canonical schema, so the create body was
+ * validated without the `id` the document requires. Both are openapi3's arguments in
+ * `openapi.js`, passed as it passes them.
+ */
+export declare function metadataInfoOf(program: Program): MetadataInfo;
+export declare function withVisibility<T>(next: Visibility, run: () => T): T;
 /** Whether a property is optional AT THE CURRENT POSITION - PATCH makes update fields optional. */
 export declare function isOptionalAt(program: Program, property: ModelProperty): boolean;
 /** Whether a property belongs in the BODY at the current position, rather than being metadata. */
 export declare function isPayloadProperty(program: Program, property: ModelProperty): boolean;
-/** Whether this model is shaped differently at `visibility` than at the canonical `Read`. */
-export declare function isTransformedBy(program: Program, model: Model, at: Visibility): boolean;
+export declare function withMetadataAnnotationsIgnored<T>(ignored: boolean, run: () => T): T;
+export declare function withMultipartBinary<T>(binary: boolean, run: () => T): T;
+export declare function multipartBinaryContext(): boolean;
+/** `bytes` kept raw, as openapi3's `isBytesKeptRaw` reads it: the standard scalar, not encoded. */
+export declare function isRawBytes(program: Program, type: Type): boolean;
+/** A union one of whose own members is raw `bytes` - see `withMultipartBinary`. */
+export declare function holdsRawBytes(program: Program, type: Type): boolean;
+/** Whether metadata annotations are ignored where the walk is - the registry keys declarations on it. */
+export declare function metadataAnnotationsIgnored(): boolean;
+/** Whether this model or union is shaped differently at `visibility` than at the canonical `Read`. */
+export declare function isTransformedBy(program: Program, type: Model | Union, at: Visibility): boolean;
+/**
+ * **The visibility a type is rendered at where another type refers to it: openapi3's
+ * `reduceContext`.** A type that is not transformed at the requested visibility renders at `Read`, so
+ * a model with nothing create-specific inside a create body IS the canonical schema - a read-only
+ * property shared into it, as `canShareProperty` says. Rendered at the requested visibility under the
+ * canonical name, the body dropped that property while the document requires it.
+ *
+ * **Only where openapi3 reduces.** Its asset emitter asks for a reference context by what it emits:
+ * a named model, a model expression, a template instance, a named union, a scalar or an enum. A list -
+ * `T[]` or `model Tags is Tag[]` - and a union expression or instance have none, so they keep the
+ * visibility they were reached at, and so does everything inside them. Reduced here as well, a
+ * `model Tags is Tag[]` sent in a create body and returned was one declaration where the document
+ * publishes `TagsCreate` and `Tags`, and a model expression inside a union expression in a create
+ * body was judged at `Read`, where openapi3 reads its properties at `Create`.
+ */
+export declare function renderedVisibilityOf(program: Program, type: Type, requested: Visibility): Visibility;
+/**
+ * **The visibility an operation's body, parameter or response is rendered at: openapi3's
+ * `emitTypeWithSchemaEmitter`**, which renders a type at `Read` unless it is transformed at the
+ * requested visibility - whatever kind of type it is, a list included.
+ */
+export declare function rootVisibilityOf(program: Program, type: Type, requested: Visibility): Visibility;
+/**
+ * **Whether openapi3 can name a template instance**: its asset emitter's `declarationName`, which
+ * spells each argument's own name after the template's and gives up where one has none - a model
+ * expression, a literal, an instance of no nameable arguments. Such an instance is written out where
+ * it is used: `Maybe<{ x: string }>` is no component, and declared as `Maybe` it was one name for two
+ * schemas wherever a second argument appeared.
+ */
+export declare function isSpeakableInstance(type: Type): boolean;
+/** A named list model, `model Tags is Tag[]`, which openapi3 emits as an `arrayDeclaration`. */
+export declare function isNamedList(type: Model): boolean;
+/**
+ * **An array literal's elements are rendered at `Item` visibility**, as openapi3's
+ * `arrayLiteralReferenceContext` renders them: PATCH leaves a list's items required, and metadata on
+ * an element is data, since no element carries a header. Read at the list's own visibility, a PATCH
+ * made every item's properties optional, a `@header` on an element dropped out of the list the
+ * document requires it in, and one such model in a request list and a response list was two shapes
+ * under one name - `TaggedCreateItem` and `TaggedItem` in the document. A named list model is a
+ * declaration, rendered at its own visibility.
+ */
+export declare function atItem<T>(program: Program, list: Model, run: () => T): T;
+/**
+ * **An array literal, `T[]`, rather than a named list model** - as openapi3's asset emitter tells
+ * them apart, by name: a list called `Array` with no properties of its own. A visibility template's
+ * copy of `Pet[]` is no standard type, and read as a named list it was declared as `Array`, one
+ * name for every such copy.
+ */
+export declare function isArrayLiteral(program: Program, list: Model): boolean;
+export declare function withParameterPosition<T>(inside: boolean, run: () => T): T;
+export declare function inParameterPosition(): boolean;
+/** Why a tuple parameter is refused, and what to write instead - both walks say the same. */
+export declare const TUPLE_PARAMETER: {
+    readonly why: "a parameter typed as a tuple, which openapi3 publishes as `prefixItems` over the values it carries and this emitter does not read from the wire";
+    readonly remedy: "Declare the parameter as a list of one element type, or carry the value in the body.";
+};
 /** The visibility the current walk is emitting for - the registry keys declarations on it. */
 export declare function currentVisibility(): Visibility;
+/**
+ * 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.
+ */
+export declare function includeDerivedModel(model: Model): boolean;
 /**
  * Record every enum a service DECLARES, not merely every one its success bodies happen to reach.
  *
@@ -75,6 +159,21 @@ export declare function withDeclarationSite<T>(site: Type | undefined, run: () =
  * walked, which does.
  */
 export declare function refusalTarget(type: Type): Type;
+/**
+ * **The external document a type is published as a reference to**, by `@useRef`: openapi3 writes
+ * `$ref: <url>` wherever it is used and no component, so the document states no schema this emitter
+ * can read. Read off the decorator applied, as `@typespec/openapi3`, which declares it, is no
+ * dependency of this package.
+ */
+export declare function externalReferenceOf(type: Type): string | undefined;
+/** Refuse a type the document publishes only as a reference to another document. */
+export declare function refuseExternalReference(program: Program, type: Type, url: string): string;
+/**
+ * **The Zod a standard scalar becomes, or `undefined` for any other scalar** - looked up only for
+ * the standard library's own: a spec's `scalar uint8 extends string` is a string, and found in this
+ * table by its name it was validated as a byte, refusing every string the document accepts.
+ */
+export declare function standardScalarSchemaOf(program: Program, scalar: Scalar): string | undefined;
 /**
  * **A doc becomes `.describe()`, which is the one place Zod keeps a description.**
  *
@@ -109,17 +208,83 @@ export declare function described(expression: string, doc: string | undefined):
  * Without that, `string`'s own "A sequence of textual characters." would sit on every `z.string()`.
  */
 export declare function scalarDocOf(program: Program, scalar: Scalar): string | undefined;
-/** A scalar's schema without its description, for a position that publishes its own. */
 /**
- * The scalars an `@encode` chain passes through, when it returns to one it already passed - and
- * `undefined` when it ends at a type that crosses the wire.
+ * **The `@encode` a scalar is published under: its own, or the nearest one up its `extends` chain.**
+ *
+ * openapi3 builds a scalar that is not standard from its base's schema - encoding included - and
+ * then applies its own decorators over it, so `scalar TsChild extends Ts` with
+ * `@encode(unixTimestamp, int32)` on `Ts` is published as an integer, exactly as `Ts` is. This read
+ * the scalar's own `@encode` alone, so `TsChild` was validated as an ISO date-time string, refusing
+ * every value the document accepts and accepting every value it refuses. `link` is the scalar that
+ * declares the encoding.
+ */
+export declare function scalarEncodingOf(program: Program, scalar: Scalar): {
+    readonly link: Scalar;
+    readonly encoded: Scalar;
+} | undefined;
+export declare function withSyntheticDeclarations<T>(hook: (name: string, build: () => string, site: Type) => string, run: () => T): T;
+/**
+ * **Why a variant of an envelope-less `@discriminated` union cannot be dispatched to by its wire
+ * discriminator, or `undefined` where it can.** The variant must carry the discriminator under its
+ * WIRE name, as one fixed value. Matched on the TypeSpec name as well, a variant whose `kind` was
+ * renamed `t` passed, and the module threw "Invalid discriminated union option" on import; one
+ * inheriting an open `type: string` threw on every parse.
+ */
+export declare function undeclaredVariantOf(program: Program, variant: Type, property: string): "missing" | "open" | "refused" | undefined;
+/**
+ * **The variants a `@discriminated` union dispatches to: each but one no value can be.**
  *
- * **The one guard for every walk that follows `@encode`.** The schema, the wire kind and the contract
- * type each follow the chain by calling themselves on the encoded type, and each one overflowed the
- * stack on `Ping -> Pong -> Ping`. A scalar encoded as itself is no cycle: the chain ends there.
+ * A variant without an envelope that accepts nothing - its fixed discriminator refused by a
+ * declaration above it, `kind: "cobra"` under `@maxLength(3) kind: string`, or a key it requires
+ * refused by a base openapi3 seals - is published by the document as a member no value satisfies, and
+ * a `oneOf` with such a member accepts what the others accept. Refusing the union for it refused every
+ * `asp` the document accepts, and dispatching to it put a `z.never()` where Zod reads a literal: the
+ * first parse threw "Invalid discriminated union option".
  */
-export declare function encodeCycleOf(program: Program, scalar: Scalar): readonly Scalar[] | undefined;
-export declare function withSyntheticDeclarations<T>(hook: (name: string, build: () => string) => string, run: () => T): T;
+export declare function dispatchedVariantsOf(program: Program, union: Union): readonly [string, Type][];
+/**
+ * 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
+ * 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
+ * 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
+ * emitted **only when the variant declares that property itself**. Otherwise the document does not
+ * publish it and the union is refused; see `undeclared-discriminator`.
+ */
+/**
+ * **Whether a required property is optional at `at`**: a PATCH with implicit optionality, outside a
+ * list's elements - `@typespec/http`'s `isOptional`, for a property with no declaration of its own
+ * to ask, as an envelope's are.
+ */
+export declare function implicitlyOptional(at: Visibility): boolean;
+/**
+ * **The visibility an envelope is published at, within a union rendered at the current one.**
+ * openapi3 synthesises the envelope as a model of two properties - the discriminator and the variant
+ * - and emits it from the union's context, which reduces it to `Read` unless it is transformed
+ * there: where the variant is, or where a PATCH makes both its properties optional. Read as one
+ * envelope for every visibility, a PATCH body was held to the read wrapper's required `kind` and
+ * `value`, and a response to the create wrapper's variant.
+ */
+export declare function envelopeVisibilityOf(program: Program, union: Union, variant: Type): Visibility;
+/** Whether a variant's discriminator may be absent where the union is rendered - see `unionToZod`. */
+export declare function optionalDiscriminator(program: Program, union: Union, variant: Type, options: {
+    envelope: string;
+    discriminatorPropertyName: string;
+}): boolean;
+/**
+ * **The component openapi3 publishes an envelope as**: the union's name and the variant's, suffixed
+ * with the envelope's visibility where the union - whose usage openapi3 gives the envelope - is used
+ * at more than one. None for a union with no name, whose envelopes are written out where it is.
+ */
+export declare function envelopeNameOf(program: Program, union: Union, variantName: string, variant: Type): string | undefined;
 /**
  * Every property the model declares, **including the ones it inherits**.
  *
@@ -142,32 +307,355 @@ export declare function withSyntheticDeclarations<T>(hook: (name: string, build:
  * 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 declare function inheritedAndOwnProperties(model: Model): ModelProperty[];
+export declare function inheritedAndOwnProperties(program: Program, model: Model): ModelProperty[];
+/**
+ * A property of a model as the document publishes the model: the most derived declaration of a wire
+ * key, and the declarations of the same key further up the chain, nearest first.
+ *
+ * **Keyed on the WIRE name, because that is what the document keys a schema's properties on.** A
+ * subtype is published as `allOf` its base, so every declaration of a key along the chain still
+ * applies to the value. Keyed on the TypeSpec name, `@encodedName("application/json", "k") kind` on a
+ * base was REPLACED by a subtype's `kind`, so the subtype lost the `k` its base requires; and a base's
+ * `kind` renamed to `type` beside a subtype's own `type` was written as two `type` keys, which does not
+ * compile.
+ */
+export interface FlattenedProperty {
+    readonly property: ModelProperty;
+    readonly overridden: readonly ModelProperty[];
+}
+export declare function flattenedPropertiesOf(program: Program, model: Model): readonly FlattenedProperty[];
+/**
+ * The keys a model publishes at the current position, each with every declaration of it the
+ * document holds the value to - its most derived published declaration first.
+ *
+ * **A declaration counts where openapi3 publishes it, and only there.** Each model in the chain is
+ * published as `allOf` the one above, and each judges its own properties at the position: a
+ * `@header` or a create-only property above a response is in no schema the response is held to, so
+ * its `@maxLength` bounds nothing there; a `never` or an invisible redeclaration drops out of its own
+ * model's schema and leaves the key to the ones above it. Judged on the most derived declaration
+ * alone, the first was enforced where the document does not, and the second dropped a key the base
+ * still requires.
+ *
+ * **HTTP metadata is not payload.** A `@header` or `@statusCode` property describes the envelope, so
+ * it never appears in the body: RFC 9457 puts `@header("content-type") contentType:
+ * "application/problem+json"` on the problem model, the document described a body without it, and
+ * this emitter required `contentType` as a member. **A `never` property is dropped, as the document
+ * drops it**: `model N { value: never; other: string }` is published as `{other}`, and a validator
+ * keeping `value: z.never()` refused `{"other": "x"}`, the exact body the document describes.
+ */
+export declare function publishedPropertiesOf(program: Program, model: Model): readonly FlattenedProperty[];
+/**
+ * The discriminators a model is published under: its own and every one up its chain, by wire name.
+ * openapi3 lists each in its base's `required`, and the base applies through `allOf`.
+ */
+export declare function discriminatorsOf(program: Program, model: Model): readonly string[];
+/**
+ * **What the document asserts of a property at its position in a model, beyond its own declaration.**
+ *
+ * openapi3 publishes a subtype as `allOf` its base, so every declaration of a key along the chain
+ * still applies. Flattened to the subtype's declaration alone, `Pet { @maxLength(3) name: string }`
+ * let `Dog`'s own `name: string` be `"rexie"`, which the document refuses - and, under a discriminated
+ * base, so did the base, whose dispatch accepted it.
+ *
+ * **Where the overriding value narrows each declaration above it, the rest is their keywords**:
+ *
+ * - `constrainedBy`: the ancestors' own constraints, and their declared scalars', applied to the
+ *   value for its own JSON type; a literal is checked against them statically.
+ * - `never`: no value is both - another JSON type, or a literal the ancestor refuses.
+ * - `nullOnly`: the override's literals are all refused, and both sides admit `null`.
+ * - `nonNull`: the override admits `null` and a declaration above it does not.
+ * - `stringOnly`: openapi3 adds the discriminator as a `string` to the model declaring
+ *   `@discriminator` where that model's OWN properties lack it, whatever a model above it declares.
+ *
+ * **Where it does not, the declarations are merged into one schema** - `value`, see
+ * {@link mergeParts}: two unrelated models key by key, two lists by element, a union member by
+ * member. Zod's `.and()` is never put between two objects: it pools the keys one sealed side refuses,
+ * throws on two defaults, and is no option a dispatch can read.
+ *
+ * `required` holds where the property is a discriminator, which openapi3 adds to the base's
+ * `required` however it is declared, or where any declaration above requires it.
+ */
+export interface PropertyPosition {
+    readonly constrainedBy: readonly Keyworded[];
+    readonly required: boolean;
+    readonly stringOnly: boolean;
+    readonly never: boolean;
+    readonly nullOnly: boolean;
+    readonly nonNull: boolean;
+    /** The value as one schema, where the declarations above are merged with it rather than implied. */
+    readonly value: Merged | undefined;
+    /** The declarations above, each published at this position. */
+    readonly ancestors: readonly ModelProperty[];
+    /**
+     * **The visibility the most derived declaration's model is published at**, where a merge holds
+     * declarations published apart - see `mergeShapes`. Its optionality is read there: `M6 { b }`
+     * merged at a PATCH beside an `S8` published at `Read` was `b` required, where the document's
+     * `M6` leaves it optional.
+     */
+    readonly at?: Visibility;
+    /** A merge no one schema states - see `unrepresentable-override`. */
+    readonly refused: {
+        readonly ancestor: ModelProperty;
+        readonly why: string;
+        readonly recursive: boolean;
+    } | undefined;
+}
+export declare const OWN_POSITION: PropertyPosition;
+export declare function positionOf(program: Program, model: Model, entry: FlattenedProperty): PropertyPosition;
+/**
+ * **A declaration is judged at the visibility its own model is rendered at**, as openapi3 renders
+ * each model of a chain: a subtype's create body is `allOf` its base, and a base with nothing
+ * create-specific is the canonical schema - its read-only `id` shared in, `readOnly` and required.
+ * Judged at the subtype's visibility, the base's `id` dropped out of the create body the document
+ * requires it in. See `renderedVisibilityOf`.
+ */
+/** At the visibility a merged member's declaration is published at, where it is not the merge's. */
+export declare function atPosition<T>(position: PropertyPosition, run: () => T): T;
+export declare function atDeclaration<T>(program: Program, property: ModelProperty, run: () => T): T;
+/**
+ * **A property's type is referred to at the visibility openapi3 reads its declaration's properties
+ * at** - see `readVisibilityOf` - where the declaration is rendered at the current one. Its
+ * optionality and its position stay where the model is published; only what the type is named, a
+ * list or a union instance openapi3 does not reduce, can differ.
+ */
+export declare function atReading<T>(program: Program, property: ModelProperty, run: () => T): T;
+/**
+ * **Whether a union reaches itself through union members alone**: `union string { int32, string }`
+ * in a namespace, where the member `string` names the union and not the scalar, or `A { int32, B }`
+ * beside `B { string, A }`. No property or list element stands between the union and its own
+ * reference, so the schema openapi3 publishes, `anyOf: [int32, { $ref: string }]`, refers to itself
+ * with no value passed through on the way, and JSON Schema leaves that undefined - measured, Ajv
+ * overflows its stack on `5`, `"abc"` and `null` alike. TypeScript refuses the alias it would be,
+ * and the walks here that flatten a union recursed until the compiler reported "Emitter crashed!
+ * This is a bug." A union with an envelope wraps each member in an object, which a value does pass
+ * through, so the walk stops there.
+ */
+export declare function reachesItselfThroughUnions(program: Program, union: Union): boolean;
+/** Refuse a union that reaches itself through union members alone - see `reachesItselfThroughUnions`. */
+export declare function refuseSelfReachingUnion(program: Program, union: Union): void;
+/** TypeSpec's own assignability, which an override is checked against and a rename is not. */
+export declare function isAssignable(program: Program, source: Type, target: Type): boolean;
+/**
+ * A declaration whose keywords - `@minLength`, `@minItems` and the like - apply to a value beside its
+ * type: a property, a declared scalar above it, a model.
+ */
+export type Keyworded = ModelProperty | Scalar | Model;
+/**
+ * The wrapper openapi3 synthesises for one variant of a `@discriminated` union with an envelope -
+ * `{kind: "cat", value: Cat}` - which no TypeSpec type stands for. A member of a merge like any other.
+ */
+interface Envelope {
+    readonly kind: "Envelope";
+    readonly union: Union;
+    readonly name: string;
+    readonly variant: Type;
+    readonly discriminator: string;
+    readonly property: string;
+}
+type Member = Type | Envelope;
+/** One schema of the `allOf` a value is held to - see {@link mergeParts}. */
+interface Part {
+    /** What the value may be, `null` aside: one member, or each member of a union. */
+    readonly members: readonly Member[];
+    readonly nullable: boolean;
+    readonly keywords: readonly Keyworded[];
+    /** The declared type, where the part is one - rendered by reference where it narrows the rest. */
+    readonly type?: Type;
+    /** A declaration only valid whole: an encoding that keeps its declared type beside another. */
+    readonly whole?: ModelProperty;
+    /** Why no one schema states the part - a `@discriminated` union with a default variant. */
+    readonly refused?: string;
+    /** Its members are a `@oneOf` union's: exactly one may accept a value. */
+    readonly exclusive?: boolean;
+    /**
+     * **The visibility its value is published at, where that is not the merge's own** - each
+     * declaration's, as openapi3 publishes each: a list literal's element at `Item`, a named list's
+     * at the list's own visibility, a record's value at the record's. Merged at one visibility, a
+     * PATCH made every element of a list literal optional beside a named list, and a record's values
+     * optional where the document keeps them as declared.
+     */
+    readonly at?: Visibility;
+}
+/**
+ * **The declarations of one key, merged into the one schema the document holds its value to.**
+ *
+ * The document publishes each declaration in its own model and joins the models with `allOf`, so a
+ * value at the key is valid where every declaration accepts it. This is that conjunction, worked out
+ * as the document's own validator works it out, keyword family by keyword family:
+ *
+ * - a declaration whose type every other declaration's type admits is the value, with every
+ *   declaration's keywords on it - a subtype, a derived scalar, a literal the others allow;
+ * - a union is merged member by member, and a member no other declaration admits is dropped;
+ * - two objects are merged key by key: a key one sealed side does not declare is refused, a key
+ *   either requires is required, and a typed indexer holds every key it does not name;
+ * - two lists are merged element by element, with every declaration's `@minItems` and `@maxItems`;
+ * - two scalars of one JSON type that neither narrows are both checked, `.and()` between leaves.
+ *
+ * `null` is valid only where every declaration admits it, and a JSON type no declaration shares is no
+ * value at all. Refused only where no one schema can say it: a merge that refers back to itself, and a
+ * `@discriminated` union with a default variant, which this emitter refuses on its own.
+ */
+export type Merged = 
+/** No value - `withheld` where a refused declaration leaves it so, not the document. */
+{
+    readonly kind: "never";
+    readonly withheld?: true;
+} | {
+    readonly kind: "refused";
+    readonly why: string;
+    readonly recursive?: true;
+} | {
+    readonly kind: "type";
+    readonly type: Type;
+    readonly keywords: readonly Keyworded[];
+    /** The visibility the type is published at, where it is not the merge's own - see `Part`. */
+    readonly at?: Visibility;
+} | {
+    readonly kind: "whole";
+    readonly property: ModelProperty;
+} | {
+    readonly kind: "nullable";
+    readonly inner: Merged;
+} | {
+    readonly kind: "union";
+    readonly members: readonly Merged[];
+    readonly exclusive?: boolean;
+} | {
+    readonly kind: "all";
+    readonly parts: readonly Merged[];
+} | {
+    readonly kind: "array";
+    readonly element: Merged;
+    readonly keywords: readonly Keyworded[];
+    /** An array literal, whose element is computed and rendered at `Item` visibility. */
+    readonly list?: Model;
+} | MergedObject;
+export interface MergedObject {
+    readonly kind: "object";
+    readonly members: readonly MergedMember[];
+    /**
+     * What a key no member names may hold: nothing (`sealed`), anything, kept (`loose`) or stripped
+     * (`open`), or a value of a schema - a typed indexer.
+     */
+    readonly rest: "sealed" | "open" | "loose" | Merged;
+    /** Every key held to `rest`, and none declared: a dictionary. */
+    readonly dictionary: boolean;
+    readonly keywords: readonly Keyworded[];
+    /** Where a refusal inside the indexer is reported. */
+    readonly site: Type | undefined;
+}
+export interface MergedMember {
+    readonly key: string;
+    /** The declaration whose optionality, default and doc the member takes, or none where none states it. */
+    readonly property: ModelProperty | undefined;
+    readonly position: PropertyPosition;
+}
+export declare function mergeParts(program: Program, given: readonly (Part | undefined)[]): Merged;
+/**
+ * **The indexer that holds a model's keys: the TOPMOST string indexer in its chain.**
+ *
+ * openapi3 publishes a root model's indexer as `additionalProperties`, which holds every key the
+ * model does not declare itself - a subtype's own keys included, since the subtype is `allOf` the
+ * root - and a lower model's as `unevaluatedProperties`, which the root's has already evaluated. So
+ * the topmost indexer holds every key its own model and those above it do not declare, and any below
+ * it never applies. Read as the nearest, a subtype's `m: Inner2` escaped the base's
+ * `...Record<Inner>` and a subtype's own indexer refused keys the document accepts.
+ */
+export declare function bindingIndexerOf(model: Model): {
+    readonly link: Model;
+    readonly value: Type;
+} | undefined;
 /** The indexer in force, which a model can inherit - `model X extends Record<unknown>`. */
 export declare function effectiveIndexer(model: Model): Model["indexer"];
 /**
- * The subtypes a `@discriminator` base stands for, in declaration order.
+ * The subtypes a `@discriminator` base dispatches to: the models its document's `mapping` names.
+ *
+ * **The compiler's own reading, which is what openapi3 writes the mapping from.** A derived model
+ * that declares no value for the discriminator is looked through to the models derived from it
+ * that do. This used to be the base's DIRECT subtypes, so `Animal` -> `Mammal` (no `kind`) -> `Cat`
+ * dispatched to `Mammal`, which carries no literal `kind`, and Zod threw "Invalid discriminated union
+ * option" on every parse - a known kind, an unknown one, anything - while `Cat`, the model the
+ * mapping names for `"cat"`, was not in the dispatch at all.
  *
  * 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.
  */
 export declare function discriminatedSubtypes(program: Program, model: Model): readonly Model[];
 /**
- * **How a `@discriminator` base is validated: a value whose discriminator names a subtype as that
- * subtype, and any other value as the base model itself.**
+ * The subtypes a discriminated base dispatches to, each with the discriminator value its mapping
+ * names it for - see {@link discriminatedSubtypes}.
+ */
+export declare function dispatchedSubtypesOf(program: Program, model: Model): readonly (readonly [string, Model])[];
+/**
+ * **Why a model the mapping names cannot be dispatched to, or `undefined` where it can.**
  *
- * The document publishes the base as an object of its own properties carrying `discriminator:
- * {propertyName, mapping}`, and every subtype as `allOf` that base. The mapping says which subtype a
- * value naming it is; nothing in the document refuses a value naming none. This emitter dispatched
- * on the mapping and stopped there, so `{ "kind": "wrongKind", "weight": 8 }` was refused for a
- * `Dog` whose `kind` is `string | "golden"`, though `Dog` requires only `kind` and `weight`. That is
- * the response `@typespec/http-specs` declares for `type/model/inheritance/enum-discriminator`,
- * `single-discriminator` and `nested-discriminator`, and a handler returning it failed its own
- * response contract (typespec-http-graphql, 2026-10-16).
+ * A dispatch reads one fixed value per subtype - `z.discriminatedUnion` has no other way to choose -
+ * and the document's `mapping` names a subtype for exactly the values its discriminator fixes. Two
+ * declarations break that, and each used to break the emitted module:
  *
- * **A closed discriminator every value of which a subtype claims has no base arm**: a value outside
- * it is refused by the base's own discriminator, and a value inside it always names a subtype. So a
- * fixed enum fully covered by its subtypes is validated exactly as before.
+ * - **a discriminator that is not one fixed value** - `kind: "lab" | string`, or a subtype that
+ *   renames `kind` with `@encodedName` so the `kind` it publishes is its base's open `string`. Zod
+ *   threw "Invalid discriminated union option" on the first parse, or on import.
+ * - **a value a declaration above it refuses** - `kind: "cobra"` under `@maxLength(3) kind: string`.
+ *   The document publishes the subtype as `allOf` that base, so no value is one; validated as its own
+ *   declaration alone, every `"cobra"` was accepted.
+ *
+ * Each is refused as `invalid-subtype-discriminator`, as `undeclared-discriminator` refuses a
+ * discriminator the document cannot state, and the base dispatches to its other subtypes.
+ */
+export declare function invalidSubtypeOf(program: Program, subtype: Model, propertyName: string): {
+    readonly why: string;
+    readonly satisfiable: boolean;
+    readonly invisibleAt?: Visibility;
+} | undefined;
+/** A visibility as its flags read: `Update | Patch`, `Create | Item`. */
+export declare function visibilityName(at: Visibility): string;
+/**
+ * **Whether a model is a subtype its base's mapping names that no value can be** - its fixed
+ * discriminator refused by a declaration above it. Refused as `invalid-subtype-discriminator` and
+ * emitted as nothing, so used directly as a body it accepts nothing, as the document does, where it
+ * used to accept its own declaration.
+ */
+export declare function unsatisfiableSubtype(program: Program, model: Model): boolean;
+/**
+ * **A model extending a base that openapi3 seals because it does not count the model as derived.**
+ *
+ * openapi3 seals a model with no derived models it publishes, and a template instance is not one
+ * (`includeDerivedModel`). So with `seal-object-schemas` on, `Pet<string> extends Animal` leaves
+ * `Animal` sealed, and `Pet<string>` - published as `allOf` that sealed `Animal` - refuses every
+ * value carrying a property `Pet<string>` adds, since `Animal`'s own `unevaluatedProperties` cannot
+ * see it. Validated as its own flattened properties, such a value was accepted. Returns the sealed
+ * base and the keys it refuses, or `undefined` where nothing is refused.
+ */
+export declare function sealedBaseExtensionOf(program: Program, model: Model): {
+    readonly base: Model;
+    readonly keys: readonly string[];
+    readonly required: boolean;
+} | undefined;
+/**
+ * **How a `@discriminator` base is validated: as the document's base, deserialized as the subtype
+ * its discriminator names where the value is one.**
+ *
+ * The document publishes the base as an object of its own properties beside `discriminator:
+ * {propertyName, mapping}`, and every subtype as `allOf` that base. OAS 3.1.1 section 4.8.25 is
+ * normative that the discriminator "MUST NOT change the validation outcome of the schema", and
+ * section 4.8.25.2 that in this `allOf` form validating the parent "does not perform a search for
+ * child schemas or use them in validation in any way" - restated in 3.2.0 and 3.2.1, and by the
+ * spec's editors (OAI/OpenAPI-Specification#3901: "`discriminator` only really helps with things
+ * like code generation and data de-serialization. It doesn't help with validation"). Ajv defines it
+ * as a no-op for validation.
+ *
+ * **So the verdict is the base's, and the subtype is a deserialization.** A union of the dispatch
+ * and the base accepts exactly what the base accepts - every subtype is `allOf` the base, so a valid
+ * subtype is a valid base - and hands back, for a value that is a valid instance of the subtype its
+ * discriminator names, that subtype with its own properties, as an SDK deserializing the same body
+ * would. A value naming no subtype, or one that is not a valid instance of the subtype it names, is
+ * the base.
+ *
+ * This emitter refused a value naming no subtype until typespec-http-graphql's report of
+ * 2026-10-16, and 0.30.0 then guarded the base against a value naming a subtype, so a `"golden"`
+ * value missing `Golden`'s own fields was refused though the document accepts it as a `Dog`. Both
+ * made the validator stricter than the document it exists to agree with.
  */
 export interface DiscriminatedBase {
     /** The discriminator's wire name. */
@@ -175,18 +663,48 @@ export interface DiscriminatedBase {
     /** The subtypes a `z.discriminatedUnion` dispatches to, each carrying literal discriminator values. */
     readonly dispatched: readonly Model[];
     /**
-     * Subtypes that are themselves bases validated with a base arm. A `z.union` has no literal values
-     * to dispatch on, so no `z.discriminatedUnion` can hold one; it sits beside the dispatch, where its
-     * own literal discriminator keeps it exclusive.
+     * Subtypes that are themselves discriminated bases, and so `z.union`s with no literal values to
+     * dispatch on; no `z.discriminatedUnion` can hold one, so each sits beside the dispatch.
      */
     readonly beside: readonly Model[];
-    /** Every value a subtype claims, which are the keys of the document's `mapping`. */
-    readonly claimed: readonly string[];
-    /** Whether a value no subtype claims is validated as the base model. */
-    readonly open: boolean;
 }
 export declare function discriminatedBaseOf(program: Program, model: Model): DiscriminatedBase | undefined;
-export declare function wireKindOf(program: Program, type: Type): "number" | "boolean" | undefined;
+/** What the registry knows of the declarations a value refers to, which the value is built around. */
+export interface HeldDeclarations {
+    /**
+     * **A declaration refused as validating nothing - a collision - which no dispatch can hold**: its
+     * validator is `z.never()`, and `z.discriminatedUnion` throws on every parse given one. The
+     * registry re-renders a dispatch that held it before the refusal.
+     */
+    readonly refused: (expression: string) => boolean;
+    /**
+     * **A declaration annotated `z.ZodType<T>`, which no dispatch can hold**: the annotation
+     * `z.lazy()` requires for a recursive declaration erases the literal values
+     * `z.discriminatedUnion` reads, and the module failed to typecheck with `TS2322` - "not
+     * assignable to `$ZodTypeDiscriminable`".
+     */
+    readonly annotated: (expression: string) => boolean;
+    /**
+     * **A type whose declaration at a visibility is refused** - as a collision, or as
+     * `split-visibility` - which a merge or a `@oneOf` holding it holds to nothing. The registry
+     * re-renders a value that asked before the refusal.
+     */
+    readonly refusedAt: (type: Type, at: Visibility) => boolean;
+    /**
+     * **A type whose declaration at a visibility holds a refused one anywhere it refers to** - see
+     * `holdsRefusedMember`. The registry re-renders a value that asked before the refusal.
+     */
+    readonly holdsRefusalAt: (type: Type, at: Visibility) => boolean;
+}
+export declare function withHeldDeclarations<T>(given: HeldDeclarations, run: () => T): T;
+/**
+ * A model as the object it publishes at the current position: the merge of one - see
+ * {@link mergeShapes}. **HTTP metadata is not payload**, and neither is a property invisible here or
+ * a `never` one, which the document drops; each is judged declaration by declaration - see
+ * {@link publishedPropertiesOf}.
+ */
+export declare function objectOfModel(program: Program, model: Model): Merged;
+export declare function readsFromText(program: Program, type: Type): boolean;
 /**
  * A name as an object key - quoted when it is not a legal JavaScript identifier.
  *
@@ -221,8 +739,154 @@ export declare function objectKey(name: string): string;
  * comment indented differently from the member it documents is the tell that a generator wrote it.
  */
 export declare function jsDocComment(text: string | undefined, indent: string): string;
+/**
+ * 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
+ * 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
+ * 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.
+ *
+ * **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.
+ */
+export declare function rawPropertyKey(program: Program, property: ModelProperty): string;
 export declare function encodedTypeOf(program: Program, target: ModelProperty | Scalar): Scalar | undefined;
-export declare function propertyToZod(program: Program, property: ModelProperty): string;
+/**
+ * **What a property under `@encode` must be: what `@typespec/openapi3` publishes for it.**
+ *
+ * Its `applyEncoding` takes the schema the property would publish - a `$ref` to a declared type, or
+ * the type written out inline - and replaces only its `type` with the encoded scalar's, dropping
+ * `items` unless that is an array. Everything else stays. So `@encode("x", string) color: Color` is
+ * `{ $ref: Color, type: "string" }`: a string, and one of `Color`'s values. This emitter replaced the
+ * type outright, so it validated `z.string()` beside that and accepted `"green"`; it dropped a named
+ * scalar's `@pattern`, a literal union's values, and the `null` of a nullable property, the last
+ * contradicting the comment that said it was kept.
+ *
+ * - `declared`: no type change - no `@encode`, a query parameter's array style, `rfc3339` on a
+ *   date-time.
+ * - `replaced`: the declared type is written out inline, and nothing it kept constrains a value of
+ *   the new type - a standard scalar, an inline list, record or object.
+ * - `both`: the declared type is kept beside the new one and still constrains it. `kept` is what is
+ *   left of it once the new `type` has ruled out every member of another JSON type - the whole
+ *   declared type where nothing was ruled out - and `within` where that alone says both.
+ * - `unsatisfiable`: no value is both - `{ $ref: Filter, type: "string" }` - or only `null` is, or
+ *   the encoded scalar is not standard, so the document states no type at all. Refused, so no
+ *   validator contradicts it.
+ *
+ * `nullable` is the document's: openapi3 3.1 applies the encoding to the one member beside `null`
+ * when the property publishes as `anyOf: [<member>, { type: "null" }]`, and to the whole `anyOf`
+ * otherwise, where the new `type` rules `null` out with everything else of another type.
+ */
+export type EncodedValue = {
+    readonly kind: "declared";
+} | {
+    readonly kind: "replaced";
+    readonly scalar: Scalar;
+    readonly nullable: boolean;
+} | {
+    readonly kind: "both";
+    readonly scalar: Scalar;
+    /** The encoding's name - `rfc7231`, `ISO8601` - which decides what a member's check is. */
+    readonly form: string | undefined;
+    readonly nullable: boolean;
+    readonly kept: Type | readonly Type[];
+    readonly within: boolean;
+} | {
+    readonly kind: "unsatisfiable";
+    readonly scalar: Scalar;
+    readonly declared: Type;
+    readonly why: "typeless" | "nothing" | "null";
+};
+export declare function encodedValueOf(program: Program, property: ModelProperty): EncodedValue;
+/**
+ * The JSON type a value is published as. `fraction` is a number literal that is not an integer: a
+ * `number` scalar may hold an integer, so an `integer` encoding admits it, but `1.5` never can.
+ */
+type JsonType = "string" | "integer" | "number" | "fraction" | "boolean" | "object" | "array" | "null";
+/**
+ * The JSON type a scalar is published as, its own scalar-level `@encode` included - or `undefined`
+ * for a scalar with no standard base, which openapi3 publishes as `{}`, any value. Read as a string,
+ * `@encode("x", int32)` on one was refused as unsatisfiable while the document accepts `5`.
+ */
+export declare function jsonTypeOfScalar(program: Program, scalar: Scalar): JsonType | undefined;
+/**
+ * **Whether an encoded value is written as the encoded scalar intersected with what it keeps.**
+ *
+ * Where the kept type alone says both it is written alone - but a constraint on the property cannot
+ * go on a kept union or literal, which carries no `.min` or `.regex`, so then the constraints go on
+ * the encoded scalar and the kept type is intersected beside it. Applied to the union,
+ * `@encode("x", string) @minLength(2) v: string | "a"` emitted `z.union(...).min(2)`, and the module
+ * threw on import.
+ */
+export declare function encodedIntersects(program: Program, property: ModelProperty, encoding: Extract<EncodedValue, {
+    kind: "both";
+}>): boolean;
+/**
+ * **A union property's constraints, applied to each member as JSON Schema applies them.**
+ *
+ * `@minLength(2) v: string | "a" | int32` is published `{ anyOf: [...], minLength: 2 }`, and
+ * `minLength` constrains a value only where it is a string: `"ab"` and `5` are valid, `"a"` is not.
+ * Each member takes the keywords of its own JSON type, and a literal member breaking one is no value
+ * at all. Applied to the union, this emitted `z.union(...).min(2)`, and the module threw on import.
+ * The constraints are the property's own and those of every declaration above it the position
+ * leaves - see `PropertyPosition` - and, where openapi3 adds the discriminator as a `string`, only
+ * the members that can be a string are left. Returns the members left, or `undefined` where the
+ * property is not a union read member by member.
+ */
+export declare function constrainedMembersOf(program: Program, property: ModelProperty, position?: PropertyPosition): readonly Type[] | undefined;
+/** A member with no JSON type of its own: `unknown`, or a scalar with no standard base. */
+export declare function isTypelessMember(program: Program, member: Type): boolean;
+export declare const ANY_JSON_TS: string;
+/** Whether a kept member is a scalar whose own check the encoding's wire form replaces. */
+export declare function replacesFormOf(program: Program, encoding: Extract<EncodedValue, {
+    kind: "both";
+}>, member: Type): member is Scalar;
+export declare function isExclusive(program: Program, target: Type): boolean;
+/** Whether a union is exclusive where it is rendered: its own `@oneOf`, or its property's. */
+export declare function isExclusiveHere(program: Program, union: Union): boolean;
+/** The inline union a property's `@oneOf` makes exclusive; a named one is a `$ref` it leaves alone. */
+export declare function exclusiveSiteOf(program: Program, property: ModelProperty, declared: Type): Type | undefined;
+/**
+ * **Whether a `@oneOf` holds a member whose declaration is refused, or refers to one that is**, so
+ * that it validates nothing. openapi3 still publishes the member, and counts it: `@oneOf union O {
+ * a: S, b: N }` with `S` refused as `split-visibility` accepted `{"id": "i"}`, which matches both
+ * members in the document and so is refused there - `z.xor` counted the refused `S` as matching
+ * nothing. **A member holding a refused declaration further down is held stricter in the same way**:
+ * `@oneOf { v0: M16, v1: M13 }`, with `M13`'s `c?: M14` refused, accepted `{ c: {...}, e: "red" }`,
+ * which matches both in the document, as `M16` alone. Both walks ask it, so the validator and the
+ * contract type are `never` together.
+ */
+export declare function holdsRefusedMember(program: Program, union: Union, exclusive: boolean): boolean;
+export declare function withExclusiveSite<T>(site: Type | undefined, run: () => T): T;
+/**
+ * The members of a union a value's keywords leave, or `undefined` where the type is no union: a
+ * literal member breaking one is no value at all. Shared by both walks, so they list the same members.
+ */
+export declare function keptMembersOf(program: Program, type: Type, keywords: readonly Keyworded[]): readonly Type[] | undefined;
+/** The keywords that constrain anything, of the declarations a merged value carries. */
+export declare function constrainingKeywords(program: Program, keywords: readonly Keyworded[]): readonly Keyworded[];
+/**
+ * **The members a merged union is written with, by the validator and the contract type alike: one
+ * of each text the validator writes, in an `anyOf`.** `M19 | M19` merged with `Record<M19>` was two
+ * identical objects, whose two `z.input` types the wire assertion told apart from the one `Record` the
+ * contract type is (`TS2344`). Each walk deduplicating by its own text disagreed the other way: `S3`
+ * merged under `M1 | M2` is two objects the validator writes apart - `b` held to one `@minLength` and
+ * to two - and the contract type wrote as one, and TypeScript counts a union of two such objects as
+ * no object. So the validator decides, as it writes them, and the contract type writes the members
+ * it kept - see {@link noteWrittenMembers}. Repeated in a `@oneOf`, a value matching both is refused,
+ * so there each stays.
+ */
+export declare function membersToWrite(program: Program, value: Merged & {
+    readonly kind: "union";
+}): readonly Merged[];
+export declare function propertyToZod(program: Program, property: ModelProperty, position?: PropertyPosition): string;
 /**
  * **Whether `propertyToZod` emits `.default(...)` for this property, which is exactly whether its
  * INPUT admits an explicit `undefined`.**
@@ -235,7 +899,9 @@ export declare function propertyToZod(program: Program, property: ModelProperty)
  *
  * Pure: it reports nothing, so the type walk can ask it without duplicating a diagnostic.
  */
-export declare function emitsDefault(program: Program, property: ModelProperty): boolean;
+export declare function emitsDefault(program: Program, property: ModelProperty, position?: PropertyPosition): boolean;
+/** The non-null half of a two-variant `T | null` union, or `undefined` if it is not one. */
+export declare function nullableInnerOf(type: Type): Type | undefined;
 export declare function withRefResolver<T>(resolver: (type: Type) => string | undefined, run: () => T): T;
 /** Called by the registry when it hands out the identifier of a declaration that is still open. */
 export declare function noteBackEdge(): void;
@@ -260,4 +926,14 @@ export declare function typeToZod(program: Program, type: Type): string;
  * occurrences still go through {@link typeToZod} and do resolve - which is what makes a recursive
  * model reference itself instead of inlining itself forever.
  */
+/**
+ * **An instance of a list template is refused**: `model Page<T> is T[]` made `Page<Item>`, which
+ * openapi3 emits as a template instance - an object - and publishes as `type: object` with the
+ * element as `additionalProperties`, a dictionary where the spec declares a list. No validator agrees
+ * with both. A named list per element type, `model Items is Item[]`, or `Item[]` itself, is a list in
+ * the document too.
+ */
+export declare function listTemplateInstanceWhy(program: Program, type: Model): string | undefined;
+export declare const LIST_TEMPLATE_REMEDY = "Declare a named list model per element type, `model Items is Item[]`, or use `Item[]` itself.";
 export declare function typeToZodBody(program: Program, type: Type): string;
+export {};