typespec-http-zod 0.30.0 → 0.32.0

package/dist/src/registry.js

@@ -1,72 +1,13 @@
 import { getDoc, getFriendlyName, } from "@typespec/compiler";
 import { getVisibilitySuffix, Visibility } from "@typespec/http";
+import { firstReportOf } from "./constraints.js";
 import { reportDiagnostic } from "./lib.js";
-import { propertyToTs, propertyTypeToTs, typeToTsBody, withTsRefResolver } from "./types.js";
-import { captureBackEdges, currentVisibility, described, isOptionalAt, isTransformedBy, noteBackEdge, propertyToZod, UNREPRESENTABLE, typeToZodBody, withDeferredAnnotator, withRefResolver, withSyntheticDeclarations, } from "./zod.js";
+import { isSplitByVisibility, isSuffixedByUsage, viewRemedyOf, viewTemplateOf, } from "./published.js";
+import { propertyToTs, propertyTypeToTs, typeToTs, typeToTsBody, withTsRefResolver, withTsSyntheticDeclarations, } from "./types.js";
+import { captureBackEdges, currentVisibility, described, externalReferenceOf, isArrayLiteral, isOptionalAt, isSpeakableInstance, refuseExternalReference, metadataAnnotationsIgnored, metadataInfoOf, multipartBinaryContext, noteBackEdge, OWN_POSITION, propertyToZod, renderedVisibilityOf, requestReadingAt, requestReadsApart, rootVisibilityOf, UNREPRESENTABLE, typeToZodBody, visibilityName, withDeclarationSite, withDeferredAnnotator, withMetadataAnnotationsIgnored, withMultipartBinary, withRefResolver, withRequestReadingAs, withHeldDeclarations, withSyntheticDeclarations, withParameterPosition, withVisibility, } from "./zod.js";
 /**
- * The name an ANONYMOUS payload model inherits from the single model it spreads.
- *
- * **`@typespec/http` hands back a synthesised model for a body whose declaration carried
- * metadata**, and it has no name - so `@error model InvalidAuth { @statusCode _: 403; error: string }`
- * reached the registry as `{error}` with `name: ""`, was inlined at its use site, and produced **no
- * validator at all** for a component the document publishes as `InvalidAuth`. Four authentication
- * scenarios, each with an unvalidated 403.
- *
- * `@typespec/openapi3` never meets that model: it works from the TypeSpec type and strips metadata
- * itself, which is why its component keeps the original name. This recovers the same name from
- * `sourceModels`, so both artefacts call the shape the same thing.
- *
- * **Only a PURE spread of one named model.** `{...A, extra: string}` is a different shape and must
- * not claim `A`'s name - so every property has to come from the source. Metadata-stripping removes
- * properties and never adds them, which is exactly the asymmetry this tests for. A collision would be
- * caught by the differential's `component-name-collision` arm regardless.
- */
-function spreadSourceOf(type, seen = new Set(), 
-/**
- * The properties the ORIGINAL type has, carried down the chain rather than re-derived.
- *
- * **Re-deriving them at each link is what blocked `Alias.InnerModel`.** The intermediate model
- * an operation builds holds the spread body's properties AND the operation's own `@path` and
- * `@header` parameters, so checking THAT set against the named ancestor fails on properties the
- * body never had. The question is whether every property of the shape being named comes from the
- * ancestor - `{name}` does - not whether some intermediate did.
- *
- * The guard is unchanged in what it refuses: `{...A, extra}` still fails, because `extra` is in
- * the original set and not in `A`.
- */
-required = [...type.properties.keys()]) {
-    if (seen.has(type))
-        return undefined;
-    const sources = type.sourceModels;
-    if (sources.length !== 1)
-        return undefined;
-    const source = sources[0];
-    if (source === undefined || source.usage !== "spread")
-        return undefined;
-    const model = source.model;
-    if (model.templateMapper !== undefined)
-        return undefined;
-    for (const property of required) {
-        if (!model.properties.has(property))
-            return undefined;
-    }
-    /**
-     * **Follow the chain through ANONYMOUS links.** TypeSpec puts an unnamed model between an
-     * operation's parameter model and the model that was spread into it, so stopping at the first
-     * source finds `""` and gives up - measured: the bodies for `Alias.InnerModel` and
-     * `Model.CompositeRequestMix` both reported `sources: [{ usage: "spread", name: "" }]` while the
-     * document published both as components, and the one case that already worked
-     * (`Model.BodyParameter`) was the one whose source happened to be named directly.
-     *
-     * Terminating on an unnamed source with no named ancestor is what keeps a spread ALIAS inline:
-     * OpenAPI names a component for a spread model and not for an alias, and following the chain
-     * reproduces that distinction rather than asserting it.
-     */
-    return model.name === "" ? spreadSourceOf(model, new Set([...seen, type]), required) : model;
-}
-const spreadSourceName = (type) => spreadSourceOf(type)?.name;
-/**
- * ECMAScript's reserved words, which cannot name a TypeScript declaration.
+ * The words TypeScript refuses as the name of a declaration the emitted files write - a type alias,
+ * an interface, and the references to each - in a module, which is strict mode.
  *
  * **A model may be named after one, and the corpus declares exactly that on purpose.** `special-words`
  * carries `await`, `break` and the rest, and this emitter wrote `export interface await { ... }` and
@@ -75,25 +16,28 @@ const spreadSourceName = (type) => spreadSourceOf(type)?.name;
  *
  * **This is a LIST, which this package otherwise refuses.** It is defensible here because it is
  * not a list about our own code that drifts as the code changes: it is a closed set the language
- * specification fixes. The guard is that `tsc` compiles a fixture declaring models named after these,
- * so a word missing from the list fails a test rather than reaching a consumer - the list is the
- * implementation and the compiler is the oracle.
+ * fixes. The guard is that `test/round9/names/` reads every keyword from the scanner of the
+ * TypeScript this package builds with, measures which ones `tsc` refuses in each position, and holds
+ * this set to exactly those - so a word missing here, or one renamed that need not be, fails a test.
  *
- * Most contextual keywords are absent, because they are legal: `interface`, `string`, `number`,
- * `any`, `never` and `public` all name a type without complaint.
+ * **It is four groups, and only the first is ECMAScript's reserved words.** This docblock used to say
+ * `interface`, `string`, `number`, `any`, `never` and `public` name a type without complaint; every
+ * one of them is refused, and `export type object = ...` did not even load (`Type alias name cannot
+ * be 'object'`). Measured against tsc 7.0.2 over the 84 keywords its scanner knows, as a model, an
+ * enum and a union: 61 refused, the 61 below; the other 23 - `type`, `declare`, `module`, `of` and
+ * the like - are legal everywhere the files write a name.
  *
- * **Two contextual words are NOT legal, and both were missing from this set.** `as` and `yield` are
- * refused in the declaration positions this emitter writes -- `export type as = ...` is
- * `TS1005: '{' expected`, and `yield` is `TS1214: 'yield' is a reserved word in strict mode` as both
- * a type alias and an interface. Either one made the whole emitted file unparseable, because the
- * parser gives up after the first.
- *
- * **A word belongs here when `tsc` refuses it in EITHER position**, since both are emitted for the
- * same model. Measured that way against tsc 7.0.2, one invocation per word: of the 56 candidates,
- * 39 are refused and 39 are listed. `yield` had been recorded here as measured-legal and is not,
- * which is why the arm that grades this set now takes its words from somewhere else entirely.
+ * - ECMAScript's reserved words, and `await` and `yield`, which a module reserves. `as` is contextual
+ *   but `export type as = ...` is `TS1005`.
+ * - The words strict mode reserves: `implements`, `interface`, `let`, `package`, `private`,
+ *   `protected`, `public`, `static` - `TS1214`, since a module is strict.
+ * - The predefined types, which no declaration may be named: `any`, `bigint`, `boolean`, `never`,
+ *   `number`, `object`, `string`, `symbol`, `undefined`, `unknown` - `TS2457` and `TS2427`.
+ * - The type operators, which do not parse where a type is referred to: `p?: keyof;` is `TS1110`,
+ *   and so are `readonly` and `unique`; `infer` is `TS1003`.
  */
 const RESERVED_DECLARATION_NAMES = new Set([
+    // ECMAScript's reserved words, and the two a module reserves.
     "as",
     "await",
     "break",
@@ -133,6 +77,31 @@ const RESERVED_DECLARATION_NAMES = new Set([
     "while",
     "with",
     "yield",
+    // Strict mode's.
+    "implements",
+    "interface",
+    "let",
+    "package",
+    "private",
+    "protected",
+    "public",
+    "static",
+    // The predefined types.
+    "any",
+    "bigint",
+    "boolean",
+    "never",
+    "number",
+    "object",
+    "string",
+    "symbol",
+    "undefined",
+    "unknown",
+    // The type operators.
+    "infer",
+    "keyof",
+    "readonly",
+    "unique",
 ]);
 /**
  * **The names the emitted files declare for THEMSELVES, beside the spec's own declarations.**
@@ -150,26 +119,87 @@ const EMITTED_HELPER_NAMES = new Set([
     "ByteStream",
     "Produced",
     "ResponseArm",
+    "SPEC_VOCABULARIES",
     "Simplify",
     "WireInputs",
     "WireOutputs",
+    "WireReader",
+    "WireReaders",
     "WireResults",
 ]);
 /**
- * The name a declaration is emitted under.
+ * **Library types the emitted files name bare, so a spec's type of the name takes a trailing `_`** -
+ * a multipart file's `arrayBuffer: () => globalThis.Promise<ArrayBuffer>`, a stream's `Uint8Array`
+ * chunks.
+ *
+ * **Every library GENERIC a file names is written `globalThis.Record<...>`, `globalThis.Readonly<...>`
+ * or `globalThis.Promise<...>` where it is written**, so a spec's own `model Record`, `Promise`,
+ * `Readonly` or `Exclude` is declared under its name, as openapi3 publishes it, and shadows nothing.
+ * This was a rewrite of each finished file instead - every `Record<` in a file declaring a `Record`
+ * became `globalThis.Record<` - and a file's text is not only references: the spec's own text is in
+ * it too. Measured beside `model Record`: `k?: "Record<k>"` became `z.literal("globalThis.Record<k>")`,
+ * refusing the value the document accepts and accepting one it refuses; `@pattern("^Record<...")`,
+ * a default and a `.describe()` were rewritten alike; and an enum's value `"Record<int32>"`, kept in
+ * `vocabularies.gen.ts`, was rewritten in `requests.gen.ts`, so the wire contract did not compile. Only
+ * the site writing a reference knows it is one.
+ */
+const LIBRARY_NAMES_WRITTEN_BARE = new Set(["ArrayBuffer", "Uint8Array"]);
+/**
+ * The name a declaration is emitted under, from the name the document publishes it under.
  *
  * A trailing `_` is appended where the spec's own name cannot be a TypeScript declaration, or is one
  * the emitted file already declares for itself. It is applied in ONE place so both walks agree:
  * `wire-contract.gen.ts` pairs a validator against a contract type by name, and a mangling applied to
  * one side only would break that assertion rather than the file.
+ *
+ * **Decided on the WHOLE name, visibility suffix included, and for every declaration.** It was
+ * decided on the bare name before {@link nameAt} added the suffix, so `model WireReader` seen through a
+ * PATCH, which openapi3 publishes as `WireReaderUpdate` - a name nothing in the files holds - was
+ * `WireReader_Update` and `wireReader_UpdateSchema`. And a declaration no type stands for never
+ * reached it: a multipart body `model public` was `export interface public` (`TS1214`), and a
+ * `@discriminated union Wire` with a variant `inputs` declared its envelope `WireInputs` beside the
+ * lookup of that name, and the two interfaces merged without a word.
  */
-function safeDeclarationName(name) {
-    return RESERVED_DECLARATION_NAMES.has(name) || EMITTED_HELPER_NAMES.has(name) ? `${name}_` : name;
+function safeDeclarationName(declared) {
+    /**
+     * **A character a component key cannot hold is `_`, as openapi3 writes the key**: `model Caf\u{e9}` is
+     * published as `Caf_`, its `createValidKey`. Written as declared, the name reached identifiers -
+     * `caf\u{e9}Schema`, `interface Caf\u{e9}` - in files this package keeps to printable ASCII, under a name the
+     * document does not use. `-` and `.`, which a key may hold and an identifier may not, are `_` too.
+     */
+    const name = declared.replace(/[^A-Za-z0-9_]/g, "_");
+    return RESERVED_DECLARATION_NAMES.has(name) ||
+        EMITTED_HELPER_NAMES.has(name) ||
+        LIBRARY_NAMES_WRITTEN_BARE.has(name)
+        ? `${name}_`
+        : name;
+}
+/**
+ * **The type a body is validated as: openapi3's effective payload type, at the body itself.**
+ * openapi3 resolves every request, response and part body through `getEffectivePayloadType`: what is
+ * left once metadata is set aside, matched to the model it all came from. `@body body: { ...Foo;
+ * @header h: string }` is `$ref Foo`, `Pet & {}` is `$ref Pet`; validated as written, the first
+ * required the header as a key and the second refused a subtype's own keys under sealing.
+ */
+function payloadTypeOf(program, type, payload, depth) {
+    if (!payload || depth !== 0 || type.kind !== "Model")
+        return type;
+    return metadataInfoOf(program).getEffectivePayloadType(type, currentVisibility());
 }
-/** A type earns a name when the spec gave it one - anonymous shapes stay inline where they are used. */
+/**
+ * A type earns a name when the spec gave it one - anonymous shapes stay inline where they are used.
+ * The name the document publishes it under, before any visibility suffix: {@link nameAt} makes it
+ * the name it is emitted under.
+ */
 function declaredNameOf(program, type) {
+    /**
+     * **`@friendlyName` names a declaration, as openapi3's `getOpenAPITypeName` reads it first.**
+     * Read as the declared name, `@friendlyName("Dog") model Cat` was validated as `Dog` by the
+     * validator named `catSchema`, and two models swapping names swapped validators.
+     */
+    const named = type.kind === "Enum" || type.kind === "Union" ? getFriendlyName(program, type) : undefined;
     if (type.kind === "Enum")
-        return safeDeclarationName(type.name);
+        return named || type.name;
     /**
      * A named union earns a declaration too.
      *
@@ -178,17 +208,26 @@ function declaredNameOf(program, type) {
      * cross-field rule modelled as a discriminated union (which is how `@refine` is being replaced)
      * would silently stop being checked at the boundary.
      */
-    if (type.kind === "Union")
-        return type.name === undefined ? undefined : safeDeclarationName(type.name);
+    // An instance openapi3 cannot name is written out where it is used - see `isSpeakableInstance`.
+    if (type.kind === "Union") {
+        return type.name === undefined || !isSpeakableInstance(type) ? undefined : named || type.name;
+    }
     if (type.kind !== "Model")
         return undefined;
-    // `Array`/`Record` are TypeSpec's built-in generic containers, not names worth exporting.
-    if (type.name === "Array" || type.name === "Record")
+    // A list literal is written out where it is used - see `isArrayLiteral`; `Record<T>` is an
+    // instance, and the standard library's own. A spec's model of either name is published by it.
+    if (isArrayLiteral(program, type))
+        return undefined;
+    if (type.name === "Record" && program.checker.isStdType(type))
+        return undefined;
+    /**
+     * **An anonymous model is written out where it is used**, as openapi3 writes `{ ...Pet }`: the one
+     * it names is the model a body resolves to, its effective payload type - see `payloadTypeOf` -
+     * which is that model, not the copy. Named after its source anywhere else, a property typed
+     * `{ ...Pet }` was a discriminated base, and refused with `Pet` where `Pet` was split.
+     */
+    if (type.name === "")
         return undefined;
-    if (type.name === "") {
-        const spread = spreadSourceName(type);
-        return spread === undefined ? undefined : safeDeclarationName(spread);
-    }
     /**
      * **A template INSTANTIATION carries the template's name, and it is not a declaration - unless
      * `@friendlyName` gives it one of its own.**
@@ -211,11 +250,133 @@ function declaredNameOf(program, type) {
      */
     if (type.templateMapper !== undefined) {
         const friendly = getFriendlyName(program, type);
-        return friendly === undefined || friendly === "" ? undefined : safeDeclarationName(friendly);
+        return friendly === undefined || friendly === "" ? undefined : friendly;
     }
-    return safeDeclarationName(type.name);
+    const friendly = getFriendlyName(program, type);
+    return friendly === undefined || friendly === "" ? type.name : friendly;
 }
 const lowerFirst = (value) => value.charAt(0).toLowerCase() + value.slice(1);
+/**
+ * `duplicate-declaration`, once per name whichever walk meets it first, saying which of the three it
+ * is: two types of one name; one model in two metadata contexts; or one model at two visibilities
+ * openapi3 names alike - PATCH at `Update` and at `Update` with `Patch`, both `XUpdate`.
+ */
+function reportCollision(program, name, first, second) {
+    const target = second.type ?? first.type ?? second.synthetic?.site ?? first.synthetic?.site;
+    if (target === undefined || !firstReportOf(program, "duplicate-declaration", target, name))
+        return;
+    /**
+     * **A shape no type stands for, beside another under its name**: a multipart body, whose parts
+     * are text and files, and an envelope openapi3 names after its union and variant.
+     */
+    const synthetic = first.synthetic ?? second.synthetic;
+    if (synthetic !== undefined) {
+        reportDiagnostic(program, {
+            code: "duplicate-declaration",
+            messageId: synthetic.kind,
+            format: { name },
+            target,
+        });
+        return;
+    }
+    // The declaration's own model: a copy the compiler makes for a payload has no source.
+    if (first.type === second.type) {
+        // A union published in a multipart part's binary context and outside it - see `withMultipartBinary`.
+        const binary = (key) => key?.endsWith("\u0000multipart") === true;
+        if (binary(first.key) !== binary(second.key)) {
+            reportDiagnostic(program, {
+                code: "duplicate-declaration",
+                messageId: "binary",
+                format: { name },
+                target,
+            });
+            return;
+        }
+        const visibilities = first.at !== undefined && second.at !== undefined ? [first.at, second.at] : undefined;
+        if (visibilities === undefined || visibilities[0] === visibilities[1]) {
+            reportDiagnostic(program, {
+                code: "duplicate-declaration",
+                messageId: "context",
+                format: { name },
+                target,
+            });
+            return;
+        }
+        /**
+         * **The request's own view is published apart**, which is the remedy where openapi3 writes one
+         * model at a request's visibility and at another: `D extends B` sent once in a create body is
+         * written at `Create` and, through `B`'s derived models, at `Read`.
+         */
+        const view = visibilities
+            .map((each) => viewTemplateOf(each))
+            .find((template) => template !== undefined);
+        reportDiagnostic(program, {
+            code: "duplicate-declaration",
+            messageId: "visibility",
+            format: {
+                name,
+                first: visibilityName(visibilities[0] ?? Visibility.Read),
+                second: visibilityName(visibilities[1] ?? Visibility.Read),
+                remedy: view === undefined
+                    ? "Use the model at one of the two - for a PATCH, one 'implicitOptionality' setting - or give one use a model of its own."
+                    : first.type === undefined
+                        ? `Send the request its own '${view}<...>' view, which openapi3 publishes apart, or use the model at one of the two - for a PATCH, one 'implicitOptionality' setting.`
+                        : `Send the request its own view - ${viewRemedyOf(view, first.type)} and send it as the request's '@body' - which openapi3 publishes apart, or use the model at one of the two - for a PATCH, one 'implicitOptionality' setting.`,
+            },
+            target,
+        });
+        return;
+    }
+    /**
+     * **Which of four things made two types one name**, each told as it is: a validator is named for
+     * its type with the first letter lowered, so `Foo` and `foo` meet only there; a visibility suffix
+     * can spell another type's name, `Thing` at `Create` beside a `ThingCreate`; a character an
+     * identifier cannot hold is `_`, so `x-y` meets `x_y`; and a namespace is dropped. Every one was
+     * told as the last, in one namespace as in two.
+     */
+    const declaredName = (type) => type !== undefined && "name" in type && typeof type.name === "string" ? type.name : name;
+    const names = [declaredName(first.type), declaredName(second.type)];
+    if (first.typeName !== undefined &&
+        second.typeName !== undefined &&
+        first.typeName !== second.typeName) {
+        reportDiagnostic(program, {
+            code: "duplicate-declaration",
+            messageId: "cased",
+            format: { name, first: first.typeName, second: second.typeName },
+            target,
+        });
+        return;
+    }
+    const suffixed = [first, second].findIndex((each) => {
+        const bare = each.type === undefined ? undefined : declaredNameOf(program, each.type);
+        return bare !== undefined && safeDeclarationName(bare) !== name && each.at !== undefined;
+    });
+    if (suffixed !== -1) {
+        reportDiagnostic(program, {
+            code: "duplicate-declaration",
+            messageId: "suffixed",
+            format: {
+                name,
+                first: names[suffixed] ?? name,
+                second: names[1 - suffixed] ?? name,
+                at: visibilityName([first, second][suffixed]?.at ?? Visibility.Read),
+            },
+            target,
+        });
+        return;
+    }
+    // Two instances of one template: openapi3 names a union instance after its template alone.
+    const template = (type) => type !== undefined && "templateMapper" in type && type.templateMapper !== undefined
+        ? type.node
+        : undefined;
+    const instances = template(first.type) !== undefined && template(first.type) === template(second.type);
+    reportDiagnostic(program, {
+        code: "duplicate-declaration",
+        messageId: instances ? "instances" : names[0] !== names[1] ? "renamed" : "default",
+        format: { name, first: names[0], second: names[1] },
+        target,
+    });
+}
 /**
  * One model can need MORE THAN ONE declaration.
  *
@@ -231,57 +392,83 @@ const lowerFirst = (value) => value.charAt(0).toLowerCase() + value.slice(1);
  * with the component names the document publishes.
  */
 /**
- * The visibility a type is actually DECLARED at, which is not always the one requested.
+ * The visibility a type is actually DECLARED at, which is not always the one requested - see
+ * `renderedVisibilityOf`, the one rule both registries name and render by.
  *
  * **A type not reshaped at this visibility IS the canonical declaration, not a copy of it.** Keying
  * on the requested visibility while only suffixing transformed types produced two cache entries
  * sharing one identifier and an emitted file that stopped parsing:
  * `Identifier 'approvalTierSchema' has already been declared`. An enum is the same enum in a request
- * and a response, which is what the `Model` guard is for.
- *
- * It is the same collapse `@typespec/openapi3` performs before naming a component, and
- * `isTransformedBy` is its own predicate, `metadataInfo.isTransformed`.
+ * and a response; a union holding a model the request reshapes is not, and was declared once for
+ * both - its response validating the create view - until unions were named by the same rule as
+ * models, as openapi3 names them.
  *
- * **Extracted so both registries answer it identically.** They must: the emitted assertion pairs a
- * validator with a contract type BY NAME, so a rule applied in one walk and paraphrased in the other
- * is a pairing that silently compares the wrong two things.
+ * **One rule for both registries.** The emitted assertion pairs a validator with a contract type BY
+ * NAME, so a rule applied in one walk and paraphrased in the other is a pairing that silently
+ * compares the wrong two things.
  */
-export function visibilityFor(program, type, requested) {
-    return type.kind === "Model" &&
-        requested !== Visibility.Read &&
-        isTransformedBy(program, type, requested)
-        ? requested
-        : Visibility.Read;
-}
 /**
- * A declaration's name at a visibility: the bare name at canonical, suffixed anywhere else.
+ * A declaration's name at a visibility: the bare name at canonical, and suffixed elsewhere only where
+ * the type is used at more than one visibility - openapi3's own rule, so a model only ever sent in a
+ * create body is `Holder` and not `HolderCreate`, as the document names it.
  *
  * The suffix is `@typespec/http`'s `getVisibilitySuffix`, called with `Visibility.Read` as the
  * canonical exactly as `@typespec/openapi3` calls it in `schema-emitter.ts`. Same function, same
- * argument, so these identifiers line up with the component names the document publishes rather than
- * merely resembling them.
+ * argument, same usage rule, so these identifiers line up with the component names the document
+ * publishes rather than merely resembling them.
+ */
+/**
+ * **The visibility a type is rendered at, by where it is asked for.** An operation's own body,
+ * parameter or response - asked for with no body being rendered - is collapsed as openapi3 collapses
+ * a root, whatever kind of type it is; a type another refers to is reduced where openapi3 reduces a
+ * reference. They differ for a list and a union expression, which openapi3 reduces at the root and
+ * not below it.
  */
-export function nameAt(bare, at) {
-    return `${bare}${at === Visibility.Read ? "" : getVisibilitySuffix(at, Visibility.Read)}`;
+function visibilityAt(program, type, requested, depth) {
+    return depth === 0
+        ? rootVisibilityOf(program, type, requested)
+        : renderedVisibilityOf(program, type, requested);
 }
-function keyFor(type, visibility) {
+export function nameAt(bare, at, type, reading) {
     /**
-     * **Keyed on the SPREAD SOURCE where there is one, or one component gets two declarations.**
-     *
-     * `@typespec/http` synthesises a fresh anonymous model per position, so two operations taking the
-     * same body produce two distinct types that both resolve to the name `BodyModel` - and
-     * `parameters/body-optionality` emitted `export const bodyModelSchema` twice, a file that does not
-     * parse. The document has exactly one `BodyModel` component; collapsing onto the source is what
-     * makes the two artefacts agree about how many things there are.
+     * **A 3.0 request's reading of a shared schema is named for the request**, `WidgetCreate` beside
+     * the `Widget` a response reads: the document publishes one component and OAS 3.0 reads it two
+     * ways - see `withRequestReading` - so the module declares both, the request's under the name
+     * openapi3 gives a view of the type at that visibility.
      */
-    const canonical = canonicalTypeFor(type);
-    return `${String(visibility)}\u0000${String(canonical.name ?? "")}\u0000${identityOf(canonical)}`;
+    if (reading !== undefined) {
+        return safeDeclarationName(`${bare}${getVisibilitySuffix(reading, Visibility.Read)}`);
+    }
+    // Suffixed only where openapi3 suffixes it: used at more than one visibility - see `isSuffixedByUsage`.
+    const suffixed = at !== Visibility.Read && isSuffixedByUsage(type);
+    return safeDeclarationName(`${bare}${suffixed ? getVisibilitySuffix(at, Visibility.Read) : ""}`);
 }
-/** The model an anonymous payload stands for, so every projection of it shares one declaration. */
-function canonicalTypeFor(type) {
-    if (type.kind !== "Model" || type.name !== "")
-        return type;
-    return spreadSourceOf(type) ?? type;
+/**
+ * **The 3.0 request a shared schema is read apart for here**, or `undefined`: only a type rendered at
+ * `Read` is shared with a response, and only one reaching a required read-only property reads apart -
+ * see `requestReadsApart`. A view openapi3 publishes for a request's own visibility drops read-only
+ * properties already, and the shared types it holds are read apart as they are reached.
+ */
+function readingOf(program, type, at) {
+    const reading = requestReadingAt();
+    return reading !== undefined && at === Visibility.Read && requestReadsApart(program, type, at)
+        ? reading
+        : undefined;
+}
+function keyFor(type, visibility, reading) {
+    /**
+     * **Keyed on the named model, never a copy of it**: `@typespec/http` synthesises a fresh anonymous
+     * model per position, and two operations taking one body each hand over a copy. Both resolve to
+     * the model itself, their effective payload type - see `payloadTypeOf` - so the document's one
+     * `BodyModel` is one declaration, where two copies of it once emitted `bodyModelSchema` twice.
+     */
+    // Inside an explicit `@body` a type can render differently - see `withMetadataAnnotationsIgnored`.
+    const body = metadataAnnotationsIgnored() ? "\u0000body" : "";
+    // And inside a multipart part's union holding raw `bytes` - see `withMultipartBinary`.
+    const binary = multipartBinaryContext() ? "\u0000multipart" : "";
+    // And a 3.0 request's reading of a shared schema - see `readingOf`.
+    const request = reading === undefined ? "" : `\u0000request${String(reading)}`;
+    return `${String(visibility)}\u0000${String(type.name ?? "")}\u0000${identityOf(type)}${body}${binary}${request}`;
 }
 /** A stable per-type identity, since two models can share a name across namespaces. */
 const identities = new WeakMap();
@@ -302,6 +489,12 @@ 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();
+    /** Identifiers refused as two shapes under one name, which no dispatch may hold. */
+    #refused = new Set();
+    /** Declarations refused as `split-visibility`, which a `@oneOf` holding them holds to nothing. */
+    #withheld = new Set();
+    /** Every type name a refused identifier stood for: `Foo` and `foo` are both `fooSchema`. */
+    #refusedTypeNames = new Set();
     /**
      * Inlined types currently being walked, by identity, against the number of declarations that were
      * in flight when each was entered.
@@ -315,6 +508,8 @@ export class SchemaRegistry {
      * entered since, the cycle has a name to close on and the walk may continue.
      */
     #inlineInProgress = new Map();
+    /** How many bodies are being rendered - none, and the type asked for is an operation's own. */
+    #depth = 0;
     constructor(program) {
         this.#program = program;
     }
@@ -323,8 +518,20 @@ export class SchemaRegistry {
      * inline source. Declaring is depth-first so a model's dependencies are emitted above it, which is
      * what lets the generated file be plain `const` declarations with no forward references.
      */
-    expressionFor(type) {
+    expressionFor(given, payload = false) {
+        const type = payloadTypeOf(this.#program, given, payload, this.#depth);
+        // Published as a reference to another document, with no schema to validate.
+        const external = externalReferenceOf(type);
+        if (external !== undefined)
+            return refuseExternalReference(this.#program, type, external);
         const bare = declaredNameOf(this.#program, type);
+        const requested = currentVisibility();
+        /**
+         * Asked of the model a declaration stands for, as openapi3 asks it of the effective payload type:
+         * a spread body's copy holds only what the request sends, so it is reshaped by nothing, while the
+         * model it copies - its `@path` property payload at `Read` - is.
+         */
+        const at = visibilityAt(this.#program, type, requested, this.#depth);
         if (bare === undefined) {
             /**
              * **A back edge to an INLINED type is a cycle with no name to close it**, and following it
@@ -342,7 +549,7 @@ export class SchemaRegistry {
             }
             this.#inlineInProgress.set(type, this.#inProgress.size);
             try {
-                return this.#inline(type);
+                return this.#inline(type, at, undefined);
             }
             finally {
                 this.#inlineInProgress.delete(type);
@@ -357,8 +564,8 @@ export class SchemaRegistry {
          * request and a response. Collapsing onto `Read` first is what makes the key and the name agree,
          * and it is the same collapse openapi3 performs before naming a component.
          */
-        const at = visibilityFor(this.#program, type, currentVisibility());
-        const key = keyFor(type, at);
+        const reading = readingOf(this.#program, type, at);
+        const key = keyFor(type, at, reading);
         const existing = this.#declarations.get(key);
         if (existing !== undefined)
             return existing.identifier;
@@ -383,34 +590,21 @@ export class SchemaRegistry {
                 this.#cyclic.add(inFlight);
             return pending;
         }
-        const name = nameAt(bare, at);
+        const name = nameAt(bare, at, type, reading);
         const identifier = `${lowerFirst(name)}Schema`;
-        this.#inProgress.set(key, identifier);
-        const rendered = captureBackEdges(() => this.#inline(type));
-        this.#inProgress.delete(key);
-        /**
-         * A back edge that survived the whole body reached this declaration by a path with no object
-         * property on it - a named union variant, or a dictionary value - so nothing could make it lazy
-         * and the emitted `const` would read itself while initialising. `z.lazy()` defers the whole body
-         * instead, which is the only place left to put the deferral once no property can hold it.
-         */
-        /**
-         * **The description goes on the declaration's own body, so the exported const IS the
-         * described schema.** Every reference then names that one instance, which is what keeps
-         * identity, `z.compile`'s clone (it inherits the description through its parent link) and
-         * Zod's `$ref` extraction all intact. Described at a reference instead, each use would be a
-         * fresh clone. Read from the canonical type, because an anonymous payload has its doc only on
-         * the model it was spread from, and a visibility projection carries the doc of the model it
-         * projects - as openapi3 publishes one component for both.
-         */
-        const body = rendered.deferred ? `z.lazy(() => ${rendered.value})` : rendered.value;
-        const source = described(body, getDoc(this.#program, canonicalTypeFor(type)));
+        const { source, deferred, consulted } = this.#render(type, at, name, key, identifier);
         const declaration = {
             identifier,
             typeName: name,
             source,
-            ...(this.#cyclic.has(key) ? { structural: this.#structuralBodyOf(type) } : {}),
-            ...(rendered.deferred ? { annotated: true } : {}),
+            type,
+            at,
+            key,
+            ignore: metadataAnnotationsIgnored(),
+            ...(reading === undefined ? {} : { reading }),
+            ...(this.#cyclic.has(key) ? { structural: this.#structuralBodyOf(type, at) } : {}),
+            ...(deferred ? { annotated: true } : {}),
+            ...(consulted.size === 0 ? {} : { consulted }),
         };
         /**
          * **Two different types can resolve to one identifier, and the module then does not parse.**
@@ -429,19 +623,191 @@ export class SchemaRegistry {
          * `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,
-            });
+        const twin = this.#order.find((candidate) => candidate.identifier === identifier);
+        /**
+         * **One declaration reached in two contexts that render it alike is one declaration.** A type
+         * under an explicit `@body` is keyed apart from the same type elsewhere, since the body can
+         * publish a `@header` as data; where nothing in it does, the two are the same text and the
+         * document's one component.
+         */
+        if (twin !== undefined && twin.source === declaration.source) {
+            this.#declarations.set(key, twin);
+            return twin.identifier;
+        }
+        if (twin !== undefined) {
+            reportCollision(this.#program, name, twin, declaration);
+            /**
+             * **One name, one declaration, and it validates nothing.** Two differing shapes under one
+             * identifier was a module declaring it twice, which does not parse. The document holds one
+             * of them under the name and openapi3 refuses its own document for it, so neither is kept.
+             */
+            const refused = {
+                identifier,
+                typeName: name,
+                source: UNREPRESENTABLE,
+                ...(twin.type === undefined ? {} : { type: twin.type }),
+                ...(twin.at === undefined ? {} : { at: twin.at }),
+            };
+            this.#order[this.#order.indexOf(twin)] = refused;
+            for (const [other, value] of this.#declarations) {
+                if (value === twin)
+                    this.#declarations.set(other, refused);
+            }
+            this.#declarations.set(key, refused);
+            this.#refused.add(identifier);
+            this.#refusedTypeNames.add(twin.typeName).add(name);
+            if (twin.type !== undefined)
+                this.#refuseEnvelopesOf(twin.type);
+            this.#renderDispatchesHolding(identifier);
+            return identifier;
         }
         this.#declarations.set(key, declaration);
         this.#order.push(declaration);
         this.#declareRelatives(type);
         return declaration.identifier;
     }
+    /**
+     * A declaration's body, rendered with its key in flight so a reference back to it is a back edge.
+     *
+     * A back edge that survived the whole body reached this declaration by a path with no object
+     * property on it - a named union variant, or a dictionary value - so nothing could make it lazy
+     * and the emitted `const` would read itself while initialising. `z.lazy()` defers the whole body
+     * instead, which is the only place left to put the deferral once no property can hold it.
+     */
+    #render(type, at, name, key, identifier) {
+        this.#inProgress.set(key, identifier);
+        const consulted = new Set();
+        this.#consulted.push(consulted);
+        const rendered = (() => {
+            try {
+                return captureBackEdges(() => this.#inline(type, at, name));
+            }
+            finally {
+                this.#consulted.pop();
+            }
+        })();
+        this.#inProgress.delete(key);
+        if (rendered.value === UNREPRESENTABLE &&
+            isSplitByVisibility(this.#program, type, at, metadataAnnotationsIgnored(), name)) {
+            this.#withheld.add(identifier);
+        }
+        /**
+         * **The description goes on the declaration's own body, so the exported const IS the
+         * described schema.** Every reference then names that one instance, which is what keeps
+         * identity, `z.compile`'s clone (it inherits the description through its parent link) and
+         * Zod's `$ref` extraction all intact. Described at a reference instead, each use would be a
+         * fresh clone. A visibility projection carries the doc of the model it projects, as openapi3
+         * publishes one component for both.
+         */
+        const body = rendered.deferred ? `z.lazy(() => ${rendered.value})` : rendered.value;
+        const source = described(body, getDoc(this.#program, type));
+        return { source, deferred: rendered.deferred, consulted };
+    }
+    /**
+     * **Every dispatch rendered before a subtype it holds was refused, rendered again without it.** A
+     * refusal is found where the second shape under one name is declared, and a base's dispatch can
+     * already hold the first: `z.discriminatedUnion` given the `z.never()` the refusal leaves throws
+     * on every parse, and the module does not typecheck. Each is rendered in its own context, its key
+     * in flight, so a reference back to it is still a back edge.
+     */
+    /**
+     * **A union refused takes its envelopes with it.** openapi3 publishes each envelope wherever it
+     * publishes the union, under one name: where the union is two schemas under its one name, each
+     * envelope is too, and the document keeps the one written last - `DU7Y` with its `kind` and
+     * `value` optional, written from a PATCH - while its validator held the view it was first declared
+     * at, requiring both. Refused with the union, whose diagnostic says why; the contract types follow.
+     */
+    #refuseEnvelopesOf(union) {
+        for (const [index, declaration] of this.#order.entries()) {
+            if (declaration.synthetic?.kind !== "envelope" || declaration.synthetic.site !== union)
+                continue;
+            if (declaration.source === UNREPRESENTABLE)
+                continue;
+            const refused = { ...declaration, source: UNREPRESENTABLE };
+            this.#order[index] = refused;
+            for (const [other, value] of this.#declarations) {
+                if (value === declaration)
+                    this.#declarations.set(other, refused);
+            }
+            this.#refused.add(declaration.identifier);
+            this.#refusedTypeNames.add(declaration.typeName);
+        }
+    }
+    /** What a value rendered here may ask of the declarations it refers to - see `HeldDeclarations`. */
+    #held = {
+        refused: (expression) => this.#refused.has(expression),
+        annotated: (expression) => this.#order.some((declaration) => declaration.identifier === expression && declaration.annotated === true),
+        refusedAt: (type, at) => {
+            const key = keyFor(type, at, readingOf(this.#program, type, at));
+            this.#consulted.at(-1)?.add(key);
+            const declared = this.#declarations.get(key);
+            return (declared !== undefined &&
+                (this.#refused.has(declared.identifier) || this.#withheld.has(declared.identifier)));
+        },
+        holdsRefusalAt: (type, at) => {
+            const key = keyFor(type, at, readingOf(this.#program, type, at));
+            this.#consulted.at(-1)?.add(key);
+            const declared = this.#declarations.get(key);
+            return declared !== undefined && this.#reachesRefusal(declared.identifier, new Set());
+        },
+    };
+    /** Whether a declaration is refused, or its source refers to one that reaches a refusal. */
+    #reachesRefusal(identifier, seen) {
+        if (seen.has(identifier))
+            return false;
+        seen.add(identifier);
+        if (this.#refused.has(identifier) || this.#withheld.has(identifier))
+            return true;
+        const declaration = this.#order.find((each) => each.identifier === identifier);
+        if (declaration === undefined)
+            return false;
+        return [...declaration.source.matchAll(/[A-Za-z_$][\w$]*/g)].some(([name]) => name !== identifier && this.#declares(name) && this.#reachesRefusal(name, seen));
+    }
+    #declares(identifier) {
+        return this.#order.some((each) => each.identifier === identifier);
+    }
+    /** The keys each declaration in flight asked `refusedAt` of, innermost last. */
+    #consulted = [];
+    /** What the contract types' walk asks of these declarations, so a merge is `never` on both sides. */
+    get held() {
+        return this.#held;
+    }
+    #renderDispatchesHolding(identifier) {
+        const holds = new RegExp(`\\b${identifier}\\b`);
+        const refusedKeys = new Set([...this.#declarations]
+            .filter(([, value]) => value.identifier === identifier)
+            .map(([each]) => each));
+        // By index: rendering one again can declare more, which hold no refused subtype.
+        for (let index = 0; index < this.#order.length; index += 1) {
+            const held = this.#order[index];
+            const { type, at, key } = held;
+            if (type === undefined || at === undefined || key === undefined)
+                continue;
+            // A dispatch, or a `@oneOf` that now holds a refused member - see `holdsRefusedMember` -
+            // directly or through the declarations it refers to.
+            const dispatches = (held.source.includes("z.discriminatedUnion(") || held.source.includes("z.xor(")) &&
+                (holds.test(held.source) || this.#reachesRefusal(held.identifier, new Set()));
+            // A merge that asked before the refusal holds the shape it now refuses - see `refusedAt`.
+            const merges = [...(held.consulted ?? [])].some((each) => refusedKeys.has(each));
+            if (!dispatches && !merges)
+                continue;
+            const keys = [...this.#declarations]
+                .filter(([, value]) => value === held)
+                .map(([each]) => each);
+            for (const each of keys)
+                this.#declarations.delete(each);
+            const { source, deferred, consulted } = withRequestReadingAs(held.reading, () => withMetadataAnnotationsIgnored(held.ignore ?? false, () => this.#render(type, at, held.typeName, key, held.identifier)));
+            const fresh = {
+                ...held,
+                source,
+                ...(deferred ? { annotated: true } : {}),
+                consulted,
+            };
+            this.#order[index] = fresh;
+            for (const each of keys)
+                this.#declarations.set(each, fresh);
+        }
+    }
     /**
      * Declare the BASE CHAIN a component's own declaration implies.
      *
@@ -451,8 +817,8 @@ export class SchemaRegistry {
      * them.
      *
      * **Subtypes are deliberately NOT walked here, because nothing would be walking them.** A
-     * discriminated base renders as a dispatch over its subtypes - `z.discriminatedUnion`, beside a base
-     * arm where its discriminator is open - and rendering that already asks the registry for each one. A loop here looked load-bearing and was measured not to
+     * discriminated base renders as a dispatch over its subtypes - `z.discriminatedUnion`, beside the base
+     * itself - and rendering that already asks the registry for each one. A loop here looked load-bearing and was measured not to
      * be: removing it left all 23 polymorphism and differential arms green.
      *
      * **Wrapped in {@link captureBackEdges} and the result discarded.** This call can land on a
@@ -466,14 +832,35 @@ export class SchemaRegistry {
         const base = type.baseModel;
         captureBackEdges(() => this.expressionFor(base));
     }
+    /**
+     * Declare a component the document publishes, at the visibility the walk is at, as a type
+     * another refers to - see `publishedComponents`. Nothing refers to it here, so a declaration
+     * still in flight is no back edge.
+     */
+    declare(type) {
+        this.#depth += 1;
+        try {
+            captureBackEdges(() => this.expressionFor(type));
+        }
+        finally {
+            this.#depth -= 1;
+        }
+    }
     /**
      * The Zod for a single property, constraints and optionality included.
      *
      * Used for path/query parameters, which are `ModelProperty`s that belong to no model - so they
      * need the property-level walk rather than the type-level one, or `@minLength` on a path param
      * would be documented and never enforced.
+     *
+     * **The property is where a refusal inside it points**, as a model's member is - see
+     * `withDeclarationSite`. A parameter is walked outside any model, so `@query a?: never[]` was
+     * reported at `<unknown location>:1:1`, the intrinsic's own place, which names nothing to edit.
      */
-    expressionForProperty(property) {
+    expressionForProperty(property, position = OWN_POSITION) {
+        return withParameterPosition(true, () => withDeclarationSite(property, () => this.#parameter(property, position)));
+    }
+    #parameter(property, position) {
         return withRefResolver(
         /**
          * **Every candidate goes through {@link expressionFor}, including the ones with no name.**
@@ -485,7 +872,7 @@ export class SchemaRegistry {
          * `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));
+        (candidate) => this.expressionFor(candidate), () => withHeldDeclarations(this.#held, () => propertyToZod(this.#program, property, position)));
     }
     /**
      * A declaration for a shape the spec never wrote, under a name the document publishes.
@@ -499,10 +886,12 @@ export class SchemaRegistry {
      * body: the document publishes `MultiPartRequest` as a component, and there is no walkable type
      * for it - the parts have to be assembled from `@typespec/http`'s own view of the payload.
      */
-    declareNamed(name, build) {
-        return this.#declareSynthetic(name, build);
+    declareNamed(name, build, site) {
+        return this.#declareSynthetic(name, build, { kind: "multipart", site });
     }
-    #declareSynthetic(name, build) {
+    #declareSynthetic(published, build, synthetic) {
+        // Under the rule every declaration's name is decided by - see `safeDeclarationName`.
+        const name = safeDeclarationName(published);
         const key = `synthetic\u0000${name}`;
         const existing = this.#declarations.get(key);
         if (existing !== undefined)
@@ -513,7 +902,31 @@ export class SchemaRegistry {
         this.#inProgress.set(key, identifier);
         const source = build();
         this.#inProgress.delete(key);
-        const declaration = { identifier, typeName: name, source };
+        const declaration = { identifier, typeName: name, source, synthetic };
+        /**
+         * **A name a type already declares is the same collision as any other**: a model sent as JSON
+         * and as a multipart form, its JSON component declared first, declared `formSchema` twice, and
+         * the module did not parse. One rendered alike is the one declaration.
+         */
+        const twin = this.#order.find((candidate) => candidate.identifier === identifier);
+        if (twin !== undefined && twin.source === source) {
+            this.#declarations.set(key, twin);
+            return identifier;
+        }
+        if (twin !== undefined) {
+            reportCollision(this.#program, name, twin, declaration);
+            const refused = { ...twin, source: UNREPRESENTABLE };
+            this.#order[this.#order.indexOf(twin)] = refused;
+            for (const [other, value] of this.#declarations) {
+                if (value === twin)
+                    this.#declarations.set(other, refused);
+            }
+            this.#declarations.set(key, refused);
+            this.#refused.add(identifier);
+            this.#refusedTypeNames.add(twin.typeName).add(name);
+            this.#renderDispatchesHolding(identifier);
+            return identifier;
+        }
         this.#declarations.set(key, declaration);
         this.#order.push(declaration);
         return identifier;
@@ -532,8 +945,27 @@ export class SchemaRegistry {
      * `wire-contract.gen.ts`, and a third spelling of "what this shape is" would be a third thing to
      * drift.
      */
-    #structuralBodyOf(type) {
-        return withTsRefResolver((candidate) => this.#typeNameOf(candidate), () => typeToTsBody(this.#program, type));
+    #structuralBodyOf(type, at) {
+        /**
+         * At the visibility the declaration is keyed on, as its body was rendered: read at the one it
+         * was requested at, a discriminated base reached from a create body annotated itself with
+         * `DogCreate`, a declaration nothing made.
+         */
+        return withVisibility(at, () => withParameterPosition(false, () => withTsRefResolver((candidate) => this.#typeNameOf(candidate) ?? this.#reducedBodyOf(candidate), () => typeToTsBody(this.#program, type))));
+    }
+    /**
+     * **A type with no declaration of its own is written out where openapi3 reduces it to**, as
+     * {@link TypeRegistry.expressionFor} writes it: `q?: Record<M4>` under a PATCH is a `Record`
+     * openapi3 renders at `Read`, its value `M4`. Walked at the PATCH, the annotation named
+     * `M4Update`, which nothing declares (`TS2552`). `undefined` where the visibility stands, so the
+     * walk goes on as it was.
+     */
+    #reducedBodyOf(candidate) {
+        const requested = currentVisibility();
+        const at = renderedVisibilityOf(this.#program, candidate, requested);
+        return at === requested
+            ? undefined
+            : withVisibility(at, () => typeToTsBody(this.#program, candidate));
     }
     /**
      * **The TypeScript name a reference resolves to is the one {@link expressionFor} declares it
@@ -546,7 +978,8 @@ export class SchemaRegistry {
         const bare = declaredNameOf(this.#program, candidate);
         if (bare === undefined)
             return undefined;
-        return nameAt(bare, visibilityFor(this.#program, candidate, currentVisibility()));
+        const at = renderedVisibilityOf(this.#program, candidate, currentVisibility());
+        return nameAt(bare, at, candidate, readingOf(this.#program, candidate, at));
     }
     /**
      * Render `type` without consulting its own declaration, but letting nested types use theirs.
@@ -558,8 +991,28 @@ export class SchemaRegistry {
      * `RangeError: Maximum call stack size exceeded`. Skipping the resolver once, here, is what makes
      * a nested occurrence resolve to the identifier while the body still renders as a body.
      */
-    #inline(type) {
-        return withRefResolver(
+    #inline(type, at, declared) {
+        // What openapi3 publishes with its properties read at another visibility - see `published.ts`.
+        const ignore = metadataAnnotationsIgnored();
+        if (isSplitByVisibility(this.#program, type, at, ignore, declared))
+            return UNREPRESENTABLE;
+        this.#depth += 1;
+        try {
+            // A declaration is a component every use shares, a parameter's included.
+            return declared === undefined
+                ? this.#body(type, at)
+                : withParameterPosition(false, () => this.#body(type, at));
+        }
+        finally {
+            this.#depth -= 1;
+        }
+    }
+    /** A model's body renders its own properties, outside a part's binary union - see `withMultipartBinary`. */
+    #body(type, at) {
+        return withMultipartBinary(multipartBinaryContext() && type.kind !== "Model", () => this.#bodyAt(type, at));
+    }
+    #bodyAt(type, at) {
+        return withVisibility(at, () => withRefResolver(
         /**
          * **Every candidate goes through {@link expressionFor}, including the ones with no name.**
          *
@@ -570,7 +1023,7 @@ export class SchemaRegistry {
          * `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))));
+        (candidate) => this.expressionFor(candidate), () => withDeferredAnnotator((property, position) => this.#deferredAnnotationOf(property, position), (variant) => this.#deferredTypeAnnotationOf(variant), () => withSyntheticDeclarations((name, build, site) => this.#declareSynthetic(name, build, { kind: "envelope", site }), () => withHeldDeclarations(this.#held, () => typeToZodBody(this.#program, type))))));
     }
     /**
      * The Zod type a property emitted as a getter is annotated with, or `undefined` for none.
@@ -587,18 +1040,32 @@ export class SchemaRegistry {
      * 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) {
+    #deferredAnnotationOf(property, position) {
         if (property.defaultValue !== undefined)
             return undefined;
-        const declared = withTsRefResolver((candidate) => this.#typeNameOf(candidate), () => propertyTypeToTs(this.#program, property));
+        const declared = withTsRefResolver((candidate) => this.#typeNameOf(candidate), () => propertyTypeToTs(this.#program, property, position));
         const core = `z.ZodType<${declared}, ${declared}>`;
-        const optional = property.optional || isOptionalAt(this.#program, property);
+        const optional = !position.required && (property.optional || isOptionalAt(this.#program, property));
         return `: ${optional ? `z.ZodExactOptional<${core}>` : core}`;
     }
+    /** The annotation for a deferred value no property declares - an envelope's variant. */
+    #deferredTypeAnnotationOf(type) {
+        const declared = withTsRefResolver((candidate) => this.#typeNameOf(candidate), () => typeToTs(this.#program, type));
+        return `: z.ZodType<${declared}, ${declared}>`;
+    }
     /** Every declaration, dependencies first. */
     declarations() {
         return this.#order;
     }
+    /** The names of the declarations that validate nothing, refused here or in the walk beneath. */
+    refusedNames() {
+        return new Set([
+            ...this.#refusedTypeNames,
+            ...this.#order
+                .filter((declaration) => declaration.source === UNREPRESENTABLE)
+                .map((declaration) => declaration.typeName),
+        ]);
+    }
 }
 /**
  * The same walk as {@link SchemaRegistry}, emitting plain TypeScript instead of Zod.
@@ -622,7 +1089,7 @@ export class SchemaRegistry {
  * whole body is a single `{...}`, whatever it contains. A composition operator cannot be missed,
  * because anything following the matching close brace fails the test whatever it happens to be.
  */
-function isSingleObjectLiteral(source) {
+export function isSingleObjectLiteral(source) {
     if (!source.startsWith("{"))
         return false;
     let depth = 0;
@@ -661,7 +1128,7 @@ export class TypeRegistry {
      * projection. The two registries pair BY NAME in the emitted assertion, so they have to agree
      * about how many declarations there are before the pairing means anything.
      *
-     * Both now go through the shared {@link visibilityFor} and {@link nameAt}: paraphrasing either
+     * Both now go through the shared `renderedVisibilityOf` and {@link nameAt}: paraphrasing either
      * rule in one walk is how a validator ends up compared against a type describing something else.
      */
     #declarations = new Map();
@@ -675,26 +1142,47 @@ export class TypeRegistry {
      * Reported only by the schema walk, so one spec does not produce the same complaint twice.
      */
     #inlineInProgress = new Map();
-    constructor(program) {
+    /** How many bodies are being rendered - see the schema registry's. */
+    #depth = 0;
+    /** The validators' declarations, whose refusals a merge here holds to as theirs do. */
+    #held;
+    constructor(program, held) {
         this.#program = program;
+        this.#held = held ?? {
+            refused: () => false,
+            annotated: () => false,
+            refusedAt: () => false,
+            holdsRefusalAt: () => false,
+        };
     }
-    expressionFor(type) {
+    expressionFor(given, payload = false) {
+        const type = payloadTypeOf(this.#program, given, payload, this.#depth);
+        // Refused by the schema walk, which reports it - see `externalReferenceOf`.
+        if (externalReferenceOf(type) !== undefined)
+            return "never";
         const bare = declaredNameOf(this.#program, type);
+        const requested = currentVisibility();
+        /**
+         * Asked of the model a declaration stands for, as openapi3 asks it of the effective payload type:
+         * a spread body's copy holds only what the request sends, so it is reshaped by nothing, while the
+         * model it copies - its `@path` property payload at `Read` - is.
+         */
+        const at = visibilityAt(this.#program, type, requested, this.#depth);
         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);
+                return this.#inline(type, at, undefined);
             }
             finally {
                 this.#inlineInProgress.delete(type);
             }
         }
-        const at = visibilityFor(this.#program, type, currentVisibility());
-        const key = keyFor(type, at);
-        const name = nameAt(bare, at);
+        const reading = readingOf(this.#program, type, at);
+        const key = keyFor(type, at, reading);
+        const name = nameAt(bare, at, type, reading);
         const existing = this.#declarations.get(key);
         if (existing !== undefined)
             return existing.name;
@@ -712,10 +1200,11 @@ export class TypeRegistry {
         if (pending !== undefined)
             return pending;
         this.#inProgress.set(key, name);
-        const source = this.#inline(type);
+        const source = this.#inline(type, at, name);
         this.#inProgress.delete(key);
         const declaration = {
             name,
+            type,
             /**
              * Only a plain object literal can be an `interface`. A permissive response is
              * `{ ...pinned } & Record<string, unknown>`, and `export interface X { ... } & ...` does not parse -
@@ -738,6 +1227,7 @@ export class TypeRegistry {
              */
             isVocabulary: type.kind === "Enum",
             source,
+            at,
         };
         this.#declarations.set(key, declaration);
         /**
@@ -759,14 +1249,27 @@ export class TypeRegistry {
             this.#order.push(declaration);
         }
         else if (sameName.source !== declaration.source) {
-            reportDiagnostic(this.#program, {
-                code: "duplicate-declaration",
-                format: { name: declaration.name },
-                target: type,
-            });
+            // Refused as the schema registry refuses it - one declaration, of nothing.
+            reportCollision(this.#program, declaration.name, sameName, declaration);
+            const refused = { ...sameName, source: "never", isObject: false };
+            this.#order[this.#order.indexOf(sameName)] = refused;
+            for (const [other, value] of this.#declarations) {
+                if (value === sameName || value === declaration)
+                    this.#declarations.set(other, refused);
+            }
         }
         return declaration.name;
     }
+    /** Declare a component the document publishes, as {@link SchemaRegistry.declare} does. */
+    declare(type) {
+        this.#depth += 1;
+        try {
+            this.expressionFor(type);
+        }
+        finally {
+            this.#depth -= 1;
+        }
+    }
     /**
      * The Zod-free type for a single property - used for path and query parameters, which are
      * `ModelProperty`s belonging to no model. Without routing them through the registry a named model
@@ -774,17 +1277,102 @@ export class TypeRegistry {
      */
     /** `wireName` names an HTTP parameter as the wire does - see {@link propertyToTs}. */
     expressionForProperty(property, wireName) {
-        return withTsRefResolver(
+        return withParameterPosition(true, () => withTsRefResolver(
         // Through expressionFor even when undeclared, so the cycle guard above is reachable.
-        (candidate) => this.expressionFor(candidate), () => propertyToTs(this.#program, property, wireName));
+        (candidate) => this.expressionFor(candidate), () => 
+        // A refusal points at the property, as the schema walk's does.
+        withDeclarationSite(property, () => withHeldDeclarations(this.#held, () => propertyToTs(this.#program, property, wireName)))));
+    }
+    #inline(type, at, declared) {
+        // Refused as the schema registry refuses it, which reports it.
+        const ignore = metadataAnnotationsIgnored();
+        if (isSplitByVisibility(this.#program, type, at, ignore, declared))
+            return "never";
+        this.#depth += 1;
+        try {
+            // A declaration is a component every use shares, a parameter's included.
+            return declared === undefined
+                ? this.#body(type, at)
+                : withParameterPosition(false, () => this.#body(type, at));
+        }
+        finally {
+            this.#depth -= 1;
+        }
+    }
+    /** A model's body renders its own properties, outside a part's binary union - see `withMultipartBinary`. */
+    #body(type, at) {
+        return withMultipartBinary(multipartBinaryContext() && type.kind !== "Model", () => this.#bodyAt(type, at));
     }
-    #inline(type) {
-        return withTsRefResolver(
+    #bodyAt(type, at) {
+        return withVisibility(at, () => withTsRefResolver(
         // Through expressionFor even when undeclared, so the cycle guard above is reachable.
-        (candidate) => this.expressionFor(candidate), () => typeToTsBody(this.#program, type));
+        (candidate) => this.expressionFor(candidate), () => withTsSyntheticDeclarations((name, build, site) => this.#declareSynthetic(name, build, { kind: "envelope", site }), () => withHeldDeclarations(this.#held, () => typeToTsBody(this.#program, type)))));
+    }
+    /** A multipart body's type, under the component's name - see {@link SchemaRegistry.declareNamed}. */
+    declareNamed(name, build, site) {
+        return this.#declareSynthetic(name, build, { kind: "multipart", site });
+    }
+    /** A type for a shape the spec never wrote, as {@link SchemaRegistry.declareNamed} declares one. */
+    #declareSynthetic(published, build, synthetic) {
+        // Under the rule every declaration's name is decided by - see `safeDeclarationName`.
+        const name = safeDeclarationName(published);
+        const key = `synthetic\u0000${name}`;
+        const existing = this.#declarations.get(key);
+        if (existing !== undefined)
+            return existing.name;
+        if (this.#inProgress.has(key))
+            return name;
+        this.#inProgress.set(key, name);
+        const source = build();
+        this.#inProgress.delete(key);
+        const declaration = {
+            name,
+            isObject: isSingleObjectLiteral(source),
+            isVocabulary: false,
+            source,
+            synthetic,
+        };
+        // One name, one declaration, as the schema registry keeps it - see its `#declareSynthetic`.
+        const twin = this.#order.find((candidate) => candidate.name === name);
+        if (twin !== undefined && twin.source === source) {
+            this.#declarations.set(key, twin);
+            return name;
+        }
+        if (twin !== undefined) {
+            reportCollision(this.#program, name, twin, declaration);
+            const refused = { ...twin, source: "never", isObject: false };
+            this.#order[this.#order.indexOf(twin)] = refused;
+            for (const [other, value] of this.#declarations) {
+                if (value === twin)
+                    this.#declarations.set(other, refused);
+            }
+            this.#declarations.set(key, refused);
+            return name;
+        }
+        this.#declarations.set(key, declaration);
+        this.#order.push(declaration);
+        return name;
     }
     /** Every declaration, dependencies first. */
     declarations() {
         return this.#order;
     }
+    /**
+     * **A contract type whose validator validates nothing is `never` too**, whatever refused it: two
+     * shapes under one name, a union this emitter refuses, a model openapi3 publishes split. The wire
+     * assertion pairs the two by name, and a contract type stating a shape beside `z.never()` failed
+     * it - `interface HBase { name: string }` beside a refused `hBaseSchema`.
+     */
+    refuse(names) {
+        for (const [index, declaration] of this.#order.entries()) {
+            if (!names.has(declaration.name) || declaration.source === "never")
+                continue;
+            const refused = { ...declaration, source: "never", isObject: false };
+            this.#order[index] = refused;
+            for (const [key, value] of this.#declarations) {
+                if (value === declaration)
+                    this.#declarations.set(key, refused);
+            }
+        }
+    }
 }