fix(v4): resolve stack overflow in toJSONSchema for recursive lazy with describe (#5797)

* fix(v4): resolve stack overflow in toJSONSchema for recursive lazy with describe

When .describe() or .meta() is called on a recursive z.lazy() schema,
the clone re-evaluates the getter on each recursion level, producing
unbounded new schema objects. Walk up to the root lazy to reuse its
cached innerType instead.

Fixes #5777.

* fix(v4): cache lazy innerType on def so clones share identity

Move the recursion fix from the JSON-schema processor into the $ZodLazy
constructor. Caching the resolved inner type on the shared `def` means
all clones of a lazy (via .describe(), .meta(), etc.) resolve to the
same inner instance, so cycle detection works for any consumer — not
just toJSONSchema — and parsing no longer rebuilds a fresh subtree on
every access through a clone.

---------

Co-authored-by: Colin McDonnell <[email protected]>

Author: Hassad674

packages/zod/src/v4/classic/tests/to-json-schema.test.ts

@@ -3029,3 +3029,18 @@ test("cycle detection - mutual recursion", () => {
     Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.]
   `);
 });
+
+test("recursive lazy with describe does not stack overflow", () => {
+  const NodeSchema: z.ZodType = z.lazy(() =>
+    z
+      .object({
+        value: z.string().describe("node value"),
+        children: z.array(NodeSchema.describe("child node")).optional().describe("child list"),
+      })
+      .describe("tree node")
+  );
+
+  const result = z.toJSONSchema(NodeSchema, { cycles: "ref", reused: "ref" });
+  expect(result).toBeDefined();
+  expect(result.$defs).toBeDefined();
+});

packages/zod/src/v4/core/schemas.ts

@@ -4404,14 +4404,14 @@ export interface $ZodLazy<T extends SomeType = $ZodType> extends $ZodType {
 export const $ZodLazy: core.$constructor<$ZodLazy> = /*@__PURE__*/ core.$constructor("$ZodLazy", (inst, def) => {
   $ZodType.init(inst, def);
 
-  // let _innerType!: any;
-  // util.defineLazy(def, "getter", () => {
-  //   if (!_innerType) {
-  //     _innerType = def.getter();
-  //   }
-  //   return () => _innerType;
-  // });
-  util.defineLazy(inst._zod, "innerType", () => def.getter() as $ZodType);
+  // Cache the resolved inner type on the shared `def` so all clones of this
+  // lazy (e.g. via `.describe()`/`.meta()`) share the same inner instance,
+  // preserving identity for cycle detection on recursive schemas.
+  util.defineLazy(inst._zod, "innerType", () => {
+    const d = def as $ZodLazyDef & { _cachedInner?: $ZodType };
+    if (!d._cachedInner) d._cachedInner = def.getter() as $ZodType;
+    return d._cachedInner;
+  });
   util.defineLazy(inst._zod, "pattern", () => inst._zod.innerType?._zod?.pattern);
   util.defineLazy(inst._zod, "propValues", () => inst._zod.innerType?._zod?.propValues);
   util.defineLazy(inst._zod, "optin", () => inst._zod.innerType?._zod?.optin ?? undefined);