typespec-http-zod 0.30.0 → 0.31.0

package/dist/src/lib.d.ts

@@ -132,17 +132,23 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
     "unsupported-type": {
         readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why", "remedy"]>;
     };
+    "invalid-default": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "why"]>;
+    };
     "unsupported-default": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;
     };
     "default-on-required-property": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
+        readonly discriminator: import("@typespec/compiler").CallableMessage<["name"]>;
+        readonly ancestor: import("@typespec/compiler").CallableMessage<["name"]>;
     };
     "truncated-doc-comment": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "tag", "tag"]>;
     };
     "undeclared-discriminator": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "property", "variant", "property", "variant"]>;
+        readonly open: import("@typespec/compiler").CallableMessage<["name", "property", "variant", "property", "variant"]>;
     };
     "empty-union": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;
@@ -150,6 +156,17 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
     "unmirrorable-seal": {
         readonly default: import("@typespec/compiler").CallableMessage<["sealed", "open"]>;
     };
+    "invalid-subtype-discriminator": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "base", "property", "why", "property", "name", "property"]>;
+        readonly invisible: import("@typespec/compiler").CallableMessage<["name", "base", "property", "why", "property", "at", "name", "name", "property"]>;
+    };
+    "sealed-base-extended": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "base", "name", "base", "keys", "name", "name", "base"]>;
+    };
+    "unrepresentable-override": {
+        readonly default: import("@typespec/compiler").CallableMessage<["model", "name", "base", "declared", "why", "name", "model", "declared"]>;
+        readonly recursive: import("@typespec/compiler").CallableMessage<["model", "name", "base", "name", "name", "model", "declared"]>;
+    };
     "unknown-key-vocabulary": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "service"]>;
     };
@@ -159,8 +176,8 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
     "non-unicode-pattern": {
         readonly default: import("@typespec/compiler").CallableMessage<["pattern"]>;
     };
-    "unenforceable-encoded-bound": {
-        readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
+    "unenforceable-encoded-constraint": {
+        readonly default: import("@typespec/compiler").CallableMessage<["keywords", "name", "type", "keywords", "type"]>;
     };
     "unenforceable-property-name": {
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
@@ -174,31 +191,61 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
     "inline-cycle": {
         readonly default: import("@typespec/compiler").CallableMessage<["type"]>;
     };
-    "encode-cycle": {
-        readonly default: import("@typespec/compiler").CallableMessage<["type", "chain"]>;
+    "never-body": {
+        readonly default: import("@typespec/compiler").CallableMessage<["operationId", "position"]>;
+    };
+    "unsatisfiable-encoding": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "declared", "encoded", "why"]>;
+    };
+    "header-case-collision": {
+        readonly default: import("@typespec/compiler").CallableMessage<["operation", "first", "second"]>;
     };
     "shared-input-key": {
         readonly default: import("@typespec/compiler").CallableMessage<["operation", "first", "key", "second", "key", "key"]>;
+        readonly repeated: import("@typespec/compiler").CallableMessage<["operation", "first", "key"]>;
+    };
+    "split-visibility": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "via", "model", "at", "property", "effect", "name", "remedy"]>;
+        readonly inherited: import("@typespec/compiler").CallableMessage<["name", "model", "model", "via", "model", "at", "property", "effect", "remedy"]>;
+        readonly inline: import("@typespec/compiler").CallableMessage<["model", "at", "property", "effect", "remedy"]>;
+    };
+    "ambiguous-form-reading": {
+        readonly default: import("@typespec/compiler").CallableMessage<["operation", "union", "member", "key", "first", "second", "other", "key", "member", "other"]>;
     };
     "duplicate-declaration": {
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
+        readonly renamed: import("@typespec/compiler").CallableMessage<["first", "second", "name"]>;
+        readonly multipart: import("@typespec/compiler").CallableMessage<["name"]>;
+        readonly envelope: import("@typespec/compiler").CallableMessage<["name"]>;
+        readonly instances: import("@typespec/compiler").CallableMessage<["name", "name"]>;
+        readonly binary: import("@typespec/compiler").CallableMessage<["name"]>;
+        readonly cased: import("@typespec/compiler").CallableMessage<["first", "second", "name"]>;
+        readonly suffixed: import("@typespec/compiler").CallableMessage<["name", "first", "at", "second", "second"]>;
+        readonly visibility: import("@typespec/compiler").CallableMessage<["name", "first", "second", "remedy"]>;
+        readonly context: import("@typespec/compiler").CallableMessage<["name"]>;
     };
 }, EmitterOptions, never>;
