@githolon/dsl 0.54.1 → 0.55.0

package/src/codegen_dart.ts

@@ -30,10 +30,12 @@
  */
 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";
 import type { Field, FieldKind, ValueObjectDescriptor, ValueObjectFieldDescriptor } from "./fields.js";
+import { admitsNull, nullMetaOf, nullDocLine } from "./null_meta.js";
 import type { Directive } from "./directive.js";
 import { executeDirectiveToIntent } from "./wire_encode.js";
 import { deterministicPorts } from "./ctx.js";
@@ -80,6 +82,13 @@ export interface PayloadFieldSpec {
    * only emits ops for present fields). Required fields are always emitted.
    */
   optional: boolean;
+  /**
+   * NULL SEMANTICS (null_semantics.md): the payload field ADMITS a domain `null` (its zod is
+   * `.nullable()`, a `t.nullable(...)`/`t.clearable(...)` sink). It generates as the sealed
+   * tri-state [NomosSlot] so the call site says OMITTED / EXPLICIT-NULL / PRESENT explicitly —
+   * `toPayloadJson` then omits, writes a real `null`, or writes the value accordingly.
+   * `false`/absent for a plain field (byte-identical to a pre-feature payload). */
+  nullAdmits?: boolean;
 }
 
 type ZodInternalDef = {
@@ -93,8 +102,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 +234,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");
@@ -222,11 +247,19 @@ export function introspectPayload(
     // when null — mirroring the engine's Zod, which only sees present fields).
     let zt = ztRaw as z.ZodTypeAny;
     let optional = false;
-    while (isOptionalOrDefault(zt)) {
-      optional = true;
+    let nullAdmits = false;
+    // Unwrap optional/default (omission) AND nullable (a domain `null`) in ANY order — a payload
+    // field may be `.nullable()`, `.optional()`, or both. A nullable field carries the tri-state slot.
+    while (isOptionalOrDefault(zt) || zodTypeName(zt) === "ZodNullable") {
+      if (zodTypeName(zt) === "ZodNullable") nullAdmits = true;
+      else optional = true;
       zt = zodInnerType(zt);
     }
-    out.push({ ...introspectField(name, zt, enumDartTypes), optional });
+    out.push({
+      ...introspectField(name, zt, enumDartTypes, lazyNames),
+      optional,
+      ...(nullAdmits ? { nullAdmits: true } : {}),
+    });
   }
   return out;
 }
@@ -239,7 +272,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 +350,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" };
@@ -412,6 +469,15 @@ interface AggFieldSpec {
    * only the generated read-model type. `undefined` for a non-json field.
    */
   jsonShape?: "object";
+  /**
+   * NULL SEMANTICS (null_semantics.md): the field ADMITS a domain `null` (declared
+   * `t.nullable(...)` / `t.clearable(...)`), so its read-model + payload surface is the
+   * sealed tri-state [NomosSlot] (Omitted / ExplicitNull / Present) instead of a plain
+   * `T?` — so the app edge can't collapse omission and explicit-null. `false`/absent for a
+   * `forbid` field (byte-identical to a pre-feature field). */
+  nullAdmits?: boolean;
+  /** The law-documentation `reason` for a null-admitting field (surfaces in the Dart doc comment). */
+  nullReason?: string;
 }
 
 export interface DartImport {
@@ -764,11 +830,16 @@ function aggregateFieldSpecs(
       // BIRTH-PRESENCE LAW (`.fromBirth()`): the gate refuses any event that leaves the field
       // absent, so the read model may type it NON-NULLABLE — the one lawful exception to the
       // partial-fold nullability doctrine (absence is unrepresentable by law, not convention).
-      const spec: AggFieldSpec = isCollectionKind(base.kind)
+      const baseSpec: AggFieldSpec = isCollectionKind(base.kind)
         ? base
         : f.isFromBirth === true
           ? { ...base, optional: false }
           : { ...base, optional: true };
+      // NULL SEMANTICS (null_semantics.md): a null-admitting scalar carries the tri-state slot.
+      const nmeta = nullMetaOf(f);
+      const spec: AggFieldSpec = admitsNull(f)
+        ? { ...baseSpec, nullAdmits: true, ...(nmeta.nullReason !== undefined ? { nullReason: nmeta.nullReason } : {}) }
+        : baseSpec;
       if (used.has(spec.name)) {
         throw new Error(
           `aggregate '${agg.id}' field '${spec.wireName}' maps to duplicate Dart field '${spec.name}'`,
@@ -1093,19 +1164,27 @@ function emitAggregate(
     `  /// indexed/by-id accessor matched on (e.g. the siteId). Empty string only when`,
     `  /// the aggregate is built from a bare \`data\` map with no row id (e.g. a unit test).`,
     `  final ${idType} aggregateId;`,
-    ...specs.map(
-      (s) => `  final ${s.dartType}${s.optional ? "?" : ""} ${s.name};`,
-    ),
+    ...specs.flatMap((s) => {
+      const doc = s.nullReason !== undefined ? [`  /// null semantic: ${s.nullReason}`] : [];
+      // NULL SEMANTICS: a null-admitting field is the sealed tri-state slot (Omitted / ExplicitNull /
+      // Present) — omission and explicit-null never collapse. Others keep the plain `T?`.
+      return s.nullAdmits === true
+        ? [...doc, `  final NomosSlot<${stripNullable(s.dartType)}> ${s.name};`]
+        : [`  final ${s.dartType}${s.optional ? "?" : ""} ${s.name};`];
+    }),
   ].join("\n");
   const ctorParams = [
     `    this.aggregateId = const ${idType}.fromRow(''),`,
     ...specs.map(
       // A required scalar stays `required`; an optional scalar OR a collection is not
       // `required` (an absent optional scalar is null; an absent collection is empty).
+      // A null-admitting slot defaults to Omitted.
       (s) =>
-        s.optional || isCollectionKind(s.kind)
-          ? `    ${collectionDefaultParam(s)}`
-          : `    required this.${s.name},`,
+        s.nullAdmits === true
+          ? `    this.${s.name} = const NomosSlot.omitted(),`
+          : s.optional || isCollectionKind(s.kind)
+            ? `    ${collectionDefaultParam(s)}`
+            : `    required this.${s.name},`,
     ),
   ].join("\n");
 
@@ -1117,7 +1196,11 @@ function emitAggregate(
   // threaded from the row id (GAP 2) — defaulting to '' for a bare-map call.
   const parseLines = [
     `      aggregateId: ${aggregateIdFromRowExpr(agg.id, "id")},`,
-    ...specs.map((s) => `      ${s.name}: ${parseField(s, className)},`),
+    ...specs.map((s) =>
+      s.nullAdmits === true
+        ? `      ${s.name}: NomosSlot.decode<${stripNullable(s.dartType)}>(data, '${s.wireName}', ${slotDecodeCallback(s, "aggregate")}),`
+        : `      ${s.name}: ${parseField(s, className)},`,
+    ),
   ].join("\n");
 
   // `==`/`hashCode` include the id (two rows with the same data but different ids are
@@ -1912,6 +1995,53 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
   }
 }
 
+/**
+ * The `(v) => …` DECODE CALLBACK for a null-admitting field's [NomosSlot] (null_semantics.md).
+ * [NomosSlot.decode] pre-handles the OMITTED (key absent) + EXPLICIT-NULL (value `null`) cases,
+ * so this callback ONLY sees a real PRESENT value `v` (never null) and turns it into the typed
+ * Dart value — mirroring [parseField]'s present-branch per kind, but over a raw leaf `v`. */
+function slotDecodeCallback(s: AggFieldSpec, mode: "aggregate" | "readModel"): string {
+  switch (s.kind) {
+    case "ref":
+      return s.refIdClass !== undefined
+        ? `(v) => ${s.refIdClass}.fromRow(v as String)`
+        : `(v) => v as String`;
+    case "position":
+    case "string":
+      return s.valueClass !== undefined
+        ? `(v) => ${s.valueClass}.fromRow(v as String)`
+        : `(v) => v as String`;
+    case "json":
+      if (s.voClass !== undefined) {
+        return `(v) => ${s.voClass}.fromProjected((v as Map).cast<String, Object?>())`;
+      }
+      // The AGGREGATE class types every `json` leaf as `String` (re-stringify a parsed container via
+      // `jsonEncode`); the READ MODEL types a `t.jsonObject()` leaf as `Map<String, Object?>` (strict
+      // object) and a plain `t.json()` leaf as the permissive `Object?` (kept as-is).
+      if (mode === "aggregate") return `(v) => v is String ? v : jsonEncode(v)`;
+      return s.jsonShape === "object" ? `(v) => (v as Map).cast<String, Object?>()` : `(v) => v`;
+    case "bool":
+      return `(v) => v as bool`;
+    case "counter":
+    case "int":
+      return `(v) => (v as num).toInt()`;
+    case "enum":
+      return `(v) => ${s.dartType}.fromWire(v as String)`;
+    case "evidence":
+      return `(v) => EvidenceRef.fromProjected((v as Map).cast<String, Object?>())`;
+    // Collections never admit null (the law bans nullable on a set/map) — unreachable.
+    case "set":
+    case "map":
+      return `(v) => v`;
+  }
+}
+
+/** Strip a trailing `?` so a nullable-typed base (`Object?`) becomes the slot's inner
+ *  non-null type (`NomosSlot<Object>` — the slot owns nullability via ExplicitNull). */
+function stripNullable(t: string): string {
+  return t.endsWith("?") ? t.slice(0, -1) : t;
+}
+
 // ---- generated read model class --------------------------------------------
 //
 // A typed read model class generated from aggregate DSL field declarations. It
@@ -2104,9 +2234,12 @@ function emitReadModel(
     `  /// The kernel aggregate id (the \`{type,id,data}\` row's \`id\`, e.g. the siteId).`,
     `  /// Empty string only when built from a bare \`data\` map with no row id (a unit test).`,
     `  final ${idType} aggregateId;`,
-    ...specs.map(
-      (s) => `  final ${readModelDartType(s)}${readModelNullableSuffix(s)} ${s.name};`,
-    ),
+    ...specs.flatMap((s) => {
+      const doc = s.nullReason !== undefined ? [`  /// null semantic: ${s.nullReason}`] : [];
+      return s.nullAdmits === true
+        ? [...doc, `  final NomosSlot<${stripNullable(readModelDartType(s))}> ${s.name};`]
+        : [`  final ${readModelDartType(s)}${readModelNullableSuffix(s)} ${s.name};`];
+    }),
     ...deriveds.map(
       (d) =>
         `  /// Engine-projected DERIVED read field (pure fn of the folded fields; NOT kernel state).\n  final ${projectionReturnDartType(d.returns)} ${d.id};`,
@@ -2121,9 +2254,12 @@ function emitReadModel(
     ...specs.map((s) =>
       // A required field is `required`; an optional scalar, a collection, OR a
       // permissive json leaf (already nullable `Object?`) takes its default/null.
-      s.optional || isCollectionKind(s.kind) || isPermissiveJsonLeaf(s)
-        ? `    ${readModelDefaultParam(s)}`
-        : `    required this.${s.name},`,
+      // A null-admitting slot defaults to Omitted.
+      s.nullAdmits === true
+        ? `    this.${s.name} = const NomosSlot.omitted(),`
+        : s.optional || isCollectionKind(s.kind) || isPermissiveJsonLeaf(s)
+          ? `    ${readModelDefaultParam(s)}`
+          : `    required this.${s.name},`,
     ),
     // Derived/combined fields are always nullable (null until the engine pass runs).
     ...deriveds.map((d) => `    this.${d.id},`),
@@ -2132,7 +2268,11 @@ function emitReadModel(
 
   const parseLines = [
     `      aggregateId: ${aggregateIdFromRowExpr(agg.id, "id")},`,
-    ...specs.map((s) => `      ${s.name}: ${parseReadModelField(s, wireType)},`),
+    ...specs.map((s) =>
+      s.nullAdmits === true
+        ? `      ${s.name}: NomosSlot.decode<${stripNullable(readModelDartType(s))}>(data, '${s.wireName}', ${slotDecodeCallback(s, "readModel")}),`
+        : `      ${s.name}: ${parseReadModelField(s, wireType)},`,
+    ),
     // Derived/combined fields decode from the engine-produced bare JSON leaf.
     ...deriveds.map((d) => `      ${d.id}: ${parseProjectionReturnField(d.id, d.returns)},`),
     ...combineds.map((c) => `      ${c.id}: ${parseProjectionReturnField(c.id, c.returns)},`),
@@ -2176,17 +2316,28 @@ 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.
   const fieldDecls = specs
-    .map((s) => `  final ${s.dartType}${s.optional ? "?" : ""} ${s.name};`)
+    .map((s) =>
+      s.nullAdmits === true
+        ? `  final NomosSlot<${stripNullable(s.dartType)}> ${s.name};`
+        : `  final ${s.dartType}${s.optional ? "?" : ""} ${s.name};`,
+    )
     .join("\n");
   const ctorParams = specs
-    .map((s) => `    ${s.optional ? "" : "required "}this.${s.name},`)
+    .map((s) =>
+      // A null-admitting slot defaults to Omitted (the call site chooses Present/ExplicitNull);
+      // an optional field defaults to null; a required field is `required`.
+      s.nullAdmits === true
+        ? `    this.${s.name} = const NomosSlot.omitted(),`
+        : `    ${s.optional ? "" : "required "}this.${s.name},`,
+    )
     .join("\n");
   // Zero-field payload (e.g. a `.births()` sanctioning directive with an empty
   // object schema): `const X({});` / a dangling blank field block is INVALID Dart —
@@ -2201,14 +2352,21 @@ function emitDirective(
   // fields are written only when present (mirrors the engine's Zod: ops are emitted
   // only for present fields).
   const requiredEntries = specs
-    .filter((s) => !s.optional)
+    .filter((s) => !s.optional && s.nullAdmits !== true)
     .map((s) => `    '${s.name}': ${toJsonExpr(s, s.name)},`);
   const optionalLines = specs
-    .filter((s) => s.optional)
+    .filter((s) => s.optional && s.nullAdmits !== true)
     .map(
       (s) =>
         `    if (${s.name} != null) '${s.name}': ${toJsonExpr(s, `${s.name}!`)},`,
     );
+  // NULL SEMANTICS: a null-admitting field writes through its slot — Omitted writes nothing,
+  // ExplicitNull writes a real `null`, Present writes the encoded value (null_semantics.md).
+  const slotSpecs = specs.filter((s) => s.nullAdmits === true);
+  const slotWriteLines = slotSpecs.map(
+    (s) => `    ${s.name}.writeTo(data, '${s.name}', (v) => ${toJsonExpr(s, "v")});`,
+  );
+  const hasSlots = slotSpecs.length > 0;
 
   const docFirst = directiveDoc(d);
 
@@ -2242,12 +2400,25 @@ function emitDirective(
     ``,
     `  /// Serialise this payload to the intent DATA JSON (the shape the`,
     `  /// domain Zod schema validates inside the engine). Optional fields are`,
-    `  /// omitted when null.`,
+    `  /// omitted when null; a null-admitting field writes through its tri-state slot.`,
     `  @override`,
-    `  Map<String, Object?> toPayloadJson() => <String, Object?>{`,
-    ...requiredEntries,
-    ...optionalLines,
-    `  };`,
+    ...(hasSlots
+      ? [
+          `  Map<String, Object?> toPayloadJson() {`,
+          `    final data = <String, Object?>{`,
+          ...requiredEntries,
+          ...optionalLines,
+          `    };`,
+          ...slotWriteLines,
+          `    return data;`,
+          `  }`,
+        ]
+      : [
+          `  Map<String, Object?> toPayloadJson() => <String, Object?>{`,
+          ...requiredEntries,
+          ...optionalLines,
+          `  };`,
+        ]),
     `}`,
   ].join("\n");
 }
@@ -2270,6 +2441,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 +3638,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 —
@@ -3389,6 +3720,13 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   ].join("\n\n");
   // The symbols whose Dart surface this file EMITS (framework-shared ones live in the shared file).
   const localAggregates = mod.aggregates.filter((a) => !skipAggregateIds.has(a.id));
+  // A nullable plain-`t.json()` read-model field's slot decode re-stringifies a parsed container via
+  // `jsonEncode` — the ONE case the generated file needs `dart:convert` (null_semantics.md).
+  const needsJsonConvert = localAggregates.some((a) =>
+    Object.values(a.fields as Record<string, Field>).some(
+      (f) => admitsNull(f) && f.kind === "json" && f.valueObject === undefined,
+    ),
+  );
   const localDirectives = mod.directives.filter((d) => !skipDirectiveIds.has(d.id));
   const localQueries = (mod.queries ?? []).filter((q) => !skipQueryIds.has(q.id));
   // Enums are collected from the LOCALLY-emitted symbols only — a framework directive/aggregate's
@@ -3421,7 +3759,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
@@ -3596,6 +3934,8 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
     `// ignore_for_file: unnecessary_this, prefer_const_constructors, constant_identifier_names`,
     `// ignore_for_file: unused_import`,
     ``,
+    // A nullable plain-`t.json()` read-model slot decode re-stringifies via `jsonEncode`.
+    ...(needsJsonConvert ? [`import 'dart:convert';`] : []),
     // The generated tenant domains live in the `co2_nomos_domains` package and depend
     // on the framework `nomos_client` package by its PUBLIC package: URI — NOT a relative
     // `../wire.dart` path into the framework (which broke when the generated dir moved

package/src/codegen_openapi.ts

@@ -38,6 +38,8 @@ import { hasManyIndexes } from "./query.js";
 import { finishCount } from "./count.js";
 import { finishSum } from "./sum.js";
 import { finishExtremum } from "./extremum.js";
+import { nullDocLine } from "./null_meta.js";
+import type { Field } from "./fields.js";
 
 type AnyDirective = Directive<unknown>;
 
@@ -56,13 +58,30 @@ export interface OpenApiFragmentOptions {
 }
 
 /** Lower a directive's payload zod to JSON Schema; a non-representable schema falls back to a
- *  permissive object rather than failing the whole compile (the engine still validates the real zod). */
-function payloadJsonSchema(d: AnyDirective): unknown {
+ *  permissive object rather than failing the whole compile (the engine still validates the real zod).
+ *  NULL SEMANTICS (null_semantics.md): a payload property that maps by name to a null-admitting field
+ *  on the directive's target aggregate carries that field's documented `reason` as its `description`,
+ *  so every consumer of the spec knows what a `null` MEANS here. */
+function payloadJsonSchema(d: AnyDirective, module: DomainModule): unknown {
+  let schema: unknown;
   try {
-    return z.toJSONSchema((d as { payloadSchema: z.ZodTypeAny }).payloadSchema, { io: "input" });
+    schema = z.toJSONSchema((d as { payloadSchema: z.ZodTypeAny }).payloadSchema, { io: "input" });
   } catch {
     return { type: "object", additionalProperties: true };
   }
+  const aggId = (d as { aggregateId?: string }).aggregateId;
+  const agg = aggId !== undefined ? module.aggregates.find((a) => a.id === aggId) : undefined;
+  const props = (schema as { properties?: Record<string, Record<string, unknown>> })?.properties;
+  if (agg !== undefined && props !== undefined && typeof props === "object") {
+    for (const [name, prop] of Object.entries(props)) {
+      const field = (agg.fields as Record<string, Field> | undefined)?.[name];
+      const doc = field !== undefined ? nullDocLine(field) : undefined;
+      if (doc !== undefined && prop !== null && typeof prop === "object") {
+        prop.description = prop.description !== undefined ? `${String(prop.description)} — ${doc}` : doc;
+      }
+    }
+  }
+  return schema;
 }
 
 /** The domain key the engine resolves intents against (the `author` registry key). */
@@ -111,7 +130,7 @@ export function generateOpenApiFragment(
       },
       requestBody: {
         required: true,
-        content: { "application/json": { schema: payloadJsonSchema(dir) } },
+        content: { "application/json": { schema: payloadJsonSchema(dir, module) } },
       },
       responses: {
         "200": { description: "admitted — the sealed intent head" },