@suveren/gateway 0.38.0 → 0.40.0

package/node_modules/zod/src/v4/core/to-json-schema.ts

@@ -1,51 +1,71 @@
-import type * as checks from "./checks.js";
+import type * as core from "../core/index.js";
 import type * as JSONSchema from "./json-schema.js";
-import { $ZodRegistry, globalRegistry } from "./registries.js";
+import { type $ZodRegistry, globalRegistry } from "./registries.js";
 import type * as schemas from "./schemas.js";
-import { getEnumValues } from "./util.js";
+import type { StandardJSONSchemaV1, StandardSchemaWithJSONProps } from "./standard-schema.js";
+import { assignProp } from "./util.js";
+
+function assignProps<T extends object>(target: T, ...sources: object[]): T {
+  for (const source of sources) {
+    for (const key of Reflect.ownKeys(source)) {
+      if (Object.prototype.propertyIsEnumerable.call(source, key)) {
+        assignProp(target, key, (source as any)[key]);
+      }
+    }
+  }
+  return target;
+}
 
-interface JSONSchemaGeneratorParams {
+export type Processor<T extends schemas.$ZodType = schemas.$ZodType> = (
+  schema: T,
+  ctx: ToJSONSchemaContext,
+  json: JSONSchema.BaseSchema,
+  params: ProcessParams
+) => void;
+
+/**
+ * Called for each schema that has no JSON Schema equivalent. Return a JSON Schema to use in its
+ * place, `"any"` to fall back to the `unrepresentable: "any"` behavior, or `"throw"`/`undefined` to
+ * throw the default error. Throwing from the handler propagates, so custom errors work too.
+ */
+export type UnrepresentableHandler<T extends schemas.$ZodType = schemas.$ZodType> = (ctx: {
+  zodSchema: T;
+  path: (string | number)[];
+  /** The error Zod would throw. Distinguishes sites that share a `zodSchema`, e.g. an `undefined`
+   *  vs a `bigint` member of the same literal. */
+  message: string;
+}) => JSONSchema.BaseSchema | "throw" | "any" | undefined;
+
+export interface JSONSchemaGeneratorParams {
+  processors: Record<string, Processor>;
   /** A registry used to look up metadata for each schema. Any schema with an `id` property will be extracted as a $def.
    *  @default globalRegistry */
   metadata?: $ZodRegistry<Record<string, any>>;
   /** The JSON Schema version to target.
    * - `"draft-2020-12"` — Default. JSON Schema Draft 2020-12
-   * - `"draft-7"` — JSON Schema Draft 7 */
-  target?: "draft-7" | "draft-2020-12";
+   * - `"draft-07"` — JSON Schema Draft 7
+   * - `"draft-04"` — JSON Schema Draft 4
+   * - `"openapi-3.0"` — OpenAPI 3.0 Schema Object */
+  target?: "draft-04" | "draft-07" | "draft-2020-12" | "openapi-3.0" | ({} & string) | undefined;
   /** How to handle unrepresentable types.
    * - `"throw"` — Default. Unrepresentable types throw an error
-   * - `"any"` — Unrepresentable types become `{}` */
-  unrepresentable?: "throw" | "any";
+   * - `"any"` — Unrepresentable types become `{}`
+   * - A function — called once per unrepresentable schema; see {@link UnrepresentableHandler}. */
+  unrepresentable?: "throw" | "any" | UnrepresentableHandler<schemas.$ZodTypes>;
   /** Arbitrary custom logic that can be used to modify the generated JSON Schema. */
   override?: (ctx: {
     zodSchema: schemas.$ZodTypes;
     jsonSchema: JSONSchema.BaseSchema;
     path: (string | number)[];
   }) => void;
-  /** Whether to extract the `"input"` or `"output"` type. Relevant to transforms, Error converting schema to JSONz, defaults, coerced primitives, etc.
+  /** Whether to extract the `"input"` or `"output"` type. Relevant to transforms, defaults, coerced primitives, etc.
    * - `"output"` — Default. Convert the output schema.
    * - `"input"` — Convert the input schema. */
   io?: "input" | "output";
-}
-
-interface ProcessParams {
-  schemaPath: schemas.$ZodType[];
-  path: (string | number)[];
-}
-
-interface EmitParams {
-  /** How to handle cycles.
-   * - `"ref"` — Default. Cycles will be broken using $defs
-   * - `"throw"` — Cycles will throw an error if encountered */
   cycles?: "ref" | "throw";
-  /* How to handle reused schemas.
-   * - `"inline"` — Default. Reused schemas will be inlined
-   * - `"ref"` — Reused schemas will be extracted as $defs */
   reused?: "ref" | "inline";
-
   external?:
     | {
-        /**  */
         registry: $ZodRegistry<{ id?: string | undefined }>;
         uri?: ((id: string) => string) | undefined;
         defs: Record<string, JSONSchema.BaseSchema>;
@@ -53,7 +73,24 @@ interface EmitParams {
     | undefined;
 }
 
-interface Seen {
+/**
+ * Parameters for the toJSONSchema function.
+ */
+export type ToJSONSchemaParams = Omit<JSONSchemaGeneratorParams, "processors" | "external">;
+
+/**
+ * Parameters for the toJSONSchema function when passing a registry.
+ */
+export interface RegistryToJSONSchemaParams extends ToJSONSchemaParams {
+  uri?: (id: string) => string;
+}
+
+export interface ProcessParams {
+  schemaPath: schemas.$ZodType[];
+  path: (string | number)[];
+}
+
+export interface Seen {
   /** JSON Schema result for this Zod schema */
   schema: JSONSchema.BaseSchema;
   /** A cached version of the schema that doesn't get overwritten during ref resolution */
@@ -64,812 +101,660 @@ interface Seen {
   /** Cycle path */
   cycle?: (string | number)[] | undefined;
   isParent?: boolean | undefined;
-  ref?: schemas.$ZodType | undefined | null;
+  /** Schema to inherit JSON Schema properties from (set by processor for wrappers) */
+  ref?: schemas.$ZodType | null;
   /** JSON Schema property path for this schema */
   path?: (string | number)[] | undefined;
 }
 
-export class JSONSchemaGenerator {
+export interface ToJSONSchemaContext {
+  processors: Record<string, Processor>;
   metadataRegistry: $ZodRegistry<Record<string, any>>;
-  target: "draft-7" | "draft-2020-12";
-  unrepresentable: "throw" | "any";
+  target: "draft-04" | "draft-07" | "draft-2020-12" | "openapi-3.0" | ({} & string);
+  // must be schemas.$ZodType to prevent recursive type resolution error
+  unrepresentable: "throw" | "any" | UnrepresentableHandler;
   override: (ctx: {
-    zodSchema: schemas.$ZodTypes;
+    // must be schemas.$ZodType to prevent recursive type resolution error
+    zodSchema: schemas.$ZodType;
     jsonSchema: JSONSchema.BaseSchema;
     path: (string | number)[];
   }) => void;
   io: "input" | "output";
-
-  counter = 0;
+  counter: number;
   seen: Map<schemas.$ZodType, Seen>;
+  /** Registry conversions share one `seen` map across every emitted schema. These hold the
+   * `external` the whole-map passes below last ran for, so the passes are not repeated once per
+   * schema — and still re-run if the map grows or `external` is swapped. `sharedEmitDoneFor`
+   * covers both passes in `finalize`: the ref flattening and the `$defs` build.
+   *
+   * The passes are valid only while nothing they read has changed, so both are cleared in
+   * `processSchema()` when the map grows, and in `JSONSchemaGenerator.emit()`, which can also change
+   * the `cycles` and `reused` they branch on.
+   *
+   * One case is deliberately not covered: an `override` callback that writes to
+   * `metadataRegistry` mid-conversion. It runs inside `finalize`, so a registry conversion has
+   * nowhere left to clear the guards, and later schemas keep the ids the first pass saw. That
+   * output was never coherent — before this, whether a shared subschema was inlined or extracted
+   * depended on which registry entry happened to be emitted when the callback fired. */
+  sharedDefsExtractedFor?: ToJSONSchemaContext["external"];
+  sharedEmitDoneFor?: ToJSONSchemaContext["external"];
+  cycles: "ref" | "throw";
+  reused: "ref" | "inline";
+  /** The `allOf` array of each intersection encountered during traversal, innermost first. `finalize` folds every emitted object holding one; see `foldIntersection`. */
+  intersections: JSONSchema.BaseSchema[][];
+  /** Rewrites a processor deferred to `finalize`, where the flatten has resolved every ref and the union branches are in place. */
+  deferred: (() => void)[];
+  external?:
+    | {
+        registry: $ZodRegistry<{ id?: string | undefined }>;
+        uri?: ((id: string) => string) | undefined;
+        defs: Record<string, JSONSchema.BaseSchema>;
+      }
+    | undefined;
+}
 
-  constructor(params?: JSONSchemaGeneratorParams) {
-    this.metadataRegistry = params?.metadata ?? globalRegistry;
-    this.target = params?.target ?? "draft-2020-12";
-    this.unrepresentable = params?.unrepresentable ?? "throw";
-    this.override = params?.override ?? (() => {});
-    this.io = params?.io ?? "output";
-
-    this.seen = new Map();
-  }
-
-  process(schema: schemas.$ZodType, _params: ProcessParams = { path: [], schemaPath: [] }): JSONSchema.BaseSchema {
-    const def = (schema as schemas.$ZodTypes)._zod.def;
+// function initializeContext<T extends schemas.$ZodType>(inputs: JSONSchemaGeneratorParams<T>): ToJSONSchemaContext<T> {
+//   return {
+//     processor: inputs.processor,
+//     metadataRegistry: inputs.metadata ?? globalRegistry,
+//     target: inputs.target ?? "draft-2020-12",
+//     unrepresentable: inputs.unrepresentable ?? "throw",
+//   };
+// }
+
+export function initializeContext(params: JSONSchemaGeneratorParams): ToJSONSchemaContext {
+  // Normalize target: convert old non-hyphenated versions to hyphenated versions
+  let target: ToJSONSchemaContext["target"] = params?.target ?? "draft-2020-12";
+  if (target === "draft-4") target = "draft-04";
+  if (target === "draft-7") target = "draft-07";
+
+  return {
+    processors: params.processors ?? {},
+    metadataRegistry: params?.metadata ?? globalRegistry,
+    target,
+    unrepresentable: (params?.unrepresentable as ToJSONSchemaContext["unrepresentable"]) ?? "throw",
+    override: (params?.override as any) ?? (() => {}),
+    io: params?.io ?? "output",
+    counter: 0,
+    seen: new Map(),
+    sharedDefsExtractedFor: undefined,
+    sharedEmitDoneFor: undefined,
+    cycles: params?.cycles ?? "ref",
+    reused: params?.reused ?? "inline",
+    intersections: [],
+    deferred: [],
+    external: params?.external ?? undefined,
+  };
+}
 
-    const formatMap: Partial<Record<checks.$ZodStringFormats, string | undefined>> = {
-      guid: "uuid",
-      url: "uri",
-      datetime: "date-time",
-      json_string: "json-string",
-      regex: "", // do not set
-    };
+/**
+ * Applies the `unrepresentable` setting at a site that has no JSON Schema equivalent. Throws
+ * `message` unless the setting (or the handler's return value) says otherwise. Returns `true` if a
+ * custom JSON Schema was written into `json`, in which case the caller must not write its own.
+ */
+export function handleUnrepresentable(
+  schema: schemas.$ZodType,
+  ctx: ToJSONSchemaContext,
+  json: JSONSchema.BaseSchema,
+  params: ProcessParams,
+  message: string
+): boolean {
+  const result =
+    typeof ctx.unrepresentable === "function"
+      ? ctx.unrepresentable({ zodSchema: schema, path: params.path, message })
+      : ctx.unrepresentable;
+  if (result === "any") return false;
+  if (result === undefined || result === "throw") throw new Error(message);
+  Object.assign(json, result);
+  return true;
+}
 
-    // check for schema in seens
-    const seen = this.seen.get(schema);
+// never rename this back to `process`: bundler polyfills inject a top-level `const process` that a lexical declaration of the same name collides with (#6397)
+export function processSchema<T extends schemas.$ZodType>(
+  schema: T,
+  ctx: ToJSONSchemaContext,
+  _params: ProcessParams = { path: [], schemaPath: [] }
+): JSONSchema.BaseSchema {
+  const def = schema._zod.def as schemas.$ZodTypes["_zod"]["def"];
 
-    if (seen) {
-      seen.count++;
+  // check for schema in seens
+  const seen = ctx.seen.get(schema);
 
-      // check if cycle
-      const isCycle = _params.schemaPath.includes(schema);
-      if (isCycle) {
-        seen.cycle = _params.path;
-      }
+  if (seen) {
+    seen.count++;
 
-      return seen.schema;
+    // check if cycle
+    const isCycle = _params.schemaPath.includes(schema);
+    if (isCycle) {
+      seen.cycle = _params.path;
     }
 
-    // initialize
-    const result: Seen = { schema: {}, count: 1, cycle: undefined, path: _params.path };
-    this.seen.set(schema, result);
+    return seen.schema;
+  }
+
+  // initialize
+  const result: Seen = { schema: {}, count: 1, cycle: undefined, path: _params.path };
+  ctx.seen.set(schema, result);
+  ctx.sharedDefsExtractedFor = undefined;
+  ctx.sharedEmitDoneFor = undefined;
+
+  // custom method overrides default behavior
+  const overrideSchema = schema._zod.toJSONSchema?.();
+  if (overrideSchema) {
+    result.schema = overrideSchema as any;
+  } else {
+    const params = {
+      ..._params,
+      schemaPath: [..._params.schemaPath, schema],
+      path: _params.path,
+    };
 
-    // custom method overrides default behavior
-    const overrideSchema = schema._zod.toJSONSchema?.();
-    if (overrideSchema) {
-      result.schema = overrideSchema as any;
+    if (schema._zod.processJSONSchema) {
+      schema._zod.processJSONSchema(ctx, result.schema, params);
     } else {
-      const params = {
-        ..._params,
-        schemaPath: [..._params.schemaPath, schema],
-        path: _params.path,
-      };
-
-      const parent = schema._zod.parent;
-
-      if (parent) {
-        // schema was cloned from another schema
-        result.ref = parent;
-        this.process(parent, params);
-        this.seen.get(parent)!.isParent = true;
-      } else {
-        const _json = result.schema;
-        switch (def.type) {
-          case "string": {
-            const json: JSONSchema.StringSchema = _json as any;
-            json.type = "string";
-            const { minimum, maximum, format, patterns, contentEncoding } = schema._zod
-              .bag as schemas.$ZodStringInternals<unknown>["bag"];
-            if (typeof minimum === "number") json.minLength = minimum;
-            if (typeof maximum === "number") json.maxLength = maximum;
-            // custom pattern overrides format
-            if (format) {
-              json.format = formatMap[format as checks.$ZodStringFormats] ?? format;
-              if (json.format === "") delete json.format; // empty format is not valid
-            }
-            if (contentEncoding) json.contentEncoding = contentEncoding;
-            if (patterns && patterns.size > 0) {
-              const regexes = [...patterns];
-              if (regexes.length === 1) json.pattern = regexes[0]!.source;
-              else if (regexes.length > 1) {
-                result.schema.allOf = [
-                  ...regexes.map((regex) => ({
-                    ...(this.target === "draft-7" ? ({ type: "string" } as const) : {}),
-                    pattern: regex.source,
-                  })),
-                ];
-              }
-            }
+      const _json = result.schema;
+      const processor = ctx.processors[def.type];
+      if (!processor) {
+        throw new Error(`[toJSONSchema]: Non-representable type encountered: ${def.type}`);
+      }
+      processor(schema, ctx, _json, params);
+    }
 
-            break;
-          }
-          case "number": {
-            const json: JSONSchema.NumberSchema | JSONSchema.IntegerSchema = _json as any;
-            const { minimum, maximum, format, multipleOf, exclusiveMaximum, exclusiveMinimum } = schema._zod.bag;
-            if (typeof format === "string" && format.includes("int")) json.type = "integer";
-            else json.type = "number";
-
-            if (typeof exclusiveMinimum === "number") json.exclusiveMinimum = exclusiveMinimum;
-            if (typeof minimum === "number") {
-              json.minimum = minimum;
-              if (typeof exclusiveMinimum === "number") {
-                if (exclusiveMinimum >= minimum) delete json.minimum;
-                else delete json.exclusiveMinimum;
-              }
-            }
+    const parent = schema._zod.parent as T;
 
-            if (typeof exclusiveMaximum === "number") json.exclusiveMaximum = exclusiveMaximum;
-            if (typeof maximum === "number") {
-              json.maximum = maximum;
-              if (typeof exclusiveMaximum === "number") {
-                if (exclusiveMaximum <= maximum) delete json.maximum;
-                else delete json.exclusiveMaximum;
-              }
-            }
+    if (parent) {
+      // Also set ref if processor didn't (for inheritance)
+      if (!result.ref) result.ref = parent;
+      processSchema(parent, ctx, params);
+      ctx.seen.get(parent)!.isParent = true;
+    }
+  }
 
-            if (typeof multipleOf === "number") json.multipleOf = multipleOf;
+  // metadata
+  const meta = ctx.metadataRegistry.get(schema);
+  if (meta) assignProps(result.schema, meta);
 
-            break;
-          }
-          case "boolean": {
-            const json = _json as JSONSchema.BooleanSchema;
-            json.type = "boolean";
-            break;
-          }
-          case "bigint": {
-            if (this.unrepresentable === "throw") {
-              throw new Error("BigInt cannot be represented in JSON Schema");
-            }
-            break;
-          }
-          case "symbol": {
-            if (this.unrepresentable === "throw") {
-              throw new Error("Symbols cannot be represented in JSON Schema");
-            }
-            break;
-          }
-          case "null": {
-            _json.type = "null";
-            break;
-          }
-          case "any": {
-            break;
-          }
-          case "unknown": {
-            break;
-          }
-          case "undefined": {
-            if (this.unrepresentable === "throw") {
-              throw new Error("Undefined cannot be represented in JSON Schema");
-            }
-            break;
-          }
-          case "void": {
-            if (this.unrepresentable === "throw") {
-              throw new Error("Void cannot be represented in JSON Schema");
-            }
-            break;
-          }
-          case "never": {
-            _json.not = {};
-            break;
-          }
-          case "date": {
-            if (this.unrepresentable === "throw") {
-              throw new Error("Date cannot be represented in JSON Schema");
-            }
-            break;
-          }
-          case "array": {
-            const json: JSONSchema.ArraySchema = _json as any;
-            const { minimum, maximum } = schema._zod.bag;
-            if (typeof minimum === "number") json.minItems = minimum;
-            if (typeof maximum === "number") json.maxItems = maximum;
-
-            json.type = "array";
-            json.items = this.process(def.element, { ...params, path: [...params.path, "items"] });
-            break;
-          }
-          case "object": {
-            const json: JSONSchema.ObjectSchema = _json as any;
-            json.type = "object";
-            json.properties = {};
-            const shape = def.shape; // params.shapeCache.get(schema)!;
-
-            for (const key in shape) {
-              json.properties[key] = this.process(shape[key]!, {
-                ...params,
-                path: [...params.path, "properties", key],
-              });
-            }
-
-            // required keys
-            const allKeys = new Set(Object.keys(shape));
-            // const optionalKeys = new Set(def.optional);
-            const requiredKeys = new Set(
-              [...allKeys].filter((key) => {
-                const v = def.shape[key]!._zod;
-                if (this.io === "input") {
-                  return v.optin === undefined;
-                } else {
-                  return v.optout === undefined;
-                }
-              })
-            );
-
-            if (requiredKeys.size > 0) {
-              json.required = Array.from(requiredKeys);
-            }
+  if (ctx.io === "input" && isTransforming(schema)) {
+    // examples/defaults only apply to output type of pipe
+    delete result.schema.examples;
+    delete result.schema.default;
+  }
 
-            // catchall
-            if (def.catchall?._zod.def.type === "never") {
-              // strict
-              json.additionalProperties = false;
-            } else if (!def.catchall) {
-              // regular
-              if (this.io === "output") json.additionalProperties = false;
-            } else if (def.catchall) {
-              json.additionalProperties = this.process(def.catchall, {
-                ...params,
-                path: [...params.path, "additionalProperties"],
-              });
-            }
+  // set prefault as default
+  if (ctx.io === "input" && "_prefault" in result.schema) result.schema.default ??= result.schema._prefault;
+  delete result.schema._prefault;
 
-            break;
-          }
-          case "union": {
-            const json: JSONSchema.BaseSchema = _json as any;
-            json.anyOf = def.options.map((x, i) =>
-              this.process(x, {
-                ...params,
-                path: [...params.path, "anyOf", i],
-              })
-            );
-            break;
-          }
-          case "intersection": {
-            const json: JSONSchema.BaseSchema = _json as any;
-            const a = this.process(def.left, {
-              ...params,
-              path: [...params.path, "allOf", 0],
-            });
-            const b = this.process(def.right, {
-              ...params,
-              path: [...params.path, "allOf", 1],
-            });
-
-            const isSimpleIntersection = (val: any) => "allOf" in val && Object.keys(val).length === 1;
-            const allOf = [
-              ...(isSimpleIntersection(a) ? (a.allOf as any[]) : [a]),
-              ...(isSimpleIntersection(b) ? (b.allOf as any[]) : [b]),
-            ];
-            json.allOf = allOf;
-            break;
-          }
-          case "tuple": {
-            const json: JSONSchema.ArraySchema = _json as any;
-            json.type = "array";
-            const prefixItems = def.items.map((x, i) =>
-              this.process(x, { ...params, path: [...params.path, "prefixItems", i] })
-            );
-            if (this.target === "draft-2020-12") {
-              json.prefixItems = prefixItems;
-            } else {
-              json.items = prefixItems;
-            }
+  // pulling fresh from ctx.seen in case it was overwritten
+  const _result = ctx.seen.get(schema)!;
 
-            if (def.rest) {
-              const rest = this.process(def.rest, {
-                ...params,
-                path: [...params.path, "items"],
-              });
-              if (this.target === "draft-2020-12") {
-                json.items = rest;
-              } else {
-                json.additionalItems = rest;
-              }
-            }
+  return _result.schema;
+}
 
-            // additionalItems
-            if (def.rest) {
-              json.items = this.process(def.rest, {
-                ...params,
-                path: [...params.path, "items"],
-              });
-            }
+/** @deprecated Renamed to `processSchema`. An export alias declares no binding, so it is safe to keep. */
+export { processSchema as process };
 
-            // length
-            const { minimum, maximum } = schema._zod.bag as {
-              minimum?: number;
-              maximum?: number;
-            };
-            if (typeof minimum === "number") json.minItems = minimum;
-            if (typeof maximum === "number") json.maxItems = maximum;
-            break;
-          }
-          case "record": {
-            const json: JSONSchema.ObjectSchema = _json as any;
-            json.type = "object";
-            json.propertyNames = this.process(def.keyType, { ...params, path: [...params.path, "propertyNames"] });
-            json.additionalProperties = this.process(def.valueType, {
-              ...params,
-              path: [...params.path, "additionalProperties"],
-            });
-            break;
-          }
-          case "map": {
-            if (this.unrepresentable === "throw") {
-              throw new Error("Map cannot be represented in JSON Schema");
-            }
-            break;
-          }
-          case "set": {
-            if (this.unrepresentable === "throw") {
-              throw new Error("Set cannot be represented in JSON Schema");
-            }
-            break;
-          }
-          case "enum": {
-            const json: JSONSchema.BaseSchema = _json as any;
-            const values = getEnumValues(def.entries);
-            // Number enums can have both string and number values
-            if (values.every((v) => typeof v === "number")) json.type = "number";
-            if (values.every((v) => typeof v === "string")) json.type = "string";
-            json.enum = values;
-            break;
-          }
-          case "literal": {
-            const json: JSONSchema.BaseSchema = _json as any;
-            const vals: (string | number | boolean | null)[] = [];
-            for (const val of def.values) {
-              if (val === undefined) {
-                if (this.unrepresentable === "throw") {
-                  throw new Error("Literal `undefined` cannot be represented in JSON Schema");
-                } else {
-                  // do not add to vals
-                }
-              } else if (typeof val === "bigint") {
-                if (this.unrepresentable === "throw") {
-                  throw new Error("BigInt literals cannot be represented in JSON Schema");
-                } else {
-                  vals.push(Number(val));
-                }
-              } else {
-                vals.push(val);
-              }
-            }
-            if (vals.length === 0) {
-              // do nothing (an undefined literal was stripped)
-            } else if (vals.length === 1) {
-              const val = vals[0]!;
-              json.type = val === null ? ("null" as const) : (typeof val as any);
-              json.const = val;
-            } else {
-              if (vals.every((v) => typeof v === "number")) json.type = "number";
-              if (vals.every((v) => typeof v === "string")) json.type = "string";
-              if (vals.every((v) => typeof v === "boolean")) json.type = "string";
-              if (vals.every((v) => v === null)) json.type = "null";
-              json.enum = vals;
-            }
-            break;
-          }
+// Escape a reference token for use in a JSON Pointer fragment (RFC 6901): `~` becomes `~0` and `/` becomes `~1`. The `~` replacement must run first.
+function encodeJSONPointerSegment(segment: string): string {
+  return segment.replace(/~/g, "~0").replace(/\//g, "~1");
+}
 
-          case "file": {
-            const json: JSONSchema.StringSchema = _json as any;
-            const file: JSONSchema.StringSchema = {
-              type: "string",
-              format: "binary",
-              contentEncoding: "binary",
-            };
-
-            const { minimum, maximum, mime } = schema._zod.bag as schemas.$ZodFileInternals["bag"];
-            if (minimum !== undefined) file.minLength = minimum;
-            if (maximum !== undefined) file.maxLength = maximum;
-            if (mime) {
-              if (mime.length === 1) {
-                file.contentMediaType = mime[0]!;
-                Object.assign(json, file);
-              } else {
-                json.anyOf = mime.map((m) => {
-                  const mFile: JSONSchema.StringSchema = { ...file, contentMediaType: m };
-                  return mFile;
-                });
-              }
-            } else {
-              Object.assign(json, file);
-            }
+export function extractDefs<T extends schemas.$ZodType>(
+  ctx: ToJSONSchemaContext,
+  schema: T
+  // params: EmitParams
+): void {
+  // iterate over seen map;
+  const root = ctx.seen.get(schema);
+
+  if (!root) throw new Error("Unprocessed schema. This is a bug in Zod.");
+
+  // With `external` set, every registered schema resolves through the external branch of `makeURI`, so the root branch below produces the same ref the external branch would — this pass is identical whichever schema it is called with, and only needs to run once.
+  if (ctx.external && ctx.sharedDefsExtractedFor === ctx.external) return;
+
+  // Track ids to detect duplicates across different schemas
+  const idToSchema = new Map<string, schemas.$ZodType>();
+  for (const entry of ctx.seen.entries()) {
+    const id = ctx.metadataRegistry.get(entry[0])?.id;
+    if (id) {
+      const existing = idToSchema.get(id);
+      if (existing && existing !== entry[0]) {
+        throw new Error(
+          `Duplicate schema id "${id}" detected during JSON Schema conversion. Two different schemas cannot share the same id when converted together.`
+        );
+      }
+      idToSchema.set(id, entry[0]);
+    }
+  }
 
-            // if (this.unrepresentable === "throw") {
-            //   throw new Error("File cannot be represented in JSON Schema");
-            // }
-            break;
-          }
-          case "transform": {
-            if (this.unrepresentable === "throw") {
-              throw new Error("Transforms cannot be represented in JSON Schema");
-            }
-            break;
-          }
+  // returns a ref to the schema defId will be empty if the ref points to an external schema (or #)
+  const makeURI = (entry: [schemas.$ZodType<unknown, unknown>, Seen]): { ref: string; defId?: string } => {
+    // comparing the seen objects because sometimes multiple schemas map to the same seen object. e.g. lazy
 
-          case "nullable": {
-            const inner = this.process(def.innerType, params);
-            _json.anyOf = [inner, { type: "null" }];
-            break;
-          }
-          case "nonoptional": {
-            this.process(def.innerType, params);
-            result.ref = def.innerType;
-            break;
-          }
-          case "success": {
-            const json = _json as JSONSchema.BooleanSchema;
-            json.type = "boolean";
-            break;
-          }
-          case "default": {
-            this.process(def.innerType, params);
-            result.ref = def.innerType;
-            _json.default = JSON.parse(JSON.stringify(def.defaultValue));
-            break;
-          }
-          case "prefault": {
-            this.process(def.innerType, params);
-            result.ref = def.innerType;
-            if (this.io === "input") _json._prefault = JSON.parse(JSON.stringify(def.defaultValue));
+    // external is configured
+    const defsSegment = ctx.target === "draft-2020-12" ? "$defs" : "definitions";
+    if (ctx.external) {
+      const externalId = ctx.external.registry.get(entry[0])?.id; // ?? "__shared";// `__schema${ctx.counter++}`;
 
-            break;
-          }
-          case "catch": {
-            // use conditionals
-            this.process(def.innerType, params);
-            result.ref = def.innerType;
-            let catchValue: any;
-            try {
-              catchValue = def.catchValue(undefined as any);
-            } catch {
-              throw new Error("Dynamic catch values are not supported in JSON Schema");
-            }
-            _json.default = catchValue;
-            break;
-          }
-          case "nan": {
-            if (this.unrepresentable === "throw") {
-              throw new Error("NaN cannot be represented in JSON Schema");
-            }
-            break;
-          }
-          case "template_literal": {
-            const json = _json as JSONSchema.StringSchema;
-            const pattern = schema._zod.pattern;
-            if (!pattern) throw new Error("Pattern not found in template literal");
-            json.type = "string";
-            json.pattern = pattern.source;
-            break;
-          }
-          case "pipe": {
-            const innerType = this.io === "input" ? (def.in._zod.def.type === "transform" ? def.out : def.in) : def.out;
-            this.process(innerType, params);
-            result.ref = innerType;
-            break;
-          }
-          case "readonly": {
-            this.process(def.innerType, params);
-            result.ref = def.innerType;
-            _json.readOnly = true;
-            break;
-          }
-          // passthrough types
-          case "promise": {
-            this.process(def.innerType, params);
-            result.ref = def.innerType;
-            break;
-          }
-          case "optional": {
-            this.process(def.innerType, params);
-            result.ref = def.innerType;
-            break;
-          }
-          case "lazy": {
-            const innerType = (schema as schemas.$ZodLazy)._zod.innerType;
-            this.process(innerType, params);
-            result.ref = innerType;
-            break;
-          }
-          case "custom": {
-            if (this.unrepresentable === "throw") {
-              throw new Error("Custom types cannot be represented in JSON Schema");
-            }
-            break;
-          }
-          default: {
-            def satisfies never;
-          }
-        }
+      // check if schema is in the external registry
+      const uriGenerator = ctx.external.uri ?? ((id: string) => id);
+      if (externalId) {
+        return { ref: uriGenerator(externalId) };
       }
+
+      // otherwise, add to __shared
+      const id: string = entry[1].defId ?? (entry[1].schema.id as string) ?? `schema${ctx.counter++}`;
+      entry[1].defId = id; // set defId so it will be reused if needed
+      return { defId: id, ref: `${uriGenerator("__shared")}#/${defsSegment}/${encodeJSONPointerSegment(id)}` };
     }
 
-    // metadata
-    const meta = this.metadataRegistry.get(schema);
-    if (meta) Object.assign(result.schema, meta);
+    const uriPrefix = `#`;
+    const defUriPrefix = `${uriPrefix}/${defsSegment}/`;
 
-    if (this.io === "input" && isTransforming(schema)) {
-      // examples/defaults only apply to output type of pipe
-      delete result.schema.examples;
-      delete result.schema.default;
+    // an id-less root has nowhere to be extracted to, so it stays inline and self-references as `#`
+    if (entry[1] === root && !entry[1].schema.id) {
+      return { ref: uriPrefix };
     }
 
-    // set prefault as default
-    if (this.io === "input" && result.schema._prefault) result.schema.default ??= result.schema._prefault;
-    delete result.schema._prefault;
-
-    // pulling fresh from this.seen in case it was overwritten
-    const _result = this.seen.get(schema)!;
+    // self-contained schema
+    const defId = entry[1].schema.id ?? `__schema${ctx.counter++}`;
+    return { defId, ref: defUriPrefix + encodeJSONPointerSegment(defId) };
+  };
 
-    return _result.schema;
-  }
+  // stored cached version in `def` property remove all properties, set $ref
+  const extractToDef = (entry: [schemas.$ZodType<unknown, unknown>, Seen]): void => {
+    // if the schema is already a reference, do not extract it
+    if (entry[1].schema.$ref) {
+      return;
+    }
+    const seen = entry[1];
+    const { ref, defId } = makeURI(entry);
+
+    seen.def = { ...seen.schema };
+    // defId won't be set if the schema is a reference to an external schema or if the schema is the root schema
+    if (defId) seen.defId = defId;
+    // wipe away all properties except $ref
+    const schema = seen.schema;
+    for (const key in schema) {
+      delete schema[key];
+    }
+    schema.$ref = ref;
+  };
 
-  emit(schema: schemas.$ZodType, _params?: EmitParams): JSONSchema.BaseSchema {
-    const params = {
-      cycles: _params?.cycles ?? "ref",
-      reused: _params?.reused ?? "inline",
-      // unrepresentable: _params?.unrepresentable ?? "throw",
-      // uri: _params?.uri ?? ((id) => `${id}`),
-      external: _params?.external ?? undefined,
-    } satisfies EmitParams;
-
-    // iterate over seen map;
-    const root = this.seen.get(schema);
-
-    if (!root) throw new Error("Unprocessed schema. This is a bug in Zod.");
-
-    // initialize result with root schema fields
-    // Object.assign(result, seen.cached);
-
-    // returns a ref to the schema
-    // defId will be empty if the ref points to an external schema (or #)
-    const makeURI = (entry: [schemas.$ZodType<unknown, unknown>, Seen]): { ref: string; defId?: string } => {
-      // comparing the seen objects because sometimes
-      // multiple schemas map to the same seen object.
-      // e.g. lazy
-
-      // external is configured
-      const defsSegment = this.target === "draft-2020-12" ? "$defs" : "definitions";
-      if (params.external) {
-        const externalId = params.external.registry.get(entry[0])?.id; // ?? "__shared";// `__schema${this.counter++}`;
-
-        // check if schema is in the external registry
-        const uriGenerator = params.external.uri ?? ((id) => id);
-        if (externalId) {
-          return { ref: uriGenerator(externalId) };
-        }
+  // throw on cycles
 
-        // otherwise, add to __shared
-        const id: string = entry[1].defId ?? (entry[1].schema.id as string) ?? `schema${this.counter++}`;
-        entry[1].defId = id; // set defId so it will be reused if needed
-        return { defId: id, ref: `${uriGenerator("__shared")}#/${defsSegment}/${id}` };
+  // break cycles
+  if (ctx.cycles === "throw") {
+    for (const entry of ctx.seen.entries()) {
+      const seen = entry[1];
+      if (seen.cycle) {
+        throw new Error(
+          "Cycle detected: " +
+            `#/${seen.cycle?.join("/")}/<root>` +
+            '\n\nSet the `cycles` parameter to `"ref"` to resolve cyclical schemas with defs.'
+        );
       }
+    }
+  }
 
-      if (entry[1] === root) {
-        return { ref: "#" };
-      }
+  // extract schemas into $defs
+  for (const entry of ctx.seen.entries()) {
+    const seen = entry[1];
 
-      // self-contained schema
-      const uriPrefix = `#`;
-      const defUriPrefix = `${uriPrefix}/${defsSegment}/`;
-      const defId = entry[1].schema.id ?? `__schema${this.counter++}`;
-      return { defId, ref: defUriPrefix + defId };
-    };
+    // convert root schema to # $ref
+    if (schema === entry[0]) {
+      extractToDef(entry); // this has special handling for the root schema
+      continue;
+    }
 
-    // stored cached version in `def` property
-    // remove all properties, set $ref
-    const extractToDef = (entry: [schemas.$ZodType<unknown, unknown>, Seen]): void => {
-      // if the schema is already a reference, do not extract it
-      if (entry[1].schema.$ref) {
-        return;
-      }
-      const seen = entry[1];
-      const { ref, defId } = makeURI(entry);
-
-      seen.def = { ...seen.schema };
-      // defId won't be set if the schema is a reference to an external schema
-      if (defId) seen.defId = defId;
-      // wipe away all properties except $ref
-      const schema = seen.schema;
-      for (const key in schema) {
-        delete schema[key];
+    // extract schemas that are in the external registry
+    if (ctx.external) {
+      const ext = ctx.external.registry.get(entry[0])?.id;
+      if (schema !== entry[0] && ext) {
+        extractToDef(entry);
+        continue;
       }
-      schema.$ref = ref;
-    };
+    }
 
-    // throw on cycles
+    // extract schemas with `id` meta
+    const id = ctx.metadataRegistry.get(entry[0])?.id;
+    if (id) {
+      extractToDef(entry);
+      continue;
+    }
 
     // break cycles
-    if (params.cycles === "throw") {
-      for (const entry of this.seen.entries()) {
-        const seen = entry[1];
-        if (seen.cycle) {
-          throw new Error(
-            "Cycle detected: " +
-              `#/${seen.cycle?.join("/")}/<root>` +
-              '\n\nSet the `cycles` parameter to `"ref"` to resolve cyclical schemas with defs.'
-          );
-        }
+    if (seen.cycle) {
+      // any
+      extractToDef(entry);
+      continue;
+    }
+
+    // extract reused schemas
+    if (seen.count > 1) {
+      if (ctx.reused === "ref") {
+        extractToDef(entry);
       }
     }
+  }
 
-    // extract schemas into $defs
-    for (const entry of this.seen.entries()) {
-      const seen = entry[1];
+  if (ctx.external) ctx.sharedDefsExtractedFor = ctx.external;
+}
 
-      // convert root schema to # $ref
-      if (schema === entry[0]) {
-        extractToDef(entry); // this has special handling for the root schema
-        continue;
-      }
+/** Rewrites `anyOf: [{type: "a"}, {type: "b"}]` to `type: ["a", "b"]`, which every JSON Schema draft treats as equivalent and most consumers render far better for the nullable case. Only branches that are a bare type assertion qualify — anything carrying a constraint, `$ref`, `const` or metadata is left alone. Runs after `flattenRef`, so a branch an override decorated or `$defs` extraction turned into a `$ref` is no longer bare and correctly stays in `anyOf`. `oneOf` is excluded: `integer` and `number` overlap, so "exactly one" and "at least one" are not the same there. OpenAPI 3.0 is excluded: its `type` must be a single string. */
+function compactTypeUnion(schema: JSONSchema.BaseSchema): void {
+  const options = schema.anyOf;
+  if (!Array.isArray(options) || options.length === 0 || schema.type !== undefined) return;
+
+  const types: JSONSchema.SchemaType[] = [];
+  for (const option of options) {
+    if (!option || typeof option !== "object") return;
+    // A branch that is itself a compactible union folds into this one — nested `anyOf` and a flat `type` array say the same thing. Compacting it first also makes the result independent of the order this pass walks the seen map in.
+    compactTypeUnion(option as JSONSchema.BaseSchema);
+    const keys = Object.keys(option);
+    if (keys.length !== 1 || keys[0] !== "type") return;
+    const type = (option as JSONSchema.BaseSchema).type;
+    for (const member of Array.isArray(type) ? type : [type]) {
+      if (typeof member !== "string") return;
+      if (!types.includes(member)) types.push(member);
+    }
+  }
 
-      // extract schemas that are in the external registry
-      if (params.external) {
-        const ext = params.external.registry.get(entry[0])?.id;
-        if (schema !== entry[0] && ext) {
-          extractToDef(entry);
-          continue;
-        }
-      }
+  delete schema.anyOf;
+  // A `type` array must be non-empty and unique (metaschema); a single member is spelled as a bare string.
+  schema.type = types.length === 1 ? types[0] : types;
+}
 
-      // extract schemas with `id` meta
-      const id = this.metadataRegistry.get(entry[0])?.id;
-      if (id) {
-        extractToDef(entry);
-        continue;
-      }
+/** Keywords `foldIntersection` knows how to combine. Anything else — `$ref`, `patternProperties`,
+ * an annotation like `description` — makes a member unfoldable, so a constraint this does not
+ * understand leaves the `allOf` alone instead of being silently dropped or misattributed. */
+const FOLDABLE_KEYS = new Set(["type", "properties", "required", "additionalProperties"]);
+const UNION_KEYS = ["oneOf", "anyOf"] as const;
+
+/** A member's constraint on a key it does not declare itself. A `catchall` states one; `false`, an absent `additionalProperties`, and the empty schema a loose object emits state nothing. */
+function undeclaredConstraint(member: JSONSchema.ObjectSchema): JSONSchema.BaseSchema | null {
+  const extra = member.additionalProperties;
+  if (extra === undefined || extra === false || typeof extra !== "object" || extra === null) return null;
+  return Object.keys(extra).length ? (extra as JSONSchema.BaseSchema) : null;
+}
 
-      // break cycles
-      if (seen.cycle) {
-        // any
-        extractToDef(entry);
-        continue;
-      }
+/** Combines object members into the single object they describe together, or returns `null` if any of them carries a keyword outside {@link FOLDABLE_KEYS}. */
+function foldObjects(members: JSONSchema._JSONSchema[]): JSONSchema.ObjectSchema | null {
+  const objects: JSONSchema.ObjectSchema[] = [];
+  for (const member of members) {
+    // A boolean subschema is legal JSON Schema and carries no keywords to fold.
+    if (typeof member !== "object" || member.type !== "object") return null;
+    for (const key in member) {
+      if (!FOLDABLE_KEYS.has(key)) return null;
+    }
+    objects.push(member as JSONSchema.ObjectSchema);
+  }
 
-      // extract reused schemas
-      if (seen.count > 1) {
-        if (params.reused === "ref") {
-          extractToDef(entry);
-          // biome-ignore lint:
-          continue;
-        }
+  const properties: Record<string, JSONSchema._JSONSchema> = {};
+  const required = new Set<string>();
+  for (const object of objects) {
+    for (const key in object.properties) {
+      // `in` would report a `__proto__` key as already present via the prototype chain and skip it.
+      if (Object.prototype.hasOwnProperty.call(properties, key)) continue;
+      // Every member constrains this key: the ones that declare it say how, and a `catchall` member constrains it too even though it does not name it. The key has to satisfy all of them, which is the same intersection one level down.
+      const parts: JSONSchema._JSONSchema[] = [];
+      for (const other of objects) {
+        const part = other.properties?.[key] ?? undeclaredConstraint(other);
+        if (part === null || part === undefined) continue;
+        if (!parts.some((seen) => JSON.stringify(seen) === JSON.stringify(part))) parts.push(part);
       }
+      const merged =
+        parts.length === 1
+          ? parts[0]!
+          : (foldObjects(parts) ?? ({ allOf: parts as JSONSchema.BaseSchema[] } as JSONSchema.BaseSchema));
+      assignProp(properties, key, merged);
+    }
+    for (const key of object.required ?? []) required.add(key);
+  }
+
+  const folded: JSONSchema.ObjectSchema = { type: "object", properties };
+  if (required.size) folded.required = [...required];
+  // A key no member declares is rejected only when every member rejects it, so the fold is closed only when every member is. Otherwise it carries whatever the `catchall` members demand of such a key.
+  if (objects.every((object) => object.additionalProperties === false)) {
+    folded.additionalProperties = false;
+  } else {
+    const constraints: JSONSchema.BaseSchema[] = [];
+    for (const object of objects) {
+      const constraint = undeclaredConstraint(object);
+      if (constraint && !constraints.some((seen) => JSON.stringify(seen) === JSON.stringify(constraint)))
+        constraints.push(constraint);
     }
+    if (constraints.length === 1) folded.additionalProperties = constraints[0]!;
+    else if (constraints.length > 1) folded.additionalProperties = { allOf: constraints };
+  }
+  return folded;
+}
+
+/** `additionalProperties` in an `allOf` member sees only that member's own `properties`, so two
+ * closed object members reject each other's keys and the schema validates nothing. Zod's parser
+ * pools the key sets instead — `handleIntersectionResults` reports a key as unrecognized only when
+ * *every* side rejects it — so the emitted schema has to pool them too, and folding the members
+ * into one object is the encoding that says so on every target.
+ *
+ * This runs from `finalize`, after `extractDefs`, which is what keeps it clear of the `$ref`
+ * machinery: a member extracted into `$defs` is already a `$ref` by now and declines to fold, so it
+ * keeps its reference and its own closedness rather than being inlined as a stale copy. */
+function foldIntersection(json: JSONSchema.BaseSchema): void {
+  const allOf = json.allOf;
+  if (!Array.isArray(allOf) || allOf.length < 2) return;
+  // An `override` runs before this pass and may have written object keywords onto the intersection itself. Those are deliberate, so decline rather than overwrite them.
+  for (const key of FOLDABLE_KEYS) if (key in json) return;
+
+  // An intersection distributes over a union: `A & (X | Y)` is `(A & X) | (A & Y)`. Only the first union is distributed over; a second one stays among the members every branch folds against, where it fails the object check and declines the whole intersection rather than multiplying out.
+  const unions = allOf.filter((m) => UNION_KEYS.some((k) => Array.isArray(m[k])));
+
+  let folded: JSONSchema.BaseSchema | null = null;
+  if (!unions.length) {
+    folded = foldObjects(allOf);
+  } else {
+    const union = unions[0]!;
+    const keyword = UNION_KEYS.find((k) => Array.isArray(union[k]))!;
+    if (Object.keys(union).length !== 1) return;
+    const rest = allOf.filter((m) => m !== union);
+    const branches = (union[keyword] as JSONSchema._JSONSchema[]).map((branch) => foldObjects([...rest, branch]));
+    if (branches.some((b) => !b)) return;
+    folded = { [keyword]: branches } as JSONSchema.BaseSchema;
+  }
+  if (!folded) return;
+
+  delete json.allOf;
+  assignProps(json, folded);
+}
+
+export function finalize<T extends schemas.$ZodType>(
+  ctx: ToJSONSchemaContext,
+  schema: T
+): ZodStandardJSONSchemaPayload<T> {
+  const root = ctx.seen.get(schema);
+  if (!root) throw new Error("Unprocessed schema. This is a bug in Zod.");
 
-    // flatten _refs
-    const flattenRef = (zodSchema: schemas.$ZodType, params: Pick<ToJSONSchemaParams, "target">) => {
-      const seen = this.seen.get(zodSchema)!;
-      const schema = seen.def ?? seen.schema;
+  // flatten refs - inherit properties from parent schemas
+  const flattenRef = (zodSchema: schemas.$ZodType) => {
+    const seen = ctx.seen.get(zodSchema)!;
 
-      const _cached = { ...schema };
+    // already processed
+    if (seen.ref === null) return;
 
-      // already seen
-      if (seen.ref === null) {
-        return;
+    const schema = seen.def ?? seen.schema;
+    const _cached = { ...schema };
+
+    const ref = seen.ref;
+    seen.ref = null; // prevent infinite recursion
+
+    if (ref) {
+      flattenRef(ref);
+
+      const refSeen = ctx.seen.get(ref)!;
+      const refSchema = refSeen.schema;
+
+      // merge referenced schema into current
+      if (refSchema.$ref && (ctx.target === "draft-07" || ctx.target === "draft-04" || ctx.target === "openapi-3.0")) {
+        // older drafts can't combine $ref with other properties
+        schema.allOf = schema.allOf ?? [];
+        schema.allOf.push(refSchema);
+      } else {
+        assignProps(schema, refSchema);
       }
+      // restore child's own properties (child wins)
+      assignProps(schema, _cached);
+
+      const isParentRef = zodSchema._zod.parent === ref;
 
-      // flatten ref if defined
-      const ref = seen.ref;
-      seen.ref = null; // prevent recursion
-      if (ref) {
-        flattenRef(ref, params);
-
-        // merge referenced schema into current
-        const refSchema = this.seen.get(ref)!.schema;
-        if (refSchema.$ref && params.target === "draft-7") {
-          schema.allOf = schema.allOf ?? [];
-          schema.allOf.push(refSchema);
-        } else {
-          Object.assign(schema, refSchema);
-          Object.assign(schema, _cached); // prevent overwriting any fields in the original schema
+      // For parent chain, child is a refinement - remove parent-only properties
+      if (isParentRef) {
+        for (const key in schema) {
+          if (key === "$ref" || key === "allOf") continue;
+          if (!(key in _cached)) {
+            delete schema[key];
+          }
         }
       }
 
-      // execute overrides
-      if (!seen.isParent)
-        this.override({
-          zodSchema: zodSchema as schemas.$ZodTypes,
-          jsonSchema: schema,
-          path: seen.path ?? [],
-        });
-    };
-
-    for (const entry of [...this.seen.entries()].reverse()) {
-      flattenRef(entry[0], { target: this.target });
+      // When ref was extracted to $defs, remove properties that match the definition
+      if (refSchema.$ref && refSeen.def) {
+        for (const key in schema) {
+          if (key === "$ref" || key === "allOf") continue;
+          if (key in refSeen.def && JSON.stringify(schema[key]) === JSON.stringify(refSeen.def[key])) {
+            delete schema[key];
+          }
+        }
+      }
     }
 
-    const result: JSONSchema.BaseSchema = {};
-    if (this.target === "draft-2020-12") {
-      result.$schema = "https://json-schema.org/draft/2020-12/schema";
-    } else if (this.target === "draft-7") {
-      result.$schema = "http://json-schema.org/draft-07/schema#";
-    } else {
-      console.warn(`Invalid target: ${this.target}`);
+    // If parent was extracted (has $ref), propagate $ref to this schema. This handles cases like: readonly().meta({id}).describe() where processor sets ref to innerType but parent should be referenced
+    const parent = zodSchema._zod.parent;
+    if (parent && parent !== ref) {
+      // Ensure parent is processed first so its def has inherited properties
+      flattenRef(parent);
+      const parentSeen = ctx.seen.get(parent);
+      if (parentSeen?.schema.$ref) {
+        schema.$ref = parentSeen.schema.$ref;
+        // De-duplicate with parent's definition
+        if (parentSeen.def) {
+          for (const key in schema) {
+            if (key === "$ref" || key === "allOf") continue;
+            if (key in parentSeen.def && JSON.stringify(schema[key]) === JSON.stringify(parentSeen.def[key])) {
+              delete schema[key];
+            }
+          }
+        }
+      }
     }
 
-    if (params.external?.uri) {
-      const id = params.external.registry.get(schema)?.id;
-      if (!id) throw new Error("Schema is missing an `id` property");
-      result.$id = params.external.uri(id);
+    // execute overrides
+    ctx.override({
+      zodSchema: zodSchema as schemas.$ZodTypes,
+      jsonSchema: schema,
+      path: seen.path ?? [],
+    });
+  };
+
+  // Flattening walks the whole map and clears each `ref` as it goes, so a second call over the same map is a no-op scan. Skip it outright once it has run for a registry conversion.
+  if (!ctx.external || ctx.sharedEmitDoneFor !== ctx.external) {
+    for (const entry of [...ctx.seen.entries()].reverse()) {
+      flattenRef(entry[0]);
     }
 
-    Object.assign(result, root.def);
-
-    // build defs object
-    const defs: JSONSchema.BaseSchema["$defs"] = params.external?.defs ?? {};
-    for (const entry of this.seen.entries()) {
-      const seen = entry[1];
-      if (seen.def && seen.defId) {
-        defs[seen.defId] = seen.def;
+    if (ctx.target !== "openapi-3.0") {
+      for (const entry of ctx.seen.entries()) {
+        compactTypeUnion(entry[1].def ?? entry[1].schema);
       }
     }
 
-    // set definitions in result
-    if (params.external) {
-    } else {
-      if (Object.keys(defs).length > 0) {
-        if (this.target === "draft-2020-12") {
-          result.$defs = defs;
-        } else {
-          result.definitions = defs;
+    for (const rewrite of ctx.deferred) rewrite();
+
+    // After flattening, every member that was extracted is a `$ref`, so the fold sees the final shape. A schema that inherits an intersection — through `z.lazy`, or any `ref` chain — holds the same `allOf` array, so fold by array identity to catch every copy.
+    if (ctx.intersections.length) {
+      const carriers = new Map<JSONSchema.BaseSchema[], JSONSchema.BaseSchema[]>();
+      for (const seen of ctx.seen.values()) {
+        for (const json of [seen.schema, seen.def]) {
+          const allOf = json?.allOf as JSONSchema.BaseSchema[] | undefined;
+          if (!Array.isArray(allOf)) continue;
+          const existing = carriers.get(allOf);
+          if (existing) existing.push(json!);
+          else carriers.set(allOf, [json!]);
         }
       }
+      for (const allOf of ctx.intersections) {
+        for (const json of carriers.get(allOf) ?? []) foldIntersection(json);
+      }
     }
+  }
 
-    try {
-      // this "finalizes" this schema and ensures all cycles are removed
-      // each call to .emit() is functionally independent
-      // though the seen map is shared
-      return JSON.parse(JSON.stringify(result));
-    } catch (_err) {
-      throw new Error("Error converting schema to JSON.");
-    }
+  const result: JSONSchema.BaseSchema = {};
+  if (ctx.target === "draft-2020-12") {
+    result.$schema = "https://json-schema.org/draft/2020-12/schema";
+  } else if (ctx.target === "draft-07") {
+    result.$schema = "http://json-schema.org/draft-07/schema#";
+  } else if (ctx.target === "draft-04") {
+    result.$schema = "http://json-schema.org/draft-04/schema#";
+  } else if (ctx.target === "openapi-3.0") {
+    // OpenAPI 3.0 schema objects should not include a $schema property
+  } else {
+    // Arbitrary string values are allowed but won't have a $schema property set
   }
-}
 
-interface ToJSONSchemaParams extends Omit<JSONSchemaGeneratorParams & EmitParams, "external"> {}
-interface RegistryToJSONSchemaParams extends Omit<JSONSchemaGeneratorParams & EmitParams, "external"> {
-  uri?: (id: string) => string;
-}
+  if (ctx.external?.uri) {
+    const id = ctx.external.registry.get(schema)?.id;
+    if (!id) throw new Error("Schema is missing an `id` property");
+    result.$id = ctx.external.uri(id);
+  }
 
-export function toJSONSchema(schema: schemas.$ZodType, _params?: ToJSONSchemaParams): JSONSchema.BaseSchema;
-export function toJSONSchema(
-  registry: $ZodRegistry<{ id?: string | undefined }>,
-  _params?: RegistryToJSONSchemaParams
-): { schemas: Record<string, JSONSchema.BaseSchema> };
-export function toJSONSchema(
-  input: schemas.$ZodType | $ZodRegistry<{ id?: string | undefined }>,
-  _params?: ToJSONSchemaParams
-): any {
-  if (input instanceof $ZodRegistry) {
-    const gen = new JSONSchemaGenerator(_params);
-    const defs: any = {};
-    for (const entry of input._idmap.entries()) {
-      const [_, schema] = entry;
-      gen.process(schema);
-    }
+  // when the root was extracted into $defs, `root.schema` is the `$ref` wrapper and `root.def` is the body that now lives under $defs
+  assignProps(result, root.defId ? root.schema : (root.def ?? root.schema));
 
-    const schemas: Record<string, JSONSchema.BaseSchema> = {};
-    const external = {
-      registry: input,
-      uri: (_params as RegistryToJSONSchemaParams)?.uri,
-      defs,
-    };
-    for (const entry of input._idmap.entries()) {
-      const [key, schema] = entry;
-      schemas[key] = gen.emit(schema, {
-        ..._params,
-        external,
-      });
+  // The `id` in `.meta()` is a Zod-specific registration tag used to extract schemas into $defs — it is not user-facing JSON Schema metadata. Strip it from the output body where it would otherwise leak. The id is preserved implicitly via the $defs key (and via $ref paths).
+  const rootMetaId = ctx.metadataRegistry.get(schema)?.id;
+  if (rootMetaId !== undefined && result.id === rootMetaId) delete result.id;
+
+  // build defs object. With `external`, `defs` is the shared object every schema writes into, so the same entries are reassigned on every call. Without it, `defs` is fresh per call and must be rebuilt.
+  const defs: JSONSchema.BaseSchema["$defs"] = ctx.external?.defs ?? {};
+  if (!ctx.external || ctx.sharedEmitDoneFor !== ctx.external) {
+    for (const entry of ctx.seen.entries()) {
+      const seen = entry[1];
+      if (seen.def && seen.defId) {
+        if (seen.def.id === seen.defId) delete seen.def.id;
+        assignProp(defs, seen.defId, seen.def);
+      }
     }
+  }
+  if (ctx.external) ctx.sharedEmitDoneFor = ctx.external;
 
+  // set definitions in result
+  if (ctx.external) {
+  } else {
     if (Object.keys(defs).length > 0) {
-      const defsSegment = gen.target === "draft-2020-12" ? "$defs" : "definitions";
-      schemas.__shared = {
-        [defsSegment]: defs,
-      };
+      if (ctx.target === "draft-2020-12") {
+        result.$defs = defs;
+      } else {
+        result.definitions = defs;
+      }
     }
-
-    return { schemas };
   }
 
-  const gen = new JSONSchemaGenerator(_params);
-  gen.process(input);
-
-  return gen.emit(input, _params);
+  try {
+    // this "finalizes" this schema and ensures all cycles are removed each call to finalize() is functionally independent though the seen map is shared
+    const finalized = JSON.parse(JSON.stringify(result));
+    Object.defineProperty(finalized, "~standard", {
+      value: {
+        ...schema["~standard"],
+        jsonSchema: {
+          input: createStandardJSONSchemaMethod(schema, "input", ctx.processors),
+          output: createStandardJSONSchemaMethod(schema, "output", ctx.processors),
+        },
+      },
+      enumerable: false,
+      writable: false,
+    });
+
+    return finalized;
+  } catch (_err) {
+    throw new Error("Error converting schema to JSON.");
+  }
 }
 
 function isTransforming(
@@ -883,95 +768,90 @@ function isTransforming(
   if (ctx.seen.has(_schema)) return false;
   ctx.seen.add(_schema);
 
-  const schema = _schema as schemas.$ZodTypes;
-  const def = schema._zod.def;
-  switch (def.type) {
-    case "string":
-    case "number":
-    case "bigint":
-    case "boolean":
-    case "date":
-    case "symbol":
-    case "undefined":
-    case "null":
-    case "any":
-    case "unknown":
-    case "never":
-    case "void":
-    case "literal":
-    case "enum":
-    case "nan":
-    case "file":
-    case "template_literal":
-      return false;
-    case "array": {
-      return isTransforming(def.element, ctx);
-    }
-    case "object": {
-      for (const key in def.shape) {
-        if (isTransforming(def.shape[key]!, ctx)) return true;
-      }
-      return false;
-    }
-    case "union": {
-      for (const option of def.options) {
-        if (isTransforming(option, ctx)) return true;
-      }
-      return false;
-    }
-    case "intersection": {
-      return isTransforming(def.left, ctx) || isTransforming(def.right, ctx);
-    }
-    case "tuple": {
-      for (const item of def.items) {
-        if (isTransforming(item, ctx)) return true;
-      }
-      if (def.rest && isTransforming(def.rest, ctx)) return true;
-      return false;
-    }
-    case "record": {
-      return isTransforming(def.keyType, ctx) || isTransforming(def.valueType, ctx);
-    }
-    case "map": {
-      return isTransforming(def.keyType, ctx) || isTransforming(def.valueType, ctx);
-    }
-    case "set": {
-      return isTransforming(def.valueType, ctx);
-    }
+  const def = (_schema as schemas.$ZodTypes)._zod.def;
+
+  if (def.type === "transform") return true;
+
+  if (def.type === "array") return isTransforming(def.element, ctx);
+  if (def.type === "set") return isTransforming(def.valueType, ctx);
+  if (def.type === "lazy") return isTransforming(def.getter(), ctx);
+
+  if (
+    def.type === "promise" ||
+    def.type === "optional" ||
+    def.type === "nonoptional" ||
+    def.type === "nullable" ||
+    def.type === "readonly" ||
+    def.type === "default" ||
+    def.type === "prefault" ||
+    def.type === "catch"
+  ) {
+    return isTransforming(def.innerType, ctx);
+  }
 
-    // inner types
-    case "promise":
-    case "optional":
-    case "nonoptional":
-    case "nullable":
-    case "readonly":
-      return isTransforming(def.innerType, ctx);
-    case "lazy":
-      return isTransforming(def.getter(), ctx);
-    case "default": {
-      return isTransforming(def.innerType, ctx);
-    }
-    case "prefault": {
-      return isTransforming(def.innerType, ctx);
-    }
-    case "custom": {
-      return false;
-    }
-    case "transform": {
-      return true;
-    }
-    case "pipe": {
-      return isTransforming(def.in, ctx) || isTransforming(def.out, ctx);
+  if (def.type === "intersection") {
+    return isTransforming(def.left, ctx) || isTransforming(def.right, ctx);
+  }
+  if (def.type === "record" || def.type === "map") {
+    return isTransforming(def.keyType, ctx) || isTransforming(def.valueType, ctx);
+  }
+  if (def.type === "pipe") {
+    if (_schema._zod.traits.has("$ZodCodec")) return true;
+    return isTransforming(def.in, ctx) || isTransforming(def.out, ctx);
+  }
+
+  if (def.type === "object") {
+    for (const key in def.shape) {
+      if (isTransforming(def.shape[key]!, ctx)) return true;
     }
-    case "success": {
-      return false;
+    return false;
+  }
+  if (def.type === "union") {
+    for (const option of def.options) {
+      if (isTransforming(option, ctx)) return true;
     }
-    case "catch": {
-      return false;
+    return false;
+  }
+  if (def.type === "tuple") {
+    for (const item of def.items) {
+      if (isTransforming(item, ctx)) return true;
     }
-
-    default:
-      def satisfies never;
+    if (def.rest && isTransforming(def.rest, ctx)) return true;
+    return false;
   }
-  throw new Error(`Unknown schema type: ${(def as any).type}`);
+
+  return false;
 }
+
+export type ZodStandardSchemaWithJSON<T> = StandardSchemaWithJSONProps<core.input<T>, core.output<T>>;
+export interface ZodStandardJSONSchemaPayload<T> extends JSONSchema.BaseSchema {
+  "~standard": ZodStandardSchemaWithJSON<T>;
+}
+
+/**
+ * Creates a toJSONSchema method for a schema instance.
+ * This encapsulates the logic of initializing context, processing, extracting defs, and finalizing.
+ */
+export const createToJSONSchemaMethod =
+  <T extends schemas.$ZodType>(schema: T, processors: Record<string, Processor> = {}) =>
+  (params?: ToJSONSchemaParams): ZodStandardJSONSchemaPayload<T> => {
+    const ctx = initializeContext({ ...params, processors });
+    processSchema(schema, ctx);
+    extractDefs(ctx, schema);
+    return finalize(ctx, schema);
+  };
+
+/**
+ * Creates a toJSONSchema method for a schema instance.
+ * This encapsulates the logic of initializing context, processing, extracting defs, and finalizing.
+ */
+type StandardJSONSchemaMethodParams = Parameters<StandardJSONSchemaV1["~standard"]["jsonSchema"]["input"]>[0];
+export const createStandardJSONSchemaMethod =
+  <T extends schemas.$ZodType>(schema: T, io: "input" | "output", processors: Record<string, Processor> = {}) =>
+  (params?: StandardJSONSchemaMethodParams): JSONSchema.BaseSchema => {
+    const { libraryOptions, target } = params ?? {};
+    const ctx = initializeContext({ ...(libraryOptions ?? {}), target, io, processors });
+    processSchema(schema, ctx);
+    extractDefs(ctx, schema);
+    return finalize(ctx, schema);
+  };