-export declare const reportDiagnostic: <C extends "default-on-required-property" | "duplicate-declaration" | "duplicate-operation-id" | "empty-union" | "encode-cycle" | "inline-cycle" | "non-unicode-pattern" | "optional-prototype-name" | "shared-input-key" | "truncated-doc-comment" | "undeclared-discriminator" | "unenforceable-encoded-bound" | "unenforceable-property-name" | "unknown-key-vocabulary" | "unmirrorable-seal" | "unsupported-default" | "unsupported-status-code-range" | "unsupported-type", M extends keyof {
+export declare const reportDiagnostic: <C extends "ambiguous-form-reading" | "default-on-required-property" | "duplicate-declaration" | "duplicate-operation-id" | "empty-union" | "header-case-collision" | "inline-cycle" | "invalid-default" | "invalid-subtype-discriminator" | "never-body" | "non-unicode-pattern" | "optional-prototype-name" | "sealed-base-extended" | "shared-input-key" | "split-visibility" | "truncated-doc-comment" | "undeclared-discriminator" | "unenforceable-encoded-constraint" | "unenforceable-property-name" | "unknown-key-vocabulary" | "unmirrorable-seal" | "unrepresentable-override" | "unsatisfiable-encoding" | "unsupported-default" | "unsupported-status-code-range" | "unsupported-type", M extends keyof {
     "unsupported-type": {
         readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why", "remedy"]>;
     };
+    "invalid-default": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "why"]>;
+    };
     "unsupported-default": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;
     };
     "default-on-required-property": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
+        readonly discriminator: import("@typespec/compiler").CallableMessage<["name"]>;
+        readonly ancestor: import("@typespec/compiler").CallableMessage<["name"]>;
     };
     "truncated-doc-comment": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "tag", "tag"]>;
     };
     "undeclared-discriminator": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "property", "variant", "property", "variant"]>;
+        readonly open: import("@typespec/compiler").CallableMessage<["name", "property", "variant", "property", "variant"]>;
     };
     "empty-union": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;
@@ -206,6 +253,17 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "unmirrorable-seal": {
         readonly default: import("@typespec/compiler").CallableMessage<["sealed", "open"]>;
     };
+    "invalid-subtype-discriminator": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "base", "property", "why", "property", "name", "property"]>;
+        readonly invisible: import("@typespec/compiler").CallableMessage<["name", "base", "property", "why", "property", "at", "name", "name", "property"]>;
+    };
+    "sealed-base-extended": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "base", "name", "base", "keys", "name", "name", "base"]>;
+    };
+    "unrepresentable-override": {
+        readonly default: import("@typespec/compiler").CallableMessage<["model", "name", "base", "declared", "why", "name", "model", "declared"]>;
+        readonly recursive: import("@typespec/compiler").CallableMessage<["model", "name", "base", "name", "name", "model", "declared"]>;
+    };
     "unknown-key-vocabulary": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "service"]>;
     };
@@ -215,8 +273,8 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "non-unicode-pattern": {
         readonly default: import("@typespec/compiler").CallableMessage<["pattern"]>;
     };
