@githolon/dsl 0.108.0 → 0.108.2

package/src/codegen_dart.ts

@@ -7,7 +7,7 @@
 
 /**
  * Dart frontend codegen (DSL decision-6: the schema is the single source of
- * truth -> TS (done), proto (later), and Dart frontend types (here)).
+ * truth -> TypeScript, Protobuf host contracts, and Dart frontend types (here)).
  *
  * Emits, per domain:
  *   - a Dart class per aggregate with its typed fields, parsed (`fromJson`) from
@@ -17,12 +17,10 @@
  *     `watch…`/one-shot `read…` over the GitHolon `query()`/`query_by_id()`
  *     surface (the read half of the offer/query boundary);
  *   - a Dart enum per `t.enum([...])` field;
- *   - a Dart intent class per domain action — a pure typed DTO. Each class exposes its
- *     `domain` / `intentType` (so the call site never hand-types a string) and a
- *     internal `nmsInternalToPayloadJson()` seam that serialises only its typed fields to data. It builds no
- *     `Event` and no `Hlc`: the GitHolon executes the installed domain plan.
- *   - a single generic effectful write verb [`offer`] that ships {domain, intentType,
- *     nmsInternalToPayloadJson()} to the GitHolon `author(domain, intentType, payloadJson, actor)`.
+ *   - a Dart input class per domain action — a pure typed DTO. It builds no `Event`,
+ *     `Hlc`, generic map, or JSON representation: the companion generated client lowers
+ *     its fields directly into the canonical typed USDA call.
+ *   - one effectful write verb [`offer`] carrying those USDA bytes to the GitHolon.
  *
  * It does NOT hand-write the fixed wire types (`Value`/`Op`/`Event`/...): those
  * live hand-written in `dart_types/lib/src/wire.dart`. Only the per-domain shapes are
@@ -30,7 +28,7 @@
  */
 import { z } from "zod";
 import { enumTypeNameOf } from "./enum_type.js";
