@githolon/dsl 0.54.1 → 0.55.0

package/src/codegen_proof.ts

@@ -60,8 +60,33 @@ 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();
+
+/**
+ * The top-level payload fields that ADMIT a domain `null` (their zod is `.nullable()`, a
+ * `t.nullable(...)`/`t.clearable(...)` sink — null_semantics.md). The proof drives the NULL ARM for
+ * each (the value arm is the normal synthesized sample) so the law is provably total over `null`.
+ * A nullable wrapped in optional/default still counts (unwrapped in ANY order). Empty for a
+ * null-free payload — no extra leg, byte-identical proof. */
+export function nullablePayloadFields(schema: z.ZodTypeAny): string[] {
+  if (zodKind(schema) !== "object") return [];
+  const out: string[] = [];
+  for (const [name, raw] of Object.entries(zodObjectShape(schema))) {
+    let f = raw as z.ZodTypeAny;
+    let admits = false;
+    while (zodKind(f) === "optional" || zodKind(f) === "default" || zodKind(f) === "nullable") {
+      if (zodKind(f) === "nullable") admits = true;
+      f = zodDef(f).innerType!;
+    }
+    if (admits) out.push(name);
+  }
+  return out;
+}
+
 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 +149,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 +218,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 +237,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:
@@ -2592,6 +2641,25 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     );
   }
 
+  // NULL SEMANTICS BOTH-ARM PROOF (null_semantics.md): the primary dispatch above already proved the
+  // VALUE arm (a nullable field synthesizes to a sampled value); here we prove the NULL arm — the law
+  // ADMITS an explicit `null` for each nullable field, so it is provably total over null. Each create
+  // arm mints a fresh id. Empty for a null-free payload (byte-identical proof).
+  const nullArms = nullablePayloadFields(createDir.payloadSchema as z.ZodTypeAny);
+  for (const field of nullArms) {
+    const armMint = mintField !== undefined ? `, ${JSON.stringify(mintField)}: await holon.mint(${JSON.stringify(agg.id)})` : "";
+    out.push(
+      `// ${n()}. NULL-ARM PROOF — \`${field}\` is nullable: the law must ADMIT an explicit null (both arms proven).`,
+      `try {`,
+      `  await app.${createDir.id}({ ...${JSON.stringify(baseValue)}${armMint}, ${JSON.stringify(field)}: null });`,
+      `  ok(${JSON.stringify(`null-arm — ${domain}/${createDir.id} admitted with \`${field}\`=null (the law handles the explicit-null arm)`)});`,
+      `} catch (e) {`,
+      `  fail(\`null-arm ${field}=null was REFUSED — a nullable field's null arm must be admitted: \${(e as Error).message}\`);`,
+      `}`,
+      ``,
+    );
+  }
+
   out.push(
     `globalThis.fetch = realFetch;`,
     `ok("offline proof ENFORCED — fetch was trapped: local write/read touched no network");`,

package/src/codegen_ts.ts

@@ -43,12 +43,14 @@ 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";
 import type { CombinedDecl } from "./combined.js";
 import { resolveWorkspaceTypes, type ResolvedWorkspaceType, type WorkspaceTypeDecl } from "./workspace_type.js";
 import { deriveClientMintPlan, type ClientMintPlanEntry } from "./workspace_routing.js";
+import { admitsNull, nullDocLine } from "./null_meta.js";
 
 const cap = (s: string) => (s.length ? s[0]!.toUpperCase() + s.slice(1) : s);
 const camel = (s: string) => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
@@ -206,8 +208,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 +252,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 +299,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 +323,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 +334,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 +357,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 +429,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 +460,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>";
 }
@@ -360,6 +469,14 @@ function tsTypeOfPayload(
 // ── DSL Field → read-model TS type (the projection's decode surface) ──────────────
 
 function tsTypeOfField(field: Field): string {
+  const base = tsBaseTypeOfField(field);
+  // NULL SEMANTICS (null_semantics.md): a `nullable`/`explicit-empty` field ADMITS a domain `null`,
+  // so its read-model type carries the `| null` arm (distinct from the `?` partial-fold absence a
+  // non-null-admitting field gets). A `forbid` json/VO field NEVER gets the null arm.
+  return admitsNull(field) ? `${base} | null` : base;
+}
+
+function tsBaseTypeOfField(field: Field): string {
   switch (field.kind) {
     case "string":
       return "string";
@@ -564,6 +681,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 +721,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\`):`,
@@ -1023,6 +1149,8 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     out.push(`export interface ${typeId}Data {`);
     for (const [name, field] of Object.entries(agg.fields)) {
       const required = (field as Field).isFromBirth === true;
+      const doc = nullDocLine(field);
+      if (doc !== undefined) out.push(`  /** ${doc} */`);
       out.push(`  ${name}${required ? "" : "?"}: ${tsTypeOfField(field as Field)};`);
     }
     for (const extra of extrasByType.get(typeId) ?? []) out.push(extra);
@@ -1280,7 +1408,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 +1595,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";
@@ -379,6 +379,10 @@ const DART_SUPPORT_SRC = [
   "offer.dart",
   "subscriptions.dart",
   "provider.dart",
+  // The tri-state slot (NomosSlot<T>) for `nullable`/`clearable` fields (null_semantics.md) — the
+  // barrel re-exports it and generated read-model/payload classes reference it, so it must vendor.
+  // Zero external pub deps (pure Dart).
+  "null_slot.dart",
   // Runtime aggregate-meta support types (NomosAggregateMeta/NomosFieldMeta) — the generated
   // per-domain registry consts reference them through the barrel.
   "aggregate_meta.dart",
@@ -1235,6 +1239,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 +1833,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)`);