-    "unenforceable-encoded-bound": {
-        readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
+    "unenforceable-encoded-constraint": {
+        readonly default: import("@typespec/compiler").CallableMessage<["keywords", "name", "type", "keywords", "type"]>;
     };
     "unenforceable-property-name": {
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
@@ -230,30 +288,60 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "inline-cycle": {
         readonly default: import("@typespec/compiler").CallableMessage<["type"]>;
     };
-    "encode-cycle": {
-        readonly default: import("@typespec/compiler").CallableMessage<["type", "chain"]>;
+    "never-body": {
+        readonly default: import("@typespec/compiler").CallableMessage<["operationId", "position"]>;
+    };
+    "unsatisfiable-encoding": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "declared", "encoded", "why"]>;
+    };
+    "header-case-collision": {
+        readonly default: import("@typespec/compiler").CallableMessage<["operation", "first", "second"]>;
     };
     "shared-input-key": {
         readonly default: import("@typespec/compiler").CallableMessage<["operation", "first", "key", "second", "key", "key"]>;
+        readonly repeated: import("@typespec/compiler").CallableMessage<["operation", "first", "key"]>;
+    };
+    "split-visibility": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "via", "model", "at", "property", "effect", "name", "remedy"]>;
+        readonly inherited: import("@typespec/compiler").CallableMessage<["name", "model", "model", "via", "model", "at", "property", "effect", "remedy"]>;
+        readonly inline: import("@typespec/compiler").CallableMessage<["model", "at", "property", "effect", "remedy"]>;
+    };
+    "ambiguous-form-reading": {
+        readonly default: import("@typespec/compiler").CallableMessage<["operation", "union", "member", "key", "first", "second", "other", "key", "member", "other"]>;
     };
     "duplicate-declaration": {
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
+        readonly renamed: import("@typespec/compiler").CallableMessage<["first", "second", "name"]>;
+        readonly multipart: import("@typespec/compiler").CallableMessage<["name"]>;
+        readonly envelope: import("@typespec/compiler").CallableMessage<["name"]>;
+        readonly instances: import("@typespec/compiler").CallableMessage<["name", "name"]>;
+        readonly binary: import("@typespec/compiler").CallableMessage<["name"]>;
+        readonly cased: import("@typespec/compiler").CallableMessage<["first", "second", "name"]>;
+        readonly suffixed: import("@typespec/compiler").CallableMessage<["name", "first", "at", "second", "second"]>;
+        readonly visibility: import("@typespec/compiler").CallableMessage<["name", "first", "second", "remedy"]>;
+        readonly context: import("@typespec/compiler").CallableMessage<["name"]>;
     };
 }[C]>(program: import("@typespec/compiler").Program, diag: import("@typespec/compiler").DiagnosticReport<{
     "unsupported-type": {
         readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why", "remedy"]>;
     };
+    "invalid-default": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "why"]>;
+    };
     "unsupported-default": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;
     };
     "default-on-required-property": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
+        readonly discriminator: import("@typespec/compiler").CallableMessage<["name"]>;
+        readonly ancestor: import("@typespec/compiler").CallableMessage<["name"]>;
     };
     "truncated-doc-comment": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "tag", "tag"]>;
     };
     "undeclared-discriminator": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "property", "variant", "property", "variant"]>;
+        readonly open: import("@typespec/compiler").CallableMessage<["name", "property", "variant", "property", "variant"]>;
     };
     "empty-union": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;
@@ -261,6 +349,17 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "unmirrorable-seal": {
         readonly default: import("@typespec/compiler").CallableMessage<["sealed", "open"]>;
     };
+    "invalid-subtype-discriminator": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "base", "property", "why", "property", "name", "property"]>;
+        readonly invisible: import("@typespec/compiler").CallableMessage<["name", "base", "property", "why", "property", "at", "name", "name", "property"]>;
+    };
+    "sealed-base-extended": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "base", "name", "base", "keys", "name", "name", "base"]>;
+    };
+    "unrepresentable-override": {
+        readonly default: import("@typespec/compiler").CallableMessage<["model", "name", "base", "declared", "why", "name", "model", "declared"]>;
+        readonly recursive: import("@typespec/compiler").CallableMessage<["model", "name", "base", "name", "name", "model", "declared"]>;
+    };
     "unknown-key-vocabulary": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "service"]>;
     };
@@ -270,8 +369,8 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "non-unicode-pattern": {
         readonly default: import("@typespec/compiler").CallableMessage<["pattern"]>;
     };