-import { voMetaOf, collectPayloadValueObjectDescriptors, idOfMetaOf, idOfTargetKindOf, refOfMetaOf, versionedRefOfMetaOf, brandedIdMetaOf, NOMOS_UNIT_BRAND } from "./value_object.js";
+import { voMetaOf, collectPayloadValueObjectDescriptors, collectValueObjectDescriptors, idOfMetaOf, idOfTargetKindOf, refOfMetaOf, versionedRefOfMetaOf, 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";
@@ -78,14 +76,18 @@ export function dartActionInputClassName(directive: AnyDirective): string {
 
 // ---- Zod payload introspection --------------------------------------------
 
-/** How a typed payload field serialises into the payload-as-DATA JSON the engine reads. */
-export type ToJsonWrap =
+/** The concrete Dart representation of a typed payload field. */
+export type DartPayloadShape =
   | "scalar" // String/int/bool — emit the field directly.
   | "enum" // generated enum — emit `.wire`.
   | "strList" // List<String> — emit directly.
-  | "json" // nested object — emit the field's `Map<String, Object?>` directly.
-  | "vo" // a declared value object — emit `.toJson()` (the generated VO class).
-  | "voList" // a list of value objects — emit `.map((e) => e.toJson()).toList()`.
+  | "wrappedList" // List of nominal scalar wrappers — each element emits `.value`.
+  | "refList" // List<NomosRef<T>> — each element emits its canonical id.
+  | "record" // anonymous z.object — a structural Dart named record.
+  | "recordList" // list of anonymous z.object values — typed Dart records.
+  | "stringMap" // a declared z.record(z.string()) — Map<String, String>, encoded field-by-field.
+  | "vo" // a declared typed value object.
+  | "voList" // a list of declared typed value objects.
   | "wrapped" // a standalone branded-id or unit extension type — emit `.value`.
   | "ref" // an aggregate-specific NomosRef<T> — emit its `.id` wire scalar.
   | "addressRef" // a workspace-qualified NomosRef<T> — preserve its complete typed address.
@@ -107,22 +109,21 @@ export interface PayloadFieldSpec {
   versionedRefSeriesWireType?: string;
   /** for enums: the Dart enum type name + raw values. */
   enumValues?: string[];
-  /** how this field serialises into `nmsInternalToPayloadJson()`. */
-  toJson: ToJsonWrap;
+  /** Concrete generated Dart shape consumed directly by the USDA encoder. */
+  shape: DartPayloadShape;
   /** Wire scalar under a nominal wrapper. Keeps string semantics distinct from numeric units. */
   wrappedScalarKind?: "string" | "number";
   /**
    * Whether the payload field is OPTIONAL (Zod `.optional()`/`.default()`). Optional
-   * fields are nullable in Dart and OMITTED from `nmsInternalToPayloadJson()` when null — so the
-   * engine's `.plan()` sees exactly the present-field set its TS Zod schema would (it
-   * only emits ops for present fields). Required fields are always emitted.
+   * fields are nullable in Dart and omitted from the generated USDA call when null, so
+   * the engine's `.plan()` sees exactly the present-field set its schema declares.
    */
   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 —
-   * `nmsInternalToPayloadJson` then omits, writes a real `null`, or writes the value accordingly.
+   * the USDA encoder 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;
 }
@@ -159,7 +160,7 @@ export function dartForeignReferenceInputs(
   const outputs = aggregates.filter((aggregate) => outputIds.has(aggregate.id));
 
   return specs.flatMap((spec) => {
-    if (spec.toJson !== "ref" || recordInputIds.has(spec.name)) return [];
+    if (spec.shape !== "ref" || recordInputIds.has(spec.name)) return [];
     const matches = outputs.flatMap((aggregate) => {
       const field = aggregate.fields[spec.name] as Field | undefined;
       if (
@@ -364,7 +365,7 @@ function isOptionalOrDefault(zt: z.ZodTypeAny): boolean {
  * engine's same Zod schema validates, so the call-site type can never truncate a
  * fractional value the engine would accept.
  */
-function zodNumberIsInt(zt: z.ZodTypeAny): boolean {
+export function zodNumberIsInt(zt: z.ZodTypeAny): boolean {
   const raw = zt as unknown as { isInt?: boolean };
   if (raw.isInt === true) return true;
   const checks = zodDef(zt).checks ?? [];
@@ -401,6 +402,11 @@ export function introspectPayload(
       else optional = true;
       zt = zodInnerType(zt);
     }
+    // Literal fields are compiler-owned constants. The canonical USDA encoder emits
+    // them from the DSL graph, so exposing them as Dart constructor arguments would
+    // widen a literal constraint into an ordinary bool/string/number and ask callers
+    // to repeat information the model already knows.
+    if (zodTypeName(zt) === "ZodLiteral") continue;
     out.push({
       ...introspectField(name, zt, enumDartTypes, lazyNames),
       optional,
@@ -410,6 +416,20 @@ export function introspectPayload(
   return out;
 }
 
+function dartAnonymousRecordType(
+  schema: z.ZodTypeAny,
+  enumDartTypes: Map<string, string>,
+  lazyNames?: Map<z.ZodTypeAny, string>,
+): string {
+  const fields = introspectPayload(schema, enumDartTypes, lazyNames).map((spec) => {
+    if (spec.nullAdmits === true) {
+      return `NomosSlot<${stripNullable(spec.dartType)}> ${dartMemberName(spec.name)}`;
+    }
+    return `${spec.dartType}${spec.optional ? "?" : ""} ${dartMemberName(spec.name)}`;
+  });
+  return `({${fields.join(", ")}})`;
+}
+
 /**
  * The aggregate ids a directive set references via `idOf(Agg)` in its TOP-LEVEL payload fields
  * (dart_codegen_parity.md P2). A cross-domain `idOf` types the field as `NomosRef<SiblingAggregate>`;
@@ -441,8 +461,8 @@ export function collectPayloadIdOfTargets(directives: readonly { payloadSchema?:
 
 /** Introspect ONE (already-unwrapped) Zod field into its Dart spec. Handles the
  * four shapes a tenant domain uses: scalar (string/int/bool), enum, string[], and a
- * NESTED object (e.g. attach/detach's `target:{targetType,targetId}`) — the engine
- * receives nested objects as DATA, so we model them as `Map<String, Object?>`. */
+ * NESTED object (e.g. attach/detach's `target:{targetType,targetId}`), represented
+ * as a structural Dart named record rather than a generic map. */
 function introspectField(
   name: string,
   zt: z.ZodTypeAny,
@@ -458,7 +478,7 @@ function introspectField(
       name,
       dartType: `NomosRef<${target}>`,
       referenceType: addressed.aggregateType,
-      toJson: "addressRef",
+      shape: "addressRef",
     };
   }
   const versioned = versionedRefOfMetaOf(zt);
@@ -472,7 +492,7 @@ function introspectField(
     return {
       name,
       dartType: `VersionedNomosRef<${target}, ${series}>`,
-      toJson: "versionedRef",
+      shape: "versionedRef",
       versionedRefTarget: target,
       versionedRefSeries: series,
       versionedRefCurrentField: versioned.currentField,
@@ -487,32 +507,27 @@ function introspectField(
     };
   }
   if (recipientMetaOf(zt) !== undefined) {
-    return { name, dartType: "Recipient<User>", toJson: "recipient" };
+    return { name, dartType: "Recipient<User>", shape: "recipient" };
   }
-  // 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.
+  // RECURSIVE `z.lazy`: the compiler must synthesize a typed recursive class for the knot.
+  // There is deliberately no Object?/JSON fallback on the authoring path.
   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.
+    if (cls !== undefined) return { name, dartType: cls, shape: "vo" };
+    // A recursive payload must have a generated nominal class. Refuse degraded knots instead
+    // of silently reopening an Object?/JSON escape hatch.
     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" };
+    if (zodTypeName(inner) === "ZodLazy") {
+      throw new Error(`recursive payload field '${name}' has no generated Dart type`);
     }
+    return introspectField(name, inner, enumDartTypes, lazyNames);
   }
   // 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).
   {
     const vo = voMetaOf(zt);
     if (vo !== undefined) {
-      return { name, dartType: vo.name, toJson: "vo" };
+      return { name, dartType: vo.name, shape: "vo" };
     }
   }
   const tn = zodTypeName(zt);
@@ -530,21 +545,21 @@ function introspectField(
           name,
           dartType: `NomosRef<${targetClass}>`,
           referenceType: idAgg,
-          toJson: "ref",
+          shape: "ref",
         };
       }
       if (isSha256DigestSchema(zt)) {
-        return { name, dartType: "Sha256Digest", toJson: "wrapped", wrappedScalarKind: "string" };
+        return { name, dartType: "Sha256Digest", shape: "wrapped", wrappedScalarKind: "string" };
       }
       if (isGitObjectIdSchema(zt)) {
-        return { name, dartType: "GitObjectId", toJson: "wrapped", wrappedScalarKind: "string" };
+        return { name, dartType: "GitObjectId", shape: "wrapped", wrappedScalarKind: "string" };
       }
       // brandedId("SiteId"): a standalone nominal string → the generated extension type.
       const brand = brandedIdMetaOf(zt);
       if (brand !== undefined) {
-        return { name, dartType: brand, toJson: "wrapped", wrappedScalarKind: "string" };
+        return { name, dartType: brand, shape: "wrapped", wrappedScalarKind: "string" };
       }
-      return { name, dartType: "String", toJson: "scalar" };
+      return { name, dartType: "String", shape: "scalar" };
     }
     case "ZodNumber":
       // A `z.number()` is a FRACTIONAL double in JS (e.g. catalogues `createListing`
@@ -556,21 +571,21 @@ function introspectField(
       {
         const unitName = (zt as unknown as Record<symbol, unknown>)[NOMOS_UNIT_BRAND];
         if (typeof unitName === "string") {
-          return { name, dartType: unitName, toJson: "wrapped", wrappedScalarKind: "number" };
+          return { name, dartType: unitName, shape: "wrapped", wrappedScalarKind: "number" };
         }
       }
       return {
         name,
         dartType: zodNumberIsInt(zt) ? "int" : "double",
-        toJson: "scalar",
+        shape: "scalar",
       };
     case "ZodBoolean":
-      return { name, dartType: "bool", toJson: "scalar" };
+      return { name, dartType: "bool", shape: "scalar" };
     case "ZodEnum": {
       const values = zodEnumValues(zt);
       const key = dartEnumLookupKey(zt);
       const dartType = enumDartTypes.get(key) ?? `${cap(name)}Enum`;
-      return { name, dartType, toJson: "enum", enumValues: values };
+      return { name, dartType, shape: "enum", enumValues: values };
     }
     case "ZodArray": {
       const elem = zodArrayElement(zt);
@@ -578,18 +593,53 @@ function introspectField(
       // with the generated VO class (vo_first_class.md). ANY other element
       // type is arbitrary JSON DATA to the engine, modelled as `List<Object?>`.
       if (zodTypeName(elem) === "ZodString") {
-        return { name, dartType: "List<String>", toJson: "strList" };
+        const idAgg = idOfMetaOf(elem);
+        if (idAgg !== undefined) {
+          const targetClass = idOfTargetKindOf(elem) === "contract"
+            ? contractTypeName(idAgg)
+            : concreteClassName(idAgg);
+          return {
+            name,
+            dartType: `List<NomosRef<${targetClass}>>`,
+            referenceType: idAgg,
+            shape: "refList",
+          };
+        }
+        if (isSha256DigestSchema(elem)) {
+          return { name, dartType: "List<Sha256Digest>", shape: "wrappedList", wrappedScalarKind: "string" };
+        }
+        if (isGitObjectIdSchema(elem)) {
+          return { name, dartType: "List<GitObjectId>", shape: "wrappedList", wrappedScalarKind: "string" };
+        }
+        const brand = brandedIdMetaOf(elem);
+        if (brand !== undefined) {
+          return { name, dartType: `List<${brand}>`, shape: "wrappedList", wrappedScalarKind: "string" };
+        }
+        return { name, dartType: "List<String>", shape: "strList" };
+      }
+      if (zodTypeName(elem) === "ZodNumber") {
+        const unitName = (elem as unknown as Record<symbol, unknown>)[NOMOS_UNIT_BRAND];
+        if (typeof unitName === "string") {
+          return { name, dartType: `List<${unitName}>`, shape: "wrappedList", wrappedScalarKind: "number" };
+        }
       }
       // 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" };
+        return { name, dartType: `List<${elemCls}>`, shape: "voList" };
       }
       const elemVo = voMetaOf(elem);
       if (elemVo !== undefined) {
-        return { name, dartType: `List<${elemVo.name}>`, toJson: "voList" };
+        return { name, dartType: `List<${elemVo.name}>`, shape: "voList" };
       }
-      return { name, dartType: "List<Object?>", toJson: "json" };
+      if (zodTypeName(elem) === "ZodObject") {
+        return {
+          name,
+          dartType: `List<${dartAnonymousRecordType(elem, enumDartTypes, lazyNames)}>`,
+          shape: "recordList",
+        };
+      }
+      throw new Error(`payload list '${name}' needs a generated concrete Dart element type`);
     }
     case "ZodObject": {
       // A DECLARED VALUE OBJECT keeps its name: the payload field is the generated VO class
@@ -597,24 +647,23 @@ function introspectField(
       // own `toJson()`. An anonymous `z.object(...)` stays the raw-map lane below.
       const vo = voMetaOf(zt);
       if (vo !== undefined) {
-        return { name, dartType: vo.name, toJson: "vo" };
+        return { name, dartType: vo.name, shape: "vo" };
       }
-      // Nested object payload (e.g. `target: z.object({targetType, targetId})`). The
-      // engine receives it as DATA verbatim, so we model it as an arbitrary JSON map
-      // — the call site builds the literal, and `toPayloadJson()` ships it through.
-      return { name, dartType: "Map<String, Object?>", toJson: "json" };
+      return {
+        name,
+        dartType: dartAnonymousRecordType(zt, enumDartTypes, lazyNames),
+        shape: "record",
+      };
     }
     case "ZodRecord": {
       const valueType = zodRecordValueType(zt);
-      const dartType =
-        valueType !== undefined && zodTypeName(valueType) === "ZodString"
-          ? "Map<String, String>"
-          : "Map<String, Object?>";
-      return { name, dartType, toJson: "json" };
+      if (valueType === undefined || zodTypeName(valueType) !== "ZodString") {
+        throw new Error(`payload map '${name}' needs a generated concrete Dart value type`);
+      }
+      return { name, dartType: "Map<String, String>", shape: "stringMap" };
     }
     case "ZodThing":
-      // A `z.thing(...)` payload — also arbitrary JSON DATA to the engine.
-      return { name, dartType: "Map<String, Object?>", toJson: "json" };
+      throw new Error(`payload field '${name}' is an unstructured thing; declare its typed schema`);
     default:
       throw new Error(`unsupported payload field type '${tn}' for '${name}'`);
   }
@@ -638,7 +687,7 @@ function directiveDoc(d: AnyDirective): string {
 
 type MaterializedFieldKind = Exclude<FieldKind, "hasMany">;
 
-interface AggFieldSpec {
+export interface AggFieldSpec {
   /** Dart-safe field/property name exposed on generated classes. */
   name: string;
   /** Canonical wire/readmodel key declared by the DSL, e.g. `spec.domainHash`. */
@@ -879,7 +928,7 @@ function dartImportLine(imp: DartImport): string {
   return `import '${imp.uri}'${prefix};`;
 }
 
-function refIdClassResolver(mod: DomainModule): (aggregateType: string) => string {
+export function refIdClassResolver(mod: DomainModule): (aggregateType: string) => string {
   const imports = new Map<string, DartRefImport>();
   for (const imp of mod.dartRefImports ?? []) {
     imports.set(imp.aggregateType, imp);
@@ -1164,7 +1213,7 @@ function aggFieldSpec(
   }
 }
 
-function aggregateFieldSpecs(
+export function aggregateFieldSpecs(
   agg: AggregateHandle,
   enumDartTypes: Map<string, string>,
   refIdClassForAggregate: (aggregateType: string) => string = concreteClassName,
@@ -1381,21 +1430,31 @@ export function collectDartEnums(
       }
     }
     for (const d of directives) {
-      if (zodTypeName(d.payloadSchema as z.ZodTypeAny) !== "ZodObject") continue;
-      const shape = zodObjectShape(d.payloadSchema as z.ZodTypeAny);
-      for (const [name, zt] of Object.entries(shape)) {
-        const inner = unwrapZod(zt as z.ZodTypeAny);
-        if (zodTypeName(inner) === "ZodEnum") {
+      const walkPayloadEnums = (schema: z.ZodTypeAny, path: readonly string[]): void => {
+        const inner = unwrapZod(schema);
+        const kind = zodTypeName(inner);
+        if (kind === "ZodEnum") {
           const declaredName = enumTypeNameOf(inner);
-          if ((declaredName !== undefined) !== namedPass) continue;
+          if ((declaredName !== undefined) !== namedPass) return;
+          const fieldName = path.at(-1) ?? d.id;
           register(
-            name,
+            fieldName,
             zodEnumValues(inner),
-            (d as { aggregateId?: string }).aggregateId ?? d.id,
+            `${(d as { aggregateId?: string }).aggregateId ?? d.id}${path.length > 1 ? cap(path.slice(0, -1).join("_")) : ""}`,
             declaredName,
           );
+          return;
         }
-      }
+        if (kind === "ZodArray") {
+          walkPayloadEnums(zodArrayElement(inner), path);
+          return;
+        }
+        if (kind !== "ZodObject") return;
+        for (const [name, child] of Object.entries(zodObjectShape(inner))) {
+          walkPayloadEnums(child as z.ZodTypeAny, [...path, name]);
+        }
+      };
+      walkPayloadEnums(d.payloadSchema as z.ZodTypeAny, []);
     }
   }
   for (const declaration of deriveds) {
@@ -1419,7 +1478,7 @@ export function dartEnumTypeForField(
   return dartTypes.get(dartEnumLookupKey(unwrapZod(field.zod)));
 }
 
-function dartEnumLookupKey(
+export function dartEnumLookupKey(
   schemaOrValues: z.ZodTypeAny | readonly string[],
   declaredName?: string,
 ): string {
@@ -1969,7 +2028,7 @@ function voEnumFields(d: ValueObjectDescriptor): {
 }
 
 /** The generated arm class name of one union arm (`Shape` + `circle` → `ShapeCircle`). */
-function unionArmClassName(unionName: string, armKey: string): string {
+export function unionArmClassName(unionName: string, armKey: string): string {
   return `${unionName}${armKey[0]!.toUpperCase()}${armKey.slice(1)}`;
 }
 
@@ -2073,12 +2132,16 @@ function voToJsonExpr(f: ValueObjectFieldDescriptor, expr: string, depth = 0): s
 
 /** Deep json equality/hash helpers shared by every generated VO class — emitted ONCE
  * per file when the file emits ≥1 VO class (`toJson()`-based value equality). */
-function emitVoHelpers(): string {
+function emitVoHelpers(includeCopyWithSentinel: boolean): string {
   return [
-    `/// The copyWith ABSENT-vs-null sentinel: an omitted optional param keeps the current`,
-    `/// value; an explicit \`null\` clears it. (Dart cannot distinguish the two otherwise.)`,
-    `const Object _voUnset = Object();`,
-    ``,
+    ...(includeCopyWithSentinel
+      ? [
+          `/// The copyWith ABSENT-vs-null sentinel: an omitted optional param keeps the current`,
+          `/// value; an explicit \`null\` clears it. (Dart cannot distinguish the two otherwise.)`,
+          `const Object _voUnset = Object();`,
+          ``,
+        ]
+      : []),
     `/// Deep json equality for generated value-object classes (toJson-based).`,
     `bool _voJsonEq(Object? a, Object? b) {`,
     `  if (a is Map && b is Map) {`,
@@ -3753,15 +3816,11 @@ function emitDirective(
   const specs = introspectPayload(d.payloadSchema as z.ZodTypeAny, enumDartTypes, lazyNames);
   const recordInputs = dartBusinessRecordInputs(d, aggregates);
   const foreignReferenceInputs = dartForeignReferenceInputs(d, aggregates);
-  const foreignReferenceIds = new Set(foreignReferenceInputs.map((input) => input.idField));
   const principalField = d.businessPrincipalField;
   // targetBinding is declared on AnyDirective — honour it everywhere (client method,
   // payload class, application surface) or the three emitters disagree and the
   // generated Dart cannot compile.
   const targetBinding = (d as { targetBinding?: import("./directive.js").DirectiveTargetBinding }).targetBinding;
-  const targetType = targetBinding === undefined
-    ? undefined
-    : `NomosRef<${concreteClassName(targetBinding.aggregateId)}>`;
   const derivedFields = new Set([
     ...recordInputs.flatMap((input) => [input.idField, input.workspaceField]),
     ...foreignReferenceInputs.map((input) => input.workspaceField),
@@ -3774,33 +3833,18 @@ function emitDirective(
   // makes an accidentally forgotten relationship indistinguishable from a
   // deliberate omission. The generated sum type keeps those meanings apart.
   const isOptionalReferenceChoice = (spec: PayloadFieldSpec): boolean =>
-    spec.optional && spec.toJson === "ref";
-  const internalPayloadArguments = [
-    ...(targetBinding === undefined
-      ? []
-      : [`required ${targetType} nmsInternalTarget`]),
-    ...(principalField === undefined ? [] : ["required String nmsInternalPrincipal"]),
-    ...(recordInputs.length === 0
-      ? []
-      : [
-          "required String Function(Object record) nmsInternalLocationOf",
-          "required String Function(Object record) nmsInternalIdOf",
-        ]),
-  ];
-  const internalPayloadSignature = internalPayloadArguments.length === 0
-    ? ""
-    : `{${internalPayloadArguments.join(", ")}}`;
+    spec.optional && spec.shape === "ref";
 
-  // 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.
+  // Field declarations stay fully typed; optional fields are omitted directly by
+  // the USDA encoder while required fields remain non-null constructor inputs.
   const fieldDecls = [
     ...publicSpecs
     .map((s) =>
       s.nullAdmits === true
-        ? `  final NomosSlot<${stripNullable(s.dartType)}> ${s.name};`
+        ? `  final NomosSlot<${stripNullable(s.dartType)}> ${dartMemberName(s.name)};`
         : isOptionalReferenceChoice(s)
-          ? `  final NomosOptionalRef<${s.dartType.replace(/^NomosRef<(.*)>$/, "$1")}> ${s.name};`
-        : `  final ${s.dartType}${s.optional ? "?" : ""} ${s.name};`,
+          ? `  final NomosOptionalRef<${s.dartType.replace(/^NomosRef<(.*)>$/, "$1")}> ${dartMemberName(s.name)};`
+        : `  final ${s.dartType}${s.optional ? "?" : ""} ${dartMemberName(s.name)};`,
     ),
     ...recordInputs.map((input) => `  final ${input.dartType} ${input.argument};`),
   ].join("\n");
@@ -3810,10 +3854,10 @@ function emitDirective(
       // 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(),`
+        ? `    this.${dartMemberName(s.name)} = const NomosSlot.omitted(),`
         : isOptionalReferenceChoice(s)
-          ? `    required this.${s.name},`
-        : `    ${s.optional ? "" : "required "}this.${s.name},`,
+          ? `    required this.${dartMemberName(s.name)},`
+        : `    ${s.optional ? "" : "required "}this.${dartMemberName(s.name)},`,
     ),
     ...recordInputs.map((input) => `    required this.${input.argument},`),
   ].join("\n");
@@ -3825,90 +3869,6 @@ function emitDirective(
     ? [`  const ${className}({`, ctorParams, `  });`]
     : [`  const ${className}();`];
 
-  // toPayloadJson: serialise only typed fields to data. No Event, no Hlc; the
-  // GitHolon executes the installed domain plan. Optional
-  // fields are written only when present (mirrors the engine's Zod: ops are emitted
-  // only for present fields).
-  const requiredEntries = specs
-    .filter((s) =>
-      !derivedFields.has(s.name) &&
-      !foreignReferenceIds.has(s.name) &&
-      !s.optional &&
-      s.nullAdmits !== true
-    )
-    .map((s) => `    '${s.name}': ${toJsonExpr(s, s.name)},`);
-  const targetEntry = targetBinding === undefined
-    ? []
-    : [`    '${targetBinding.field}': NmsInternalNomosRefs.id(nmsInternalTarget),`];
-  const optionalLines = specs
-    .filter((s) =>
-      !derivedFields.has(s.name) &&
-      s.optional &&
-      s.nullAdmits !== true &&
-      !isOptionalReferenceChoice(s)
-    )
-    .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) => !derivedFields.has(s.name) && s.nullAdmits === true);
-  const slotWriteLines = slotSpecs.map(
-    (s) => `    ${s.name}.writeTo(data, '${s.name}', (v) => ${toJsonExpr(s, "v")});`,
-  );
-  const optionalReferenceSpecs = specs.filter(
-    (s) =>
-      !derivedFields.has(s.name) &&
-      !foreignReferenceIds.has(s.name) &&
-      isOptionalReferenceChoice(s),
-  );
-  const optionalReferenceWriteLines = optionalReferenceSpecs.map(
-    (s) => `    ${s.name}.writeTo(data, '${s.name}', (reference) => NmsInternalNomosRefs.id(reference));`,
-  );
-  const requiredForeignReferenceInputs = foreignReferenceInputs.filter((input) => !input.optional);
-  const requiredWorkspaceSources = new Map<string, DartForeignReferenceInput>();
-  const requiredForeignReferenceEntries = requiredForeignReferenceInputs.flatMap((input) => {
-    const first = requiredWorkspaceSources.get(input.workspaceField);
-    if (first === undefined) requiredWorkspaceSources.set(input.workspaceField, input);
-    return [
-      ...(first === undefined
-        ? [`    '${input.workspaceField}': NmsInternalNomosRefs.workspace(${input.idField}),`]
-        : []),
-      `    '${input.idField}': NmsInternalNomosRefs.id(${input.idField}),`,
-    ];
-  });
-  const requiredForeignReferenceValidationLines = requiredForeignReferenceInputs.flatMap((input) => {
-    const first = requiredWorkspaceSources.get(input.workspaceField)!;
-    if (first.idField === input.idField) return [];
-    return [
-      `    if (NmsInternalNomosRefs.workspace(${input.idField}) != NmsInternalNomosRefs.workspace(${first.idField})) {`,
-      `      throw ArgumentError('Foreign references for ${input.workspaceField} must belong to the same workspace.');`,
-      `    }`,
-    ];
-  });
-  const optionalForeignReferenceWriteLines = foreignReferenceInputs
-    .filter((input) => input.optional)
-    .flatMap((input) => [
-      `    ${input.idField}.when(`,
-      `      absent: () {},`,
-      `      present: (reference) {`,
-      `        final workspace = NmsInternalNomosRefs.workspace(reference);`,
-      `        final existingWorkspace = data['${input.workspaceField}'];`,
-      `        if (existingWorkspace != null && existingWorkspace != workspace) {`,
-      `          throw ArgumentError('Foreign references for ${input.workspaceField} must belong to the same workspace.');`,
-      `        }`,
-      `        data['${input.workspaceField}'] = workspace;`,
-      `        data['${input.idField}'] = NmsInternalNomosRefs.id(reference);`,
-      `      },`,
-      `    );`,
-    ]);
-  const hasPostWrites =
-    slotSpecs.length > 0 ||
-    optionalReferenceSpecs.length > 0 ||
-    requiredForeignReferenceValidationLines.length > 0 ||
-    optionalForeignReferenceWriteLines.length > 0;
-
   const docFirst = directiveDoc(d);
 
   return [
@@ -3923,72 +3883,10 @@ function emitDirective(
     `  /// ${docFirst}`,
     ...ctorLines,
     ``,
-    `  /// Nomos implementation seam used only by the generated application package.`,
-    `  /// Tenant code should pass this object to the generated domain application instead.`,
-    ...(hasPostWrites
-      ? [
-          `  Map<String, Object?> nmsInternalToPayloadJson(${internalPayloadSignature}) {`,
-          `    final data = <String, Object?>{`,
-          ...requiredEntries,
-          ...targetEntry,
-          ...requiredForeignReferenceEntries,
-          ...optionalLines,
-          ...(principalField === undefined ? [] : [`      '${principalField}': nmsInternalPrincipal,`]),
-          ...recordInputs.flatMap((input) => [
-            `      '${input.workspaceField}': nmsInternalLocationOf(${input.argument}),`,
-            `      '${input.idField}': nmsInternalIdOf(${input.argument}),`,
-          ]),
-          `    };`,
-          ...requiredForeignReferenceValidationLines,
-          ...slotWriteLines,
-          ...optionalReferenceWriteLines,
-          ...optionalForeignReferenceWriteLines,
-          `    return data;`,
-          `  }`,
-        ]
-      : [
-          `  Map<String, Object?> nmsInternalToPayloadJson(${internalPayloadSignature}) => <String, Object?>{`,
-          ...requiredEntries,
-          ...targetEntry,
-          ...requiredForeignReferenceEntries,
-          ...optionalLines,
-          ...(principalField === undefined ? [] : [`    '${principalField}': nmsInternalPrincipal,`]),
-          ...recordInputs.flatMap((input) => [
-            `    '${input.workspaceField}': nmsInternalLocationOf(${input.argument}),`,
-            `    '${input.idField}': nmsInternalIdOf(${input.argument}),`,
-          ]),
-          `  };`,
-        ]),
     `}`,
   ].join("\n");
 }
 
-/** Expression that serialises ONE typed payload field into its JSON value. */
-export function toJsonExpr(spec: PayloadFieldSpec, accessor: string): string {
-  switch (spec.toJson) {
-    case "scalar":
-    case "strList":
-    case "json":
-      return accessor;
-    case "enum":
-      return `${accessor}.wire`;
-    case "vo":
-      return `${accessor}.toJson()`;
-    case "voList":
-      return `${accessor}.map((e) => e.toJson()).toList()`;
-    case "wrapped":
-      return `${accessor}.value`;
-    case "ref":
-      return `NmsInternalNomosRefs.id(${accessor})`;
-    case "addressRef":
-      return `NmsInternalNomosRefs.toJson(${accessor})`;
-    case "versionedRef":
-      return `{'pinned': NmsInternalNomosRefs.toJson(${accessor}.pinned), 'series': NmsInternalNomosRefs.toJson(${accessor}.series)}`;
-    case "recipient":
-      return `NmsInternalRecipients.address(${accessor})`;
-  }
-}
-
 // ── RECURSIVE `z.lazy` payloads → synthesized Dart classes (full support) ─────────
 //
 // A self-referencing payload schema (`TreeNode = z.lazy(() => z.object({ label, children:
@@ -4714,7 +4612,7 @@ function sampleFromZod(zt: z.ZodTypeAny): unknown {
   }
 }
 
-function collectOwnIdFieldsByAggregate(
+export function collectOwnIdFieldsByAggregate(
   aggregates: AggregateHandle[],
   directives: AnyDirective[],
   enumDartTypes: Map<string, string>,
@@ -5060,6 +4958,14 @@ export interface GenerateDartDomainOptions {
    * module carries locally.
    */
   readonly skipValueObjectNames?: ReadonlySet<string>;
+  /**
+   * Additional compiler-proven value-object closure to emit in this file. The package
+   * composer uses this only for its synthetic shared types layer: ordinary domains
+   * still derive their public vocabulary from public aggregates and payloads, so a
+   * private framework aggregate cannot leak a nominal type into tenant Dart merely
+   * because it was present in the composed law.
+   */
+  readonly additionalValueObjects?: readonly ValueObjectDescriptor[];
 }
 
 /** Generate the full Dart source for one domain module. */
@@ -5068,9 +4974,31 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
     (a) => (a as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
   );
   const publicAggregateIds = new Set(publicAggregates.map((a) => a.id));
+  // Recompute the value vocabulary after removing framework-internal aggregates.
+  // `mod.valueObjects` describes the whole composed law, so carrying it through
+  // here would publish private framework values merely because they coexist with
+  // the tenant domain. Payload-only public values are collected below from the
+  // public directives, preserving every type reachable from the application API.
+  const publicAggregateValueObjectsByName = new Map<string, ValueObjectDescriptor>();
+  for (const descriptor of [
+    ...collectValueObjectDescriptors(publicAggregates),
+    ...(opts.additionalValueObjects ?? []),
+  ]) {
+    const prior = publicAggregateValueObjectsByName.get(descriptor.name);
+    if (prior !== undefined && JSON.stringify(prior) !== JSON.stringify(descriptor)) {
+      throw new Error(
+        `value object '${descriptor.name}' has DIVERGENT public/shared Dart shapes — one name, one shape`,
+      );
+    }
+    publicAggregateValueObjectsByName.set(descriptor.name, descriptor);
+  }
+  const publicAggregateValueObjects = [...publicAggregateValueObjectsByName.values()].sort(
+    (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0),
+  );
   mod = {
     ...mod,
     aggregates: publicAggregates,
+    valueObjects: publicAggregateValueObjects,
     directives: (mod.applicationIntents ?? mod.directives).filter(
       (d) => (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
     ),
@@ -5149,7 +5077,7 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
       try {
         for (const spec of introspectPayload(schema as z.ZodTypeAny, new Map())) {
           // A wrapped spec whose brand a VO descriptor already registered is a brandedId, not a unit.
-          if (spec.toJson === "wrapped" && spec.wrappedScalarKind === "number") {
+          if (spec.shape === "wrapped" && spec.wrappedScalarKind === "number") {
             unitNames.add(spec.dartType);
           }
         }
@@ -5178,12 +5106,18 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
     `/// passing a bare String (or another brand) where [${b}] is required is a COMPILE error.`,
     `extension type const ${b}(String value) {}`,
   ].join("\n")).join("\n\n");
+  const needsVoCopyWithSentinel = localValueObjects.some((descriptor) =>
+    Object.values(descriptor.fields ?? {}).some((field) => field.optional === true)
+    || Object.values(descriptor.union ?? {}).some((arm) =>
+      "fields" in arm && Object.values(arm.fields).some((field) => field.optional === true),
+    )
+  );
   const voBlock = [
     ...(unitBlock !== "" ? [unitBlock] : []),
     ...(brandBlock !== "" ? [brandBlock] : []),
     ...(localValueObjects.length > 0
       ? [
-          emitVoHelpers(),
+          emitVoHelpers(needsVoCopyWithSentinel),
           ...localValueObjects.flatMap((d) => [
             ...voEnumFields(d)
               .filter((e) => e.declaredName === undefined)
@@ -5501,16 +5435,14 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
         ]
       : []),
     ...helperBlock,
-    // NOTE: role UI-hint helpers (canEdit/canView) are emitted into the CLIENT package by dartRoleHelpers,
-    // NOT here — they need dart:convert, which the types-package purity gate forbids.
+    // NOTE: role UI-hint helpers (canEdit/canView) are emitted into the CLIENT package by dartRoleHelpers.
   ].join("\n");
 }
 
 /** The role UI-hint helpers (`canEdit<Agg>`/`canView<Agg>` + `_holdsAnyRelation`) for the CLIENT package — a
- *  pure client-side MIRROR of the kernel ReBAC check over the folded RelationTuple projection. INFORMATIONAL
- *  only (the one wasm gate is the authority and refuses regardless). Uses `dart:convert` (jsonDecode of the
- *  per-subject leaf), so it may NOT live in the pure types file — the caller emits it into `<name>.client.dart`
- *  and ensures a `dart:convert` import. Returns "" when the domain declares no roles (era-safe, no import). */
+ *  pure client-side mirror of the kernel ReBAC check over the compiler-generated RelationTuple projection.
+ *  Every tuple and subject is nominally typed from the same DSL graph; there is no JSON leaf or map-shaped
+ *  boundary. INFORMATIONAL only (the one wasm gate is still authoritative). */
 export function dartRoleHelpers(mod: DomainModule): string {
   const editRels = new Map<string, Set<string>>();
   const viewRels = new Map<string, Set<string>>();
@@ -5525,21 +5457,14 @@ export function dartRoleHelpers(mod: DomainModule): string {
   if (editRels.size === 0 && viewRels.size === 0) return "";
   const lines: string[] = [
     `/// True iff [principal] holds ANY of [relations] as an ACTIVE tuple in [rows] (or a \`user:*\` wildcard).`,
-    `bool _holdsAnyRelation(List<Map<String, dynamic>>? rows, Set<String> relations, String principal) {`,
+    `bool _holdsAnyRelation(List<RelationTupleReadModel>? rows, Set<String> relations, String principal) {`,
     `  for (final r in rows ?? const []) {`,
-    `    final data = r['data'];`,
-    `    if (data is! Map) continue;`,
-    `    final rel = data['relation'];`,
-    `    if (rel is! String || !relations.contains(rel)) continue;`,
-    `    final subjects = data['subjects'];`,
-    `    if (subjects is! Map) continue;`,
-    `    for (final entry in subjects.entries) {`,
-    `      final subj = entry.key.toString();`,
-    `      dynamic leaf = entry.value;`,
-    `      if (leaf is String) { try { leaf = jsonDecode(leaf); } catch (_) { leaf = const {}; } }`,
-    `      final status = leaf is Map ? leaf['status'] : null;`,
-    `      if (status != null && status != 'active') continue;`,
+    `    if (r.relation case final relation? when relations.contains(relation)) {`,
+    `      for (final entry in r.subjects.entries) {`,
+    `      final subj = entry.key;`,
+    `      if (entry.value.status != RelationshipSubjectStatus.active) continue;`,
     `      if (subj == 'user:\$principal' || subj == 'user:*') return true;`,
+    `      }`,
     `    }`,
     `  }`,
     `  return false;`,
@@ -5550,14 +5475,14 @@ export function dartRoleHelpers(mod: DomainModule): string {
     lines.push(
       `/// UI HINT — may [principal] EDIT a ${agg}? Mirrors the kernel's ReBAC check; INFORMATIONAL only`,
       `/// (the one wasm gate is the authority and refuses regardless).`,
-      `bool canEdit${cap(agg)}(List<Map<String, dynamic>>? relations, String principal) =>`,
+      `bool canEdit${cap(agg)}(List<RelationTupleReadModel>? relations, String principal) =>`,
       `    _holdsAnyRelation(relations, ${dartSet(rels)}, principal);`,
     );
   }
   for (const [agg, rels] of [...viewRels].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
     lines.push(
       `/// UI HINT — may [principal] VIEW a ${agg}? Mirrors the kernel's ReBAC read gate; INFORMATIONAL only.`,
-      `bool canView${cap(agg)}(List<Map<String, dynamic>>? relations, String principal) =>`,
+      `bool canView${cap(agg)}(List<RelationTupleReadModel>? relations, String principal) =>`,
       `    _holdsAnyRelation(relations, ${dartSet(rels)}, principal);`,
     );
   }