@githolon/dsl 0.54.1 → 0.54.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.54.1",
+  "version": "0.54.2",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/codegen_dart.ts

@@ -30,6 +30,7 @@
  */
 import { z } from "zod";
 import { voMetaOf, collectPayloadValueObjectDescriptors, idOfMetaOf, brandedIdMetaOf, NOMOS_UNIT_BRAND } from "./value_object.js";
+import { recursiveTypeBaseName, zodUnwrapLazy } from "./zod_lazy.js";
 import type { AggregateHandle } from "./aggregate.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import type { RelationTypeDecl } from "./relation_schema.js";
@@ -93,8 +94,23 @@ type ZodInternalDef = {
   value?: unknown;
   values?: readonly unknown[];
   valueType?: z.ZodTypeAny;
+  getter?: () => z.ZodTypeAny; // `z.lazy(() => …)` — the deferred inner schema (zod v4)
 };
 
+/** Resolve `z.lazy(() => …)` chains to the first non-lazy schema, with an identity-keyed
+ *  visited guard so a directly self-referencing lazy (`z.lazy(() => TheLazy)`) can't loop.
+ *  A non-lazy schema returns unchanged. */
+function resolveLazy(zt: z.ZodTypeAny): z.ZodTypeAny {
+  const seen = new Set<z.ZodTypeAny>();
+  let cur = zt;
+  while (zodDef(cur).type === "lazy" && typeof zodDef(cur).getter === "function") {
+    if (seen.has(cur)) return cur; // pathological lazy→lazy cycle — stop (caller degrades)
+    seen.add(cur);
+    cur = zodDef(cur).getter!();
+  }
+  return cur;
+}
+
 function zodDef(zt: z.ZodTypeAny): ZodInternalDef {
   const raw = zt as unknown as { _def?: ZodInternalDef; def?: ZodInternalDef };
   return raw._def ?? raw.def ?? {};
@@ -210,6 +226,7 @@ function zodNumberIsInt(zt: z.ZodTypeAny): boolean {
 export function introspectPayload(
   schema: z.ZodTypeAny,
   enumDartTypes: Map<string, string>,
+  lazyNames?: Map<z.ZodTypeAny, string>,
 ): PayloadFieldSpec[] {
   if (zodTypeName(schema) !== "ZodObject") {
     throw new Error("directive payload must be a z.object");
@@ -226,7 +243,7 @@ export function introspectPayload(
       optional = true;
       zt = zodInnerType(zt);
     }
-    out.push({ ...introspectField(name, zt, enumDartTypes), optional });
+    out.push({ ...introspectField(name, zt, enumDartTypes, lazyNames), optional });
   }
   return out;
 }
@@ -239,7 +256,26 @@ function introspectField(
   name: string,
   zt: z.ZodTypeAny,
   enumDartTypes: Map<string, string>,
+  lazyNames?: Map<z.ZodTypeAny, string>,
 ): Omit<PayloadFieldSpec, "optional"> {
+  // RECURSIVE `z.lazy` (a self-referencing tree/JSON payload): if the compiler synthesized a
+  // typed recursive class for this knot (`lazyNames`), the field IS that class (toJson via its
+  // `.toJson()`). Without a synthesized class (no map, or a degraded knot) it resolves one level
+  // and flows into the opaque-JSON lane below (`Map<String,Object?>`) — the last-resort fallback.
+  if (zodTypeName(zt) === "ZodLazy") {
+    const cls = lazyNames?.get(zt);
+    if (cls !== undefined) return { name, dartType: cls, toJson: "vo" };
+    // No synthesized class (no map, or a DEGRADED knot — e.g. a lazy of a union): last-resort
+    // opaque JSON. Resolve one level and reuse the normal lane, but any shape the lane can't
+    // express (union, undeclared nested object) falls back to `Object?` rather than throwing.
+    const inner = resolveLazy(zt);
+    if (zodTypeName(inner) === "ZodLazy") return { name, dartType: "Object?", toJson: "json" };
+    try {
+      return introspectField(name, inner, enumDartTypes, lazyNames);
+    } catch {
+      return { name, dartType: "Object?", toJson: "json" };
+    }
+  }
   // A DECLARED VO/union keeps its name regardless of its zod kind (a union(...) is a
   // z.discriminatedUnion, not a ZodObject — without this it would fall to the throw lane).
   {
@@ -298,6 +334,11 @@ function introspectField(
       if (zodTypeName(elem) === "ZodString") {
         return { name, dartType: "List<String>", toJson: "strList" };
       }
+      // A list of a RECURSIVE `z.lazy` knot (a synthesized class) is a typed `List<Class>`.
+      const elemCls = zodTypeName(elem) === "ZodLazy" ? lazyNames?.get(elem) : undefined;
+      if (elemCls !== undefined) {
+        return { name, dartType: `List<${elemCls}>`, toJson: "voList" };
+      }
       const elemVo = voMetaOf(elem);
       if (elemVo !== undefined) {
         return { name, dartType: `List<${elemVo.name}>`, toJson: "voList" };
@@ -2176,9 +2217,10 @@ function emitDirective(
   d: AnyDirective,
   domainName: string,
   enumDartTypes: Map<string, string>,
+  lazyNames?: Map<z.ZodTypeAny, string>,
 ): string {
   const className = `${cap(d.id)}Payload`;
-  const specs = introspectPayload(d.payloadSchema as z.ZodTypeAny, enumDartTypes);
+  const specs = introspectPayload(d.payloadSchema as z.ZodTypeAny, enumDartTypes, lazyNames);
 
   // Field decls: optional payload fields are nullable Dart fields (omitted from the
   // payload JSON when null); required fields are non-null + `required` in the ctor.
@@ -2270,6 +2312,159 @@ export function toJsonExpr(spec: PayloadFieldSpec, accessor: string): string {
   }
 }
 
+// ── RECURSIVE `z.lazy` payloads → synthesized Dart classes (full support) ─────────
+//
+// A self-referencing payload schema (`TreeNode = z.lazy(() => z.object({ label, children:
+// z.array(TreeNode).optional() }))`) is FULLY typed in Dart, not degraded: each lazy KNOT
+// becomes a real recursive `class` reusing the value-object class emitter — its `children`
+// field types as `List<SaveTreeRoot>?`, i.e. itself. We synthesize a `ValueObjectDescriptor`
+// per knot (a `{type:"object", ref:<self>}` field is the recursion, which the VO emitter
+// renders by NAME, so emission never loops) and route the payload field to it.
+//
+// A knot whose shape is NOT expressible as a VO field set (e.g. a lazy of a union, or an
+// interior undeclared nested object) is the ONE last-resort degrade: it drops to `Object?`
+// (opaque JSON) and its path is reported. The common tree/JSON recursion never degrades.
+
+export interface SynthesizedRecursiveTypes {
+  /** lazy zod identity → generated Dart class name (SUCCESSFULLY synthesized knots only). */
+  readonly names: Map<z.ZodTypeAny, string>;
+  /** generated recursive-class descriptors, keyed by class name (fed to [emitValueObjectClass]). */
+  readonly descriptors: Map<string, ValueObjectDescriptor>;
+  /** knot paths that could NOT be represented as a class (degraded to `Object?`) — reported. */
+  readonly degraded: string[];
+}
+
+/** Synthesize the recursive-payload Dart classes for a module's directives (see the block header). */
+export function synthesizeRecursivePayloadTypes(
+  directives: readonly { payloadSchema?: unknown; id?: string }[],
+): SynthesizedRecursiveTypes {
+  const names = new Map<z.ZodTypeAny, string>();
+  const descriptors = new Map<string, ValueObjectDescriptor>();
+  const used = new Set<string>();
+  const degraded: string[] = [];
+
+  const mint = (path: string): string => {
+    const base = recursiveTypeBaseName(path);
+    let n = base;
+    for (let i = 2; used.has(n); i++) n = `${base}${i}`;
+    used.add(n);
+    return n;
+  };
+
+  // ONE zod field inside a knot → its VO field descriptor. THROWS for a shape the VO field set
+  // can't express (→ the enclosing knot degrades). A nested lazy recurses into [buildKnot].
+  const fieldOf = (zt: z.ZodTypeAny, path: string): ValueObjectFieldDescriptor => {
+    if (zodTypeName(zt) === "ZodOptional" || zodTypeName(zt) === "ZodDefault") {
+      return { ...fieldOf(zodInnerType(zt), path), optional: true };
+    }
+    if (zodTypeName(zt) === "ZodLazy") {
+      const ref = buildKnot(zt, path);
+      if (ref === undefined) throw new Error("recursive knot degraded");
+      return { type: "object", ref };
+    }
+    const vo = voMetaOf(zt);
+    if (vo !== undefined) {
+      return vo.geometry !== undefined
+        ? { type: "geometry", ref: vo.name, geometry: vo.geometry }
+        : { type: "object", ref: vo.name };
+    }
+    switch (zodTypeName(zt)) {
+      case "ZodString": {
+        const b = brandedIdMetaOf(zt);
+        if (b !== undefined) return { type: "string", brand: b };
+        const idAgg = idOfMetaOf(zt);
+        if (idAgg !== undefined) return { type: "string", brand: `${idAgg}Id` };
+        return { type: "string" };
+      }
+      case "ZodNumber": {
+        const unit = (zt as unknown as Record<symbol, unknown>)[NOMOS_UNIT_BRAND];
+        return {
+          type: "number",
+          ...(zodNumberIsInt(zt) ? { int: true as const } : {}),
+          ...(typeof unit === "string" ? { unit } : {}),
+        };
+      }
+      case "ZodBoolean":
+        return { type: "boolean" };
+      case "ZodEnum":
+        return { type: "enum", values: zodEnumValues(zt) };
+      case "ZodLiteral": {
+        const v = zodLiteralValue(zt);
+        if (typeof v !== "string") throw new Error("non-string literal");
+        return { type: "literal", value: v };
+      }
+      case "ZodArray": {
+        const items = fieldOf(zodArrayElement(zt), `${path}[]`);
+        if (items.optional === true) throw new Error("array of optionals");
+        return { type: "array", items };
+      }
+      case "ZodRecord": {
+        const vt = zodRecordValueType(zt);
+        if (vt === undefined) throw new Error("record without value type");
+        const values = fieldOf(vt, `${path}.*`);
+        if (values.optional === true) throw new Error("record of optionals");
+        return { type: "map", values };
+      }
+      default:
+        throw new Error(`unsupported field shape '${zodTypeName(zt)}'`);
+    }
+  };
+
+  // Build (once) the class descriptor for a lazy knot. Returns its class name, or undefined if
+  // the knot degrades. Registers the name BEFORE recursing so a self-reference resolves cleanly.
+  const buildKnot = (lazyZt: z.ZodTypeAny, path: string): string | undefined => {
+    const existing = names.get(lazyZt);
+    if (existing !== undefined) return existing;
+    const name = mint(path);
+    names.set(lazyZt, name);
+    const obj = zodUnwrapLazy(lazyZt);
+    if (zodTypeName(obj) !== "ZodObject") {
+      names.delete(lazyZt);
+      degraded.push(path);
+      return undefined;
+    }
+    const fields: Record<string, ValueObjectFieldDescriptor> = {};
+    try {
+      const shape = zodObjectShape(obj);
+      for (const key of Object.keys(shape).sort()) fields[key] = fieldOf(shape[key]!, `${path}.${key}`);
+    } catch {
+      names.delete(lazyZt);
+      degraded.push(path);
+      return undefined;
+    }
+    descriptors.set(name, { name, fields });
+    return name;
+  };
+
+  // Find the outermost lazy knots reachable from each payload field (through optional/array).
+  const findKnots = (zt: z.ZodTypeAny, path: string): void => {
+    switch (zodTypeName(zt)) {
+      case "ZodLazy":
+        buildKnot(zt, path);
+        return;
+      case "ZodOptional":
+      case "ZodDefault":
+        findKnots(zodInnerType(zt), path);
+        return;
+      case "ZodArray":
+        findKnots(zodArrayElement(zt), `${path}[]`);
+        return;
+      default:
+        return;
+    }
+  };
+
+  for (const d of directives) {
+    const schema = d?.payloadSchema as z.ZodTypeAny | undefined;
+    if (!schema || typeof schema !== "object" || zodTypeName(schema) !== "ZodObject") continue;
+    const dirId = d.id ?? "";
+    for (const [key, raw] of Object.entries(zodObjectShape(schema))) {
+      findKnots(raw as z.ZodTypeAny, `${dirId}.${key}`);
+    }
+  }
+  return { names, descriptors, degraded };
+}
+
 // ---- read accessors (typed subscriptions) ----------------------------------
 //
 // The READ half of the peer query surface (Jack 2026-06-18): the app reads ONLY via
@@ -3314,7 +3509,14 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   // the aggregate-derived set. Codegen-only: the IR key stays aggregate-derived (era rule).
   const aggVoNames = new Set((mod.valueObjects ?? []).map((d) => d.name));
   const payloadVos = collectPayloadValueObjectDescriptors(mod.directives ?? []).filter((d) => !aggVoNames.has(d.name));
-  const localValueObjects = [...(mod.valueObjects ?? []), ...payloadVos]
+  // RECURSIVE `z.lazy` payloads → synthesized recursive-class descriptors (full support). They
+  // are codegen-only (like payloadVos): the law IR / domainHash never sees them (era rule). The
+  // name map routes each recursive payload field to its class in [emitDirective].
+  const recursiveTypes = synthesizeRecursivePayloadTypes(mod.directives ?? []);
+  const recursiveDescriptors = [...recursiveTypes.descriptors.values()].filter(
+    (d) => !aggVoNames.has(d.name) && !payloadVos.some((p) => p.name === d.name),
+  );
+  const localValueObjects = [...(mod.valueObjects ?? []), ...payloadVos, ...recursiveDescriptors]
     .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
     .filter((d) => !skipValueObjectNames.has(d.name));
   // Each VO's block = its FIELD ENUMS (real Dart enums, tolerant fromWire) then its class —
@@ -3421,7 +3623,7 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   // the runtime aggregate-meta registry (lookup by op.aggregateType — generic surfaces).
   const aggregateMetaBlock = emitAggregateMetaRegistry(domainKey, localAggregates);
   const dirBlock = localDirectives
-    .map((d) => emitDirective(d, domainKey, dartTypes))
+    .map((d) => emitDirective(d, domainKey, dartTypes, recursiveTypes.names))
     .join("\n\n");
 
   // TYPED IDS + MINTED CREATES (the id-mint keystone, GENERALIZED): a DISTINCT typed

package/src/codegen_proof.ts

@@ -60,8 +60,12 @@ import {
   zodEnumValues,
   zodKind,
   zodObjectShape,
+  zodUnwrapLazy,
 } from "./codegen_ts.js";
 
+/** Shared empty visited-set for the lazy-recursion guard (no allocation on the common path). */
+const EMPTY_LAZY_VISITED: ReadonlySet<z.ZodTypeAny> = new Set();
+
 const camel = (s: string) => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
 const lcFirst = (s: string) => (s.length ? s[0]!.toLowerCase() + s.slice(1) : s);
 
@@ -124,7 +128,28 @@ function joinIssuePath(base: string, segs: readonly PropertyKey[]): string {
  * names the exact field (`controlPoints[0].geoPoint.latitude`, never a bare leaf or "field ?"). NO
  * FALLBACK: an unhandled shape throws, naming the path and the remedy.
  */
-function sampleOfZod(zt: z.ZodTypeAny, path: string, where: string, voIncludeOptional = false): unknown {
+function sampleOfZod(
+  zt: z.ZodTypeAny,
+  path: string,
+  where: string,
+  voIncludeOptional = false,
+  visited: ReadonlySet<z.ZodTypeAny> = EMPTY_LAZY_VISITED,
+): unknown {
+  // RECURSIVE `z.lazy` (a self-referencing tree/JSON payload): unwrap one level, tracking the
+  // lazy object's IDENTITY on this descent. Re-entering the SAME lazy is a knot: sampling can go
+  // no deeper. The common case terminates NATURALLY one level up (the recursive branch is an
+  // OPTIONAL field, which the object case omits, or an ARRAY, which emits `[]`); only a REQUIRED
+  // non-array self-reference is genuinely unsampleable, and THAT throws with the exact path.
+  if (zodKind(zt) === "lazy") {
+    if (visited.has(zt)) {
+      throw new Error(
+        `codegen-proof: ${where} — field '${path}': recursive z.lazy schema — a REQUIRED self-reference makes a finite sample impossible; make the recursive field \`.optional()\` (proof omits it) or wrap it in an array (proof emits \`[]\`), or prove this directive by hand in test/e2e.mts`,
+      );
+    }
+    const next = new Set(visited);
+    next.add(zt);
+    return sampleOfZod(zodUnwrapLazy(zt), path, where, voIncludeOptional, next);
+  }
   // VALUE OBJECTS FIRST (vo_authoring_end_to_end.md slice C): a declared VO carries its own lawful
   // sample (the author's validated `example`, the blessed geometry sample, or per-field descriptor
   // synthesis, recursing through nested VOs / arrays-of-VOs / unions). The raw-zod walk below cannot
@@ -172,14 +197,17 @@ function sampleOfZod(zt: z.ZodTypeAny, path: string, where: string, voIncludeOpt
       // A one-element array satisfies `.min(1)` coverage; a string element keeps the readable
       // `sample-a` (constraint-probed) so golden outputs stay stable.
       if (zodKind(el) === "string") return [sampleString(el, "a")];
-      return [sampleOfZod(el, `${path}[0]`, where, voIncludeOptional)];
+      // A recursive array element (its lazy is already on this descent) bottoms out as `[]` —
+      // an empty array is a valid finite sample and breaks the recursion (depth-bound at 1).
+      if (zodKind(el) === "lazy" && visited.has(el)) return [];
+      return [sampleOfZod(el, `${path}[0]`, where, voIncludeOptional, visited)];
     }
     case "object": {
       const out: Record<string, unknown> = {};
       for (const [name, raw] of Object.entries(zodObjectShape(zt))) {
         const k = zodKind(raw as z.ZodTypeAny);
         if (k === "optional" || k === "default") continue; // optional → omit
-        out[name] = sampleOfZod(raw as z.ZodTypeAny, joinIssuePath(path, [name]), where, voIncludeOptional);
+        out[name] = sampleOfZod(raw as z.ZodTypeAny, joinIssuePath(path, [name]), where, voIncludeOptional, visited);
       }
       return out;
     }
@@ -188,10 +216,10 @@ function sampleOfZod(zt: z.ZodTypeAny, path: string, where: string, voIncludeOpt
     case "nullable":
     case "optional":
     case "default":
-      return sampleOfZod(zodDef(zt).innerType!, path, where, voIncludeOptional);
+      return sampleOfZod(zodDef(zt).innerType!, path, where, voIncludeOptional, visited);
     case "union": {
       const first = zodDef(zt).options?.[0];
-      if (first !== undefined) return sampleOfZod(first, path, where, voIncludeOptional);
+      if (first !== undefined) return sampleOfZod(first, path, where, voIncludeOptional, visited);
       throw new Error(`codegen-proof: ${where} — field '${path}': an empty union has no arm to sample`);
     }
     default:

package/src/codegen_ts.ts

@@ -43,6 +43,7 @@ import type { DomainModule } from "./codegen_dart.js";
 import type { NomosCompat } from "./compat_manifest.js";
 import type { QueryDecl } from "./query.js";
 import { voMetaOf, collectPayloadValueObjectDescriptors } from "./value_object.js";
+import { recursiveTypeBaseName, zodUnwrapLazy } from "./zod_lazy.js";
 import { finishCount } from "./count.js";
 import { finishSum } from "./sum.js";
 import type { DerivedDecl } from "./derived.js";
@@ -206,8 +207,13 @@ type ZodInternalDef = {
   value?: unknown;
   values?: readonly unknown[];
   valueType?: z.ZodTypeAny;
+  getter?: () => z.ZodTypeAny; // `z.lazy(() => …)` — the deferred inner schema (zod v4)
 };
 
+// The lazy-unwrap + recursive-name helpers live in the dependency-free `zod_lazy.ts` (shared with
+// codegen_dart WITHOUT an import cycle). Re-exported so codegen_proof's existing import holds.
+export { zodUnwrapLazy };
+
 export function zodDef(zt: z.ZodTypeAny): ZodInternalDef {
   const raw = zt as unknown as { _def?: ZodInternalDef; def?: ZodInternalDef };
   return raw._def ?? raw.def ?? {};
@@ -245,8 +251,44 @@ export function zodArrayElement(zt: z.ZodTypeAny): z.ZodTypeAny {
 const union = (parts: string[]) => [...new Set(parts)].join(" | ");
 const paren = (t: string) => (t.includes("|") || t.includes("&") ? `(${t})` : t);
 
-/** Recursive zod → TS type text. NO FALLBACK: an unhandled shape throws. */
-function tsTypeOfZod(zt: z.ZodTypeAny, indent: string): string {
+/**
+ * THE RECURSIVE-TYPE REGISTRY (`z.lazy` full support). A recursive payload schema (a `TreeNode`
+ * that references itself) can't be a finite inline literal — so at each lazy KNOT we MINT a stable
+ * named type alias (from the payload path — deterministic across compiles), emit its body ONCE, and
+ * reference the name everywhere it recurs. TS resolves named recursion natively for every shape, so
+ * NOTHING degrades: `type SaveTreeRoot = { label: string; children?: SaveTreeRoot[] }`. The `names`
+ * map (keyed on the lazy's object IDENTITY) doubles as the cycle guard — a re-encountered lazy
+ * returns its already-minted name. Mutual recursion A↔B mints two names by first-encounter path. */
+interface LazyTypeRegistry {
+  readonly names: Map<z.ZodTypeAny, string>; // lazy identity → minted type name (also the guard)
+  readonly decls: Map<string, string>; // name → `export type <Name> = <body>;` (dedup, deterministic)
+  readonly used: Set<string>; // all minted names — collision-avoidance across knots
+}
+
+function newLazyRegistry(): LazyTypeRegistry {
+  return { names: new Map(), decls: new Map(), used: new Set() };
+}
+
+/** Mint a UNIQUE PascalCase type name from a payload path; collisions get a numeric suffix. */
+function mintLazyTypeName(reg: LazyTypeRegistry, path: string): string {
+  const base = recursiveTypeBaseName(path);
+  let name = base;
+  for (let i = 2; reg.used.has(name); i++) name = `${base}${i}`;
+  reg.used.add(name);
+  return name;
+}
+
+/** Recursive zod → TS type text. NO FALLBACK for an unknown shape (it throws). A RECURSIVE
+ *  `z.lazy` knot is FULLY SUPPORTED: it mints a named type alias into `reg` and references it
+ *  (never `JsonValue`) — see {@link LazyTypeRegistry}. `reg` is absent only for standalone callers
+ *  (e.g. a query return) that can't host a named decl; a recursive lazy there is the one place the
+ *  `JsonValue` safety valve applies (query returns are read models, never recursive in practice). */
+function tsTypeOfZod(
+  zt: z.ZodTypeAny,
+  indent: string,
+  reg?: LazyTypeRegistry,
+  path = "",
+): string {
   // A DECLARED VALUE OBJECT keeps its NAME (vo_authoring_end_to_end.md slice B): the payload
   // references the same exported interface the read model uses — one name, both directions —
   // instead of an anonymous inline literal type. Checked on the BARE object only: optional/
@@ -256,6 +298,16 @@ function tsTypeOfZod(zt: z.ZodTypeAny, indent: string): string {
     if (vo !== undefined) return vo.name;
   }
   switch (zodKind(zt)) {
+    case "lazy": {
+      if (reg === undefined) return "JsonValue"; // safety valve (no host for a named decl)
+      const existing = reg.names.get(zt);
+      if (existing !== undefined) return existing; // already minted (the cycle guard)
+      const name = mintLazyTypeName(reg, path);
+      reg.names.set(zt, name); // register BEFORE recursing so self-references resolve to the name
+      const body = tsTypeOfZod(zodUnwrapLazy(zt), "", reg, path);
+      reg.decls.set(name, `export type ${name} = ${body};`);
+      return name;
+    }
     case "string":
       return "string";
     case "number":
@@ -270,7 +322,7 @@ function tsTypeOfZod(zt: z.ZodTypeAny, indent: string): string {
       return JSON.stringify(v);
     }
     case "array":
-      return `${paren(tsTypeOfZod(zodArrayElement(zt), indent))}[]`;
+      return `${paren(tsTypeOfZod(zodArrayElement(zt), indent, reg, `${path}[]`))}[]`;
     case "object": {
       const shape = zodObjectShape(zt);
       const inner = indent + "  ";
@@ -281,21 +333,21 @@ function tsTypeOfZod(zt: z.ZodTypeAny, indent: string): string {
           optional = true;
           f = zodDef(f).innerType!;
         }
-        return `${inner}${name}${optional ? "?" : ""}: ${tsTypeOfZod(f, inner)};`;
+        return `${inner}${name}${optional ? "?" : ""}: ${tsTypeOfZod(f, inner, reg, path === "" ? name : `${path}.${name}`)};`;
       });
       return fields.length ? `{\n${fields.join("\n")}\n${indent}}` : "Record<string, never>";
     }
     case "record": {
       const vt = zodDef(zt).valueType;
-      return `Record<string, ${vt ? tsTypeOfZod(vt, indent) : "unknown"}>`;
+      return `Record<string, ${vt ? tsTypeOfZod(vt, indent, reg, `${path}.*`) : "unknown"}>`;
     }
     case "optional":
     case "default":
-      return `${tsTypeOfZod(zodDef(zt).innerType!, indent)} | undefined`;
+      return `${tsTypeOfZod(zodDef(zt).innerType!, indent, reg, path)} | undefined`;
     case "nullable":
-      return `${tsTypeOfZod(zodDef(zt).innerType!, indent)} | null`;
+      return `${tsTypeOfZod(zodDef(zt).innerType!, indent, reg, path)} | null`;
     case "union":
-      return union((zodDef(zt).options ?? []).map((o) => tsTypeOfZod(o, indent)));
+      return union((zodDef(zt).options ?? []).map((o) => tsTypeOfZod(o, indent, reg, path)));
     case "unknown":
     case "any":
       return "unknown";
@@ -304,6 +356,57 @@ function tsTypeOfZod(zt: z.ZodTypeAny, indent: string): string {
   }
 }
 
+/**
+ * The RECURSIVE `z.lazy` knots in one directive payload, each reported as `{ path, name }` where
+ * `name` is the stable generated type minted for it (the SAME name {@link tsTypeOfZod} emits — the
+ * mint is deterministic from the path). Surfaced as a compile-summary NOTE so the tenant sees which
+ * fields became named recursive types (NOT a degrade — recursion is fully supported). `pathPrefix`
+ * (the directive id) scopes the minted names, matching the client's package-level registry. Empty
+ * for a lazy-free payload. */
+export function recursiveLazyTypes(schema: z.ZodTypeAny, pathPrefix = ""): { path: string; name: string }[] {
+  const reg = newLazyRegistry();
+  const out: { path: string; name: string }[] = [];
+  const walk = (zt: z.ZodTypeAny, path: string): void => {
+    switch (zodKind(zt)) {
+      case "lazy": {
+        if (reg.names.has(zt)) return; // already recorded (the cycle guard)
+        const name = mintLazyTypeName(reg, path);
+        reg.names.set(zt, name);
+        out.push({ path, name });
+        walk(zodUnwrapLazy(zt), path);
+        return;
+      }
+      case "array":
+        walk(zodArrayElement(zt), `${path}[]`);
+        return;
+      case "object": {
+        if (voMetaOf(zt) !== undefined) return; // a VO is an opaque leaf — don't descend
+        for (const [name, raw] of Object.entries(zodObjectShape(zt))) {
+          let f = raw as z.ZodTypeAny;
+          while (zodKind(f) === "optional" || zodKind(f) === "default") f = zodDef(f).innerType!;
+          walk(f, path === "" ? name : `${path}.${name}`);
+        }
+        return;
+      }
+      case "optional":
+      case "default":
+      case "nullable":
+        walk(zodDef(zt).innerType!, path);
+        return;
+      case "record":
+        if (zodDef(zt).valueType) walk(zodDef(zt).valueType!, `${path}.*`);
+        return;
+      case "union":
+        for (const o of zodDef(zt).options ?? []) walk(o, path);
+        return;
+      default:
+        return;
+    }
+  };
+  walk(schema, pathPrefix);
+  return out;
+}
+
 // ── caller-side clock sugar (the `…At` payload convention) ────────────────────────
 
 /**
@@ -325,15 +428,19 @@ export function autoStampFields(schema: z.ZodTypeAny): string[] {
   return out;
 }
 
-/** The payload type text, with auto-stamped / front-door-minted / auto-placed fields optional (`?`). */
+/** The payload type text, with auto-stamped / front-door-minted / auto-placed fields optional (`?`).
+ *  `reg` collects any RECURSIVE `z.lazy` named types minted while walking (emitted once by the
+ *  caller); `pathPrefix` (the directive id) scopes their names so two directives can't collide. */
 function tsTypeOfPayload(
   schema: z.ZodTypeAny,
   autoStamped: readonly string[],
   minted: readonly string[] = [],
   autoPlaced: readonly string[] = [],
+  reg?: LazyTypeRegistry,
+  pathPrefix = "",
 ): string {
   if (zodKind(schema) !== "object" || (autoStamped.length === 0 && minted.length === 0 && autoPlaced.length === 0)) {
-    return tsTypeOfZod(schema, "");
+    return tsTypeOfZod(schema, "", reg, pathPrefix);
   }
   const stamped = new Set(autoStamped);
   const mintedSet = new Set(minted);
@@ -352,7 +459,8 @@ function tsTypeOfPayload(
         : placedSet.has(name)
           ? " // picked LEAST-LOADED over the coordinator's law-state at offer when omitted (sharding §3)"
           : "";
-    return `  ${name}${optional ? "?" : ""}: ${tsTypeOfZod(f, "  ")};${note}`;
+    const fieldPath = pathPrefix === "" ? name : `${pathPrefix}.${name}`;
+    return `  ${name}${optional ? "?" : ""}: ${tsTypeOfZod(f, "  ", reg, fieldPath)};${note}`;
   });
   return fields.length ? `{\n${fields.join("\n")}\n}` : "Record<string, never>";
 }
@@ -564,6 +672,10 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   const encPresent = encMap !== null;
   const encConst = encryptionConstName(opts.packageName);
   const out: string[] = [];
+  // The PACKAGE-LEVEL recursive-type registry: every directive payload's `z.lazy` knots mint
+  // named recursive type aliases into it (deduped by lazy identity across directives); the decls
+  // are emitted once, after the payload types (TS hoists type aliases, so order is free).
+  const lazyReg = newLazyRegistry();
   out.push(
     `// AUTO-GENERATED by nomos-compile — typed TS client for package "${opts.packageName}".`,
     `// Regenerated on every compile; do not edit. Zero imports: bind it to any holon`,
@@ -600,6 +712,11 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `/** One projection row: the aggregate's wire type, its id, and the folded fields. */`,
     `export interface Row<T> { type: string; id: string; data: T }`,
     ``,
+    `/** Arbitrary JSON — the type a RECURSIVE \`z.lazy\` payload subtree degrades to (a self-`,
+    ` *  referencing tree/JSON schema can't be a finite named literal, so the engine validates it`,
+    ` *  at runtime and the recursive edge is typed here). Named recursion TS resolves fine. */`,
+    `export type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };`,
+    ``,
     `/** The holon surface this client binds to (structurally satisfied by @githolon/client). */`,
     `export interface NomosHolon {`,
     `  /** THE ONE ENCODER offer (the single v2-envelope codec lives in @githolon/client \`encodeIntentOfferBytes\`):`,
@@ -1280,7 +1397,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       const pv = wantSeal ? "_sealed" : "payload";
       out.push(
         `/** \`${domain}/${d.id}\` payload (mirrors the engine's zod schema).${stamps.length ? ` Omitted ${stamps.map((s) => `\`${s}\``).join("/")} auto-stamp(s) ISO now() at offer.` : ""}${mint ? ` Omitted \`${mint.field}\` is KERNEL-MINTED at offer (returned on the result).` : ""}${placed.length ? " Omitted `shard` is picked LEAST-LOADED at offer (the routed holon)." : ""} */`,
-        `export type ${payloadName} = ${tsTypeOfPayload(schema, stamps, mint ? [mint.field] : [], placed)};`,
+        `export type ${payloadName} = ${tsTypeOfPayload(schema, stamps, mint ? [mint.field] : [], placed, lazyReg, d.id)};`,
         ``,
       );
       if (mint !== undefined) {
@@ -1467,5 +1584,15 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     );
   }
 
+  // RECURSIVE PAYLOAD TYPES (`z.lazy`): emit each minted named alias once. Sorted by name for
+  // byte-determinism; TS hoists type aliases so referencing them above is fine.
+  if (lazyReg.decls.size > 0) {
+    out.push(
+      `// ── recursive payload types (z.lazy) — named so a self-referencing schema is a real TS type ──`,
+    );
+    for (const name of [...lazyReg.decls.keys()].sort()) out.push(lazyReg.decls.get(name)!);
+    out.push(``);
+  }
+
   return out.join("\n");
 }

package/src/compile_package_main.ts

@@ -117,7 +117,7 @@ import {
 } from "./stable_ids.js";
 import { emitUsd, type UsdLayer } from "./usd.js";
 import { emitLayeredRelationUsda, type RelationLayerInput } from "./relation_composition.js";
-import { generateTsClient, tsClientFactoryName } from "./codegen_ts.js";
+import { generateTsClient, tsClientFactoryName, recursiveLazyTypes } from "./codegen_ts.js";
 import { generateOpenApiFragment, mergeOpenApiFragments } from "./codegen_openapi.js";
 import { domainInterface, type DomainInterface } from "./shape_compat.js";
 import { generateTsProof, proofLegsIndex } from "./codegen_proof.js";
@@ -1235,6 +1235,20 @@ async function main(): Promise<void> {
     "utf8",
   );
 
+  // ── RECURSIVE-PAYLOAD NOTES (z.lazy) — a self-referencing tree/JSON payload field is FULLY
+  // supported: each codegen layer mints a named recursive type for it (TS `type <Name>`, Dart
+  // recursive class). Surfaced here so the tenant sees which fields became which named types.
+  const recursiveNotes: string[] = [];
+  for (const mod of domainModules) {
+    for (const d of (mod.directives ?? []) as Array<{ id?: unknown; payloadSchema?: unknown }>) {
+      if (!d || typeof d.id !== "string" || !d.payloadSchema || typeof d.payloadSchema !== "object") continue;
+      for (const { path, name } of recursiveLazyTypes(d.payloadSchema as Parameters<typeof recursiveLazyTypes>[0], d.id)) {
+        const field = path.startsWith(`${d.id}.`) ? path.slice(d.id.length + 1) : path;
+        recursiveNotes.push(`${mod.domain ?? mod.name}.${d.id} payload '${field}': recursive z.lazy schema → generated named type '${name}' (TS type + Dart class)`);
+      }
+    }
+  }
+
   // ── reports ──
   const entryReports: string[] = [];
   for (const [reportId, ref] of Object.entries(cfg.reports ?? {})) {
@@ -1815,6 +1829,7 @@ async function main(): Promise<void> {
     }
   }
   console.log(`  client     ${rel(clientPath)} (typed TS client — payloads, read models, query accessors)`);
+  for (const note of recursiveNotes) console.log(`  note       ${note}`);
   console.log(`  openapi    ${rel(openapiPath)} (${Object.keys(openapi.paths).length} operation(s) — the law's self-describing API; the host's runtime routing table)`);
   if (proofPath !== undefined) {
     console.log(`  proof      ${rel(proofPath)} (a runnable e2e GENERATED from your law — run: githolon proof)`);

package/src/zod_lazy.ts

@@ -0,0 +1,45 @@
+/**
+ * Dependency-free helpers for RECURSIVE `z.lazy` payload schemas, shared by BOTH codegen walkers
+ * (codegen_ts + codegen_dart) WITHOUT coupling them. Keeping these here (rather than in codegen_ts)
+ * avoids a codegen_ts↔codegen_dart import cycle that would otherwise drag codegen_ts's heavy
+ * transitive deps (workspace_routing → node:crypto) into the tenant ENGINE bundle (esbuild
+ * neutral-platform, no node builtins). This module imports NOTHING but zod's type.
+ */
+import type { z } from "zod";
+
+function lazyDef(zt: z.ZodTypeAny): { type?: unknown; getter?: () => z.ZodTypeAny } {
+  const raw = zt as unknown as { _def?: { type?: unknown; getter?: () => z.ZodTypeAny }; def?: { type?: unknown; getter?: () => z.ZodTypeAny } };
+  return raw._def ?? raw.def ?? {};
+}
+
+/**
+ * Resolve a `z.lazy(() => …)` ONE level to its inner schema (zod v4 exposes the deferred getter on
+ * `_def.getter`). A non-lazy schema is returned unchanged. Recursive `z.lazy` schemas (a `TreeNode`
+ * that references itself) are common for tree/JSON payloads; every schema WALKER unwraps here and
+ * carries a VISITED / registry keyed on the lazy object's IDENTITY so a self-reference is a
+ * detectable knot, never an infinite descent.
+ */
+export function zodUnwrapLazy(zt: z.ZodTypeAny): z.ZodTypeAny {
+  const def = lazyDef(zt);
+  if (def.type === "lazy" && typeof def.getter === "function") return def.getter();
+  return zt;
+}
+
+const capFirst = (s: string): string => (s.length === 0 ? s : s[0]!.toUpperCase() + s.slice(1));
+const camelize = (s: string): string => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
+
+/**
+ * A PascalCase type name from a payload path (`saveTree.root` → `SaveTreeRoot`), array markers
+ * dropped. The SAME base the TS and Dart recursive-type synthesizers use so a recursive type's
+ * TS alias and Dart class agree in the common case.
+ */
+export function recursiveTypeBaseName(path: string): string {
+  return (
+    path
+      .replace(/\[\]/g, "")
+      .split(/[.]/)
+      .filter(Boolean)
+      .map((s) => capFirst(camelize(s)))
+      .join("") || "Recursive"
+  );
+}