-    "unenforceable-encoded-bound": {
-        readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
+    "unenforceable-encoded-constraint": {
+        readonly default: import("@typespec/compiler").CallableMessage<["keywords", "name", "type", "keywords", "type"]>;
     };
     "unenforceable-property-name": {
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
@@ -285,13 +384,37 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "inline-cycle": {
         readonly default: import("@typespec/compiler").CallableMessage<["type"]>;
     };
-    "encode-cycle": {
-        readonly default: import("@typespec/compiler").CallableMessage<["type", "chain"]>;
+    "never-body": {
+        readonly default: import("@typespec/compiler").CallableMessage<["operationId", "position"]>;
+    };
+    "unsatisfiable-encoding": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "declared", "encoded", "why"]>;
+    };
+    "header-case-collision": {
+        readonly default: import("@typespec/compiler").CallableMessage<["operation", "first", "second"]>;
     };
     "shared-input-key": {
         readonly default: import("@typespec/compiler").CallableMessage<["operation", "first", "key", "second", "key", "key"]>;
+        readonly repeated: import("@typespec/compiler").CallableMessage<["operation", "first", "key"]>;
+    };
+    "split-visibility": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "via", "model", "at", "property", "effect", "name", "remedy"]>;
+        readonly inherited: import("@typespec/compiler").CallableMessage<["name", "model", "model", "via", "model", "at", "property", "effect", "remedy"]>;
+        readonly inline: import("@typespec/compiler").CallableMessage<["model", "at", "property", "effect", "remedy"]>;
+    };
+    "ambiguous-form-reading": {
+        readonly default: import("@typespec/compiler").CallableMessage<["operation", "union", "member", "key", "first", "second", "other", "key", "member", "other"]>;
     };
     "duplicate-declaration": {
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
+        readonly renamed: import("@typespec/compiler").CallableMessage<["first", "second", "name"]>;
+        readonly multipart: import("@typespec/compiler").CallableMessage<["name"]>;
+        readonly envelope: import("@typespec/compiler").CallableMessage<["name"]>;
+        readonly instances: import("@typespec/compiler").CallableMessage<["name", "name"]>;
+        readonly binary: import("@typespec/compiler").CallableMessage<["name"]>;
+        readonly cased: import("@typespec/compiler").CallableMessage<["first", "second", "name"]>;
+        readonly suffixed: import("@typespec/compiler").CallableMessage<["name", "first", "at", "second", "second"]>;
+        readonly visibility: import("@typespec/compiler").CallableMessage<["name", "first", "second", "remedy"]>;
+        readonly context: import("@typespec/compiler").CallableMessage<["name"]>;
     };
 }, C, M>) => void;

package/dist/src/lib.js

@@ -67,7 +67,21 @@ const diagnostics = {
     "unsupported-type": {
         severity: "error",
         messages: {
-            default: paramMessage `Cannot emit ${"artefact"} for ${"kind"}: ${"why"}. Replace it with a type a value can inhabit. ${"remedy"}`,
+            default: paramMessage `Cannot emit ${"artefact"} for ${"kind"}: ${"why"}. Replace or remove the declaration: ${"remedy"}`,
+        },
+    },
+    /**
+     * **A default that is no value the position accepts.** openapi3 publishes a default as the JSON it
+     * serializes, beside a schema the default need not satisfy - an encoding can change the type
+     * under it, a constraint can rule out the literal it names, a key it sets can be one the position
+     * does not declare. Filled in, it handed the handler a value its own type refuses, and the module
+     * did not compile. A warning, because the property itself is still validated as the document
+     * says; only the fallback is dropped.
+     */
+    "invalid-default": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `The default of '${"name"}' is not emitted: ${"why"}, so filling it in would hand the handler a value the property refuses. Replace it with a value the property accepts, or remove it.`,
         },
     },
     "unsupported-default": {
@@ -110,6 +124,8 @@ const diagnostics = {
         severity: "warning",
         messages: {
             default: paramMessage `'${"name"}' is required, so its default can never apply: a required property is never absent. The OpenAPI document publishes it in 'required' and carries the default only as an annotation, and this validator does the same - a request omitting '${"name"}' is refused. Declare it optional, '${"name"}?: ... = ...', if callers may omit it.`,
+            discriminator: paramMessage `'${"name"}' is a discriminator, which '@typespec/openapi3' always publishes in its base's 'required', so it is required here however it is declared and its default can never apply. The validator refuses a value omitting it, as the document does. Remove the '?' and the default.`,
+            ancestor: paramMessage `'${"name"}' is required by a declaration of its key above it, which the document holds the value to through 'allOf', so it is required here however it is declared and its default can never apply. The validator refuses a value omitting it, as the document does. Remove the '?' and the default, or make the declaration above optional.`,
         },
     },
     /**
@@ -184,6 +200,7 @@ const diagnostics = {
         severity: "error",
         messages: {
             default: paramMessage `'${"name"}' serialises with '${"property"}' inside each variant, but '${"variant"}' does not declare it - so the OpenAPI document omits it, which OpenAPI 3.1 forbids for a discriminator ("the discriminator field MUST be a required field"). Emitting a validator that required it anyway would enforce a rule the published contract does not state. Declare '${"property"}' on '${"variant"}'.`,
+            open: paramMessage `'${"name"}' serialises with '${"property"}' inside each variant, but '${"variant"}' declares it as no one fixed value, so nothing can tell its values from another variant's and no dispatch can hold it. Declare '${"property"}' on '${"variant"}' as the literal its variant name says.`,
         },
     },
     "empty-union": {
@@ -220,6 +237,60 @@ const diagnostics = {
             default: paramMessage `'seal-object-schemas' resolves to true for ${"sealed"} and false for ${"open"}, and '@typespec/openapi3' has no per-service options - it applies one value to the whole program. So one of these services would publish a document that disagrees with the validator emitted beside it. Give every service the same value, or split the surfaces into separate compiles.`,
         },
     },
+    /**
+     * **A model a discriminated base's `mapping` names, which no dispatch can hold.**
+     *
+     * The mapping names a subtype for the values its discriminator fixes, and a dispatch reads one
+     * fixed value per subtype. A subtype whose discriminator is not fixed - `"lab" | string`, or `kind`
+     * renamed with `@encodedName` so its base's open `string` is what it publishes - made Zod throw
+     * "Invalid discriminated union option" on import or on the first parse. A subtype whose value a
+     * declaration above it refuses - `kind: "cobra"` under `@maxLength(3)` - is published as `allOf`
+     * that declaration, so no value is one, and was accepted.
+     *
+     * **An error, as `undeclared-discriminator` is**: the spec says something the document cannot
+     * hold as a dispatch, so it is refused rather than read some other way, and the base dispatches to
+     * its other subtypes until it is fixed.
+     */
+    "invalid-subtype-discriminator": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"name"}' is named by the mapping of '${"base"}''s discriminator '${"property"}', and ${"why"}. Declare '${"property"}' on '${"name"}' as one fixed value that every declaration of '${"property"}' above it admits.`,
+            invisible: paramMessage `'${"name"}' is named by the mapping of '${"base"}''s discriminator '${"property"}', and ${"why"}. Make '${"property"}' visible at '${"at"}' on '${"name"}' and every model above it that declares it: a value is told as a '${"name"}' by its '${"property"}'.`,
+        },
+    },
+    /**
+     * **A template instance that adds properties to a base openapi3 seals.**
+     *
+     * openapi3 seals a model with no derived models it publishes, and does not count a template
+     * instance as one, so under `seal-object-schemas` `Pet<string> extends Animal` leaves `Animal`
+     * sealed. `Pet<string>` is published as `allOf` that sealed `Animal`, whose own
+     * `unevaluatedProperties` cannot see `Pet<string>`'s properties - so the document refuses every
+     * value carrying one. An error, because the published schema refuses what the spec declares, and
+     * no validator can agree with both.
+     */
+    "sealed-base-extended": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"name"}' extends '${"base"}', which '@typespec/openapi3' seals under 'seal-object-schemas' because it does not count a template instance as a derived model. The document publishes '${"name"}' as 'allOf' the sealed '${"base"}', so it refuses every value carrying ${"keys"}, which '${"name"}' adds. Declare it as a model of its own with 'model ... is ${"name"}', which openapi3 counts as derived and so leaves '${"base"}' open.`,
+        },
+    },
+    /**
+     * **A redeclared property no one validator can hold to both of its declarations.**
+     *
+     * openapi3 publishes a subtype as `allOf` its base, so a property the subtype redeclares must meet
+     * every declaration of it. Where the subtype's narrows the base's - a derived scalar, a model that
+     * extends it, a literal the base admits - the base's constraints are applied to the subtype's
+     * value. Where it does not - a model that only looks like the base's, a scalar that is not one of
+     * the base's - the value is held to two schemas, and intersecting them in Zod merged sealed
+     * objects' keys and threw on two defaults. Refused rather than read some other way.
+     */
+    "unrepresentable-override": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"model"}' redeclares '${"name"}', which '${"base"}' declares as '${"declared"}', and ${"why"}: the document holds the value to both, and no one validator here can. Declare '${"name"}' on '${"model"}' as '${"declared"}', or as a type derived from it.`,
+            recursive: paramMessage `'${"model"}.${"name"}' is held to '${"base"}.${"name"}' as well, through 'allOf', and merging the two declarations refers back to itself. This emitter declares no recursive merge, so the value is refused rather than validated against one of the two. Declare '${"name"}' on '${"model"}' as '${"declared"}', or as a type derived from it.`,
+        },
+    },
     "unknown-key-vocabulary": {
         severity: "error",
         messages: {
@@ -287,14 +358,25 @@ const diagnostics = {
         },
     },
     /**
+     * **A constraint `@encode` has moved onto a JSON type it does not apply to.**
+     *
+     * openapi3 applies a property's or a scalar's constraints and then lets the encoding replace
+     * `type`, so `@encode(string)` on a numeric property publishes `minimum` beside `type: string`,
+     * and `@encode("x", int32)` on a string publishes `pattern` beside `type: integer`. JSON Schema
+     * ignores each there, so the document asserts nothing, and the validator drops it too: applied,
+     * a numeric bound on text became a LENGTH check, and `.regex()` on an integer or `.min()` on a
+     * boolean threw when the module loaded. A default of the declared type under an encoding that
+     * changes it is the same case: it is no value of the encoded type.
+     *
      * **A diagnostic, not a linter rule**, because here the emitter cannot do what the spec asks: it
-     * drops a bound the author wrote. That is the case TypeSpec reserves for `$onValidate`-style
-     * diagnostics, where a linter is for a program that is correct but could be better.
+     * drops a rule the author wrote. That is the case TypeSpec reserves for `$onValidate`-style
+     * diagnostics, where a linter is for a program that is correct but could be better. It replaces
+     * `unenforceable-encoded-bound`, which reported numeric bounds on text and nothing else.
      */
-    "unenforceable-encoded-bound": {
+    "unenforceable-encoded-constraint": {
         severity: "warning",
         messages: {
-            default: paramMessage `The bound on '${"name"}' cannot be enforced, and is not emitted. '@encode(string)' makes the wire value text, so '@minValue'/'@maxValue' would become a check on how many CHARACTERS it has - '@minValue(10)' would refuse '"42"' - and the exclusive form has no string equivalent at all. The document is no help either: it publishes 'minimum' on a 'type: string' schema, which JSON Schema ignores, so a validator enforcing the bound would refuse what the published contract accepts. Declare the bound as a '@pattern', which the document publishes and every caller can read, or remove '@encode(string)' and let the value be a number.`,
+            default: paramMessage `${"keywords"} on '${"name"}' is not emitted: '@encode' makes the wire value a JSON ${"type"}, and ${"keywords"} is written for the declared type. '@typespec/openapi3' publishes it beside 'type: ${"type"}', where JSON Schema ignores a keyword meant for another type and a default is no value of it, so a validator applying it would disagree with the published contract. Declare the rule in a form the encoded value carries, such as a '@pattern' on a string, or remove '@encode'.`,
         },
     },
     /**
@@ -303,7 +385,7 @@ const diagnostics = {
      * Zod skips a declared `__proto__` key on purpose, so prototype pollution cannot reach through a
      * parse (colinhacks/zod#6386): a value of any type, or none, is accepted for it and dropped from
      * the result. The document publishes it like any other property, and nothing emitted can enforce
-     * it - which is the case `unenforceable-encoded-bound` reports for a bound, for the same reason:
+     * it - which is the case `unenforceable-encoded-constraint` reports for a constraint, for the same reason:
      * the spec is representable, so refusing it would make it emit under one emitter and not the
      * other, and serving it silently would leave a validator looser than its contract unsaid.
      *
@@ -381,21 +463,37 @@ const diagnostics = {
         },
     },
     /**
-     * **An `@encode` chain that returns to where it started never reaches a wire type.**
-     *
-     * `@encode("x", Pong) scalar Ping` and `@encode("x", Ping) scalar Pong` compile cleanly - the
-     * compiler checks neither the encoding's name nor where its type leads - and the walks here
-     * followed `@encode` by calling themselves on the encoded type. Measured before this existed:
-     * `RangeError: Maximum call stack size exceeded`, "Emitter crashed! This is a bug."
-     *
-     * **An error, as `inline-cycle` is.** A value of such a scalar has no form on the wire to validate,
-     * so there is no validator to emit. openapi3 reads one link of the chain and publishes a schema
-     * with no `type` at all - `{ format: "x" }` - which states nothing about the value either.
+     * **A body declared `never`.** The type has no values, so the body cannot exist, and
+     * `@typespec/openapi3` - whose body paths test only for `void` - publishes it as
+     * `content: { "application/json": { schema: {} } }`, any value at all. A validator could agree
+     * with the spec or with the document, not both, so the declaration is refused. `void` declares no
+     * body, and the document publishes it as none.
      */
-    "encode-cycle": {
+    "never-body": {
         severity: "error",
         messages: {
-            default: paramMessage `'${"type"}' is encoded as ${"chain"}: the '@encode' chain returns to a scalar it already passed, so it never reaches a type that crosses the wire. Encode one of them as a standard scalar such as 'string', or break the cycle.`,
+            default: paramMessage `'${"operationId"}' declares a ${"position"} body of type 'never', which has no values, and '@typespec/openapi3' publishes it as any JSON value. Replace it with 'void' to declare no body.`,
+        },
+    },
+    /**
+     * **An `@encode` whose published schema no value satisfies, or which states no type.**
+     *
+     * `@typespec/openapi3` keeps the declared type beside the encoded one, so `@encode("x", string)`
+     * on a model publishes `{ $ref: Filter, type: "string" }`: an object and a string at once, which
+     * nothing is. The same holds for a list model, an integer enum, or a string scalar encoded as
+     * `int32`. An encoding to a scalar outside the standard library publishes no `type` at all, which
+     * is also how two scalars whose `@encode` name each other once overflowed the stack. This emitter
+     * validated the encoded scalar beside each, so a value the document refuses was accepted, or one
+     * it accepts refused.
+     *
+     * **An error, as `undeclared-discriminator` is**: the published contract is not one a validator
+     * can agree with, so the declaration is refused rather than read some other way, and the property
+     * validates nothing until the spec says what it means.
+     */
+    "unsatisfiable-encoding": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"name"}' is declared '${"declared"}' and encoded as '${"encoded"}': ${"why"}. Encode it as a standard scalar its declared type admits, or remove '@encode'.`,
         },
     },
     /**
@@ -412,16 +510,67 @@ const diagnostics = {
      * validated as both declarations at once, and the contract types still compile. A server emitter
      * reading `EmittedRoute.sharedInputKeys` declines to mount the operation.
      */
+    /**
+     * **Two header parameters whose names differ only in case**, which HTTP reads as one header and
+     * openapi3 publishes as two parameters of that one value. Refused; see `headerCaseCollisionOf`.
+     */
+    "header-case-collision": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"operation"}' declares the header '${"first"}' and the header '${"second"}', which HTTP reads as one header - a header's name is case-insensitive - and openapi3 publishes as two parameters of the one value it carries. Neither is validated. Give one of them a different name.`,
+        },
+    },
     "shared-input-key": {
         severity: "warning",
         messages: {
             default: paramMessage `'${"operation"}' takes the ${"first"} '${"key"}' and the ${"second"} '${"key"}', and a handler's input holds one value under each key, so '${"key"}' is stated as both declarations at once and accepts only a value satisfying both. Give one of them a different name.`,
+            repeated: paramMessage `'${"operation"}' takes the ${"first"} '${"key"}' twice, and the document publishes only the first: the wire carries one value, which is validated and typed as the first declaration, and the second states nothing. Give one of them a different name.`,
+        },
+    },
+    /**
+     * **A schema `@typespec/openapi3` publishes with its properties and its `required` read at two
+     * visibilities.** openapi3 writes a component from the first reference that reaches it; where that
+     * reference is a request's, and the model has nothing to reshape there, its `required` is read at
+     * `Read` and its properties at the request's visibility - a read-only property is then required and
+     * not declared, or, optional, left out - and every use of the component shares it. Refused, by the
+     * maintainer's decision, rather than validated against a schema the document does not hold. See
+     * `publicationOf` in `published.ts` for the measured mechanism.
+     */
+    "split-visibility": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'@typespec/openapi3' publishes '${"name"}' as ${"via"} first reaches it: there it reads the properties of ${"model"} at '${"at"}' and its 'required' at 'Read', so ${"property"} is ${"effect"}, in every use of '${"name"}'. Refused rather than validated against a schema the document does not hold. Use the request's own view, which openapi3 publishes apart: ${"remedy"}.`,
+            inherited: paramMessage `'${"name"}' holds ${"model"} through 'allOf', and '@typespec/openapi3' publishes ${"model"} as ${"via"} first reaches it: there it reads the properties of ${"model"} at '${"at"}' and its 'required' at 'Read', so ${"property"} is ${"effect"}, in every model holding it. Refused rather than validated against a schema the document does not hold. Use the request's own view, which openapi3 publishes apart: ${"remedy"}.`,
+            inline: paramMessage `'@typespec/openapi3' publishes ${"model"} with its properties read at '${"at"}' and its 'required' at 'Read', so ${"property"} is ${"effect"}. Refused rather than validated against a schema the document does not hold. Use the request's own view, which openapi3 publishes apart: ${"remedy"}.`,
+        },
+    },
+    /**
+     * **A `@oneOf` body sent as a URL-encoded form, where a member may read one text two ways and
+     * another member accepts one and not the other.** The document accepts the form where some
+     * reading of its text matches exactly one member, and which reading that is depends on every key
+     * and member - finding it means trying every combination, exponential in the keys, and a record's
+     * keys are the sender's to choose. Refused rather than validated by a reading the document need
+     * not take. See `ambiguousFormKeyOf`.
+     */
+    "ambiguous-form-reading": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"operation"}' accepts the '@oneOf' '${"union"}' as a URL-encoded form, where '${"member"}' may read the text of ${"key"} as ${"first"} and as ${"second"}, and '${"other"}' accepts only the first. The document takes the form where some reading of its text matches exactly one member, and which reading that is depends on every key and member, so the body is not validated. Give ${"key"} one reading in '${"member"}', declare it alike in '${"other"}', or publish the union as 'anyOf' by removing '@oneOf'.`,
         },
     },
     "duplicate-declaration": {
         severity: "error",
         messages: {
             default: paramMessage `Two different types are both named '${"name"}', and a TypeScript module cannot declare one name twice. The document tells them apart by namespace; this file cannot. Give one of them a different name, or set an explicit one with '@friendlyName'.`,
+            renamed: paramMessage `Two different types, '${"first"}' and '${"second"}', are both declared as '${"name"}': a character an identifier cannot hold is written '_', and a TypeScript module cannot declare one name twice, so neither is validated. Give one of them a different name, or set an explicit one with '@friendlyName'.`,
+            multipart: paramMessage `'${"name"}' is a multipart body and the name of a schema that differs from it - the same model sent as JSON is one: openapi3 publishes one component under the name, and a TypeScript module cannot declare one name twice, so neither is validated. Send the multipart body as a model of its own.`,
+            envelope: paramMessage `'${"name"}' is the name openapi3 gives an envelope of a '@discriminated' union, after the union and the variant, and the name of another type: a TypeScript module cannot declare one name twice, so neither is validated. Rename the type, the union or the variant.`,
+            instances: paramMessage `Two instances of the template '${"name"}' are both named '${"name"}', as openapi3 names a union instance after its template alone: it refuses its own document for them as 'duplicate-type-name', and a TypeScript module cannot declare one name twice, so neither is validated. Declare a named union for each, or set an explicit name with '@friendlyName'.`,
+            binary: paramMessage `'${"name"}' holds 'bytes' and is sent as a multipart part, where openapi3 publishes 'bytes' as any value, and used elsewhere, where it is a base64 string: openapi3 publishes both under the name and refuses its own document as 'duplicate-type-name', and a TypeScript module cannot declare one name twice, so neither is validated. Give the part a union of its own.`,
+            cased: paramMessage `Two different types, '${"first"}' and '${"second"}', are both validated by '${"name"}': a validator is named for its type with the first letter lowered, and a TypeScript module cannot declare one name twice, so neither is validated. Give one of them a different name, or set an explicit one with '@friendlyName'.`,
+            suffixed: paramMessage `'${"name"}' is the name openapi3 gives '${"first"}' at '${"at"}', a type it suffixes for being used at more than one visibility, and the name of '${"second"}': openapi3 refuses its own document for it as 'duplicate-type-name', and a TypeScript module cannot declare one name twice, so neither is validated. Rename '${"second"}', or set an explicit name with '@friendlyName'.`,
+            visibility: paramMessage `'${"name"}' is the document's one name for two different schemas of one model, at '${"first"}' and at '${"second"}': openapi3 publishes both under it and refuses its own document as 'duplicate-type-name', and this module cannot declare one name twice, so neither is validated. ${"remedy"}`,
+            context: paramMessage `'${"name"}' is published inside an explicit '@body', where '@typespec/http' ignores its metadata annotations and the document holds them as data, and outside one, where they are metadata: two shapes under one name, which '@typespec/openapi3' refuses too, as 'duplicate-type-name'. Mark the body '@bodyRoot', or give the body a model of its own.`,
         },
     },
 };