@githolon/dsl 0.38.0 → 0.40.0

package/package.json

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

package/src/codegen_dart.ts

@@ -29,6 +29,7 @@
  * generated, so they stay reproducible from the domain definitions.
  */
 import { z } from "zod";
+import { voMetaOf, collectPayloadValueObjectDescriptors, idOfMetaOf, NOMOS_UNIT_BRAND } from "./value_object.js";
 import type { AggregateHandle } from "./aggregate.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import type { RelationTypeDecl } from "./relation_schema.js";
@@ -60,7 +61,10 @@ export type ToJsonWrap =
   | "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.
+  | "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()`.
+  | "wrapped"; // a typed-id class or unit extension type — emit `.value` (the wire scalar).
 
 export interface PayloadFieldSpec {
   name: string;
@@ -236,10 +240,25 @@ function introspectField(
   zt: z.ZodTypeAny,
   enumDartTypes: Map<string, string>,
 ): Omit<PayloadFieldSpec, "optional"> {
+  // 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" };
+    }
+  }
   const tn = zodTypeName(zt);
   switch (tn) {
-    case "ZodString":
+    case "ZodString": {
+      // idOf(Agg) (dart_codegen_parity.md P2): wire-identical to z.string(), but the Dart
+      // field is the aggregate's TYPED id class — cross-aggregate id mixups fail to compile.
+      const idAgg = idOfMetaOf(zt);
+      if (idAgg !== undefined) {
+        return { name, dartType: typedIdClassForAggregateType(idAgg), toJson: "wrapped" };
+      }
       return { name, dartType: "String", toJson: "scalar" };
+    }
     case "ZodNumber":
       // A `z.number()` is a FRACTIONAL double in JS (e.g. catalogues `createListing`
       // scaleX/scaleY = 0.5) UNLESS the schema adds the `.int()` check. Only an
@@ -247,6 +266,12 @@ function introspectField(
       // emits `double` so a fractional value (0.5/0.75) is NOT truncated to 0 at the
       // call site. Detect the `.int()` check on the Zod number's `_def.checks`
       // (`{kind:"int"}`), exactly the runtime constraint the engine's Zod validates.
+      {
+        const unitName = (zt as unknown as Record<symbol, unknown>)[NOMOS_UNIT_BRAND];
+        if (typeof unitName === "string") {
+          return { name, dartType: unitName, toJson: "wrapped" };
+        }
+      }
       return {
         name,
         dartType: zodNumberIsInt(zt) ? "int" : "double",
@@ -262,19 +287,31 @@ function introspectField(
     }
     case "ZodArray": {
       const elem = zodArrayElement(zt);
-      // A `string[]` is a typed `List<String>`. ANY other element type (e.g.
-      // `z.array(z.object(...))` — proposals' replacement `edges`) is arbitrary
-      // JSON DATA to the engine, modelled as `List<Object?>` and shipped verbatim.
+      // A `string[]` is a typed `List<String>`. A list of DECLARED VALUE OBJECTS is typed
+      // with the generated VO class (vo_authoring_end_to_end.md slice B). 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 elemVo = voMetaOf(elem);
+      if (elemVo !== undefined) {
+        return { name, dartType: `List<${elemVo.name}>`, toJson: "voList" };
+      }
       return { name, dartType: "List<Object?>", toJson: "json" };
     }
-    case "ZodObject":
+    case "ZodObject": {
+      // A DECLARED VALUE OBJECT keeps its name: the payload field is the generated VO class
+      // (typed author path — the same class the read model decodes to), serialised via its
+      // 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" };
+      }
       // 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" };
+    }
     case "ZodRecord": {
       const valueType = zodRecordValueType(zt);
       const dartType =
@@ -1246,16 +1283,28 @@ function emitVoEnum(voName: string, fieldName: string, values: readonly string[]
 
 /** Every (fieldName, values) enum pair a VO descriptor carries (arrays recursed —
  * an array-of-enum field's element enum is named by the FIELD). */
-function voEnumFields(d: ValueObjectDescriptor): { fieldName: string; values: readonly string[] }[] {
-  const out: { fieldName: string; values: readonly string[] }[] = [];
-  const walk = (fieldName: string, f: ValueObjectFieldDescriptor): void => {
-    if (f.type === "enum") out.push({ fieldName, values: f.values });
-    else if (f.type === "array") walk(fieldName, f.items);
+function voEnumFields(d: ValueObjectDescriptor): { fieldName: string; values: readonly string[]; owner?: string }[] {
+  const out: { fieldName: string; values: readonly string[]; owner?: string }[] = [];
+  const walk = (fieldName: string, f: ValueObjectFieldDescriptor, owner?: string): void => {
+    if (f.type === "enum") out.push({ fieldName, values: f.values, ...(owner !== undefined ? { owner } : {}) });
+    else if (f.type === "array") walk(fieldName, f.items, owner);
   };
   for (const [fieldName, f] of Object.entries(d.fields ?? {})) walk(fieldName, f);
+  // union arms: enums are owned by the ARM CLASS (`<Union><ArmCap>`) so two arms' same-named
+  // enum fields with different value sets never collide.
+  for (const [key, arm] of Object.entries(d.union ?? {})) {
+    if ("fields" in arm) {
+      for (const [fieldName, f] of Object.entries(arm.fields)) walk(fieldName, f, unionArmClassName(d.name, key));
+    }
+  }
   return out;
 }
 
+/** The generated arm class name of one union arm (`Shape` + `circle` → `ShapeCircle`). */
+function unionArmClassName(unionName: string, armKey: string): string {
+  return `${unionName}${armKey[0]!.toUpperCase()}${armKey.slice(1)}`;
+}
+
 /** The Dart type of one VO descriptor field. `voName`/`fieldName` name the field's
  * generated enum type (`<VoName><FieldName>Enum`) — threaded through arrays. */
 function dartTypeOfVoField(f: ValueObjectFieldDescriptor, voName: string, fieldName: string): string {
@@ -1263,12 +1312,16 @@ function dartTypeOfVoField(f: ValueObjectFieldDescriptor, voName: string, fieldN
     case "string":
       return "String";
     case "number":
-      return "double";
+      // a UNIT-tagged number is the generated zero-cost extension type; `.int()` is Dart int.
+      if (f.unit !== undefined) return f.unit;
+      return f.int === true ? "int" : "double";
     case "boolean":
       return "bool";
     case "enum":
       // A REAL generated Dart enum (`emitVoEnum`), named by the owning VO field.
       return voEnumName(voName, fieldName);
+    case "literal":
+      return "String"; // surfaced as a constant getter, not a ctor param
     case "array":
       return `List<${dartTypeOfVoField(f.items, voName, fieldName)}>`;
     case "object":
@@ -1293,7 +1346,10 @@ function voFromExpr(
       // TOLERANT typed decode — an unknown wire value becomes the sentinel case.
       return `${voEnumName(voName, fieldName)}.fromWire(${expr} as String)`;
     case "number":
-      return `(${expr} as num).toDouble()`;
+      if (f.unit !== undefined) return `${f.unit}((${expr} as num).toDouble())`;
+      return f.int === true ? `(${expr} as num).toInt()` : `(${expr} as num).toDouble()`;
+    case "literal":
+      return `${expr} as String`;
     case "boolean":
       return `${expr} as bool`;
     case "array": {
@@ -1309,9 +1365,11 @@ function voFromExpr(
 /** A Dart expression serializing the typed member `expr` back to plain json. */
 function voToJsonExpr(f: ValueObjectFieldDescriptor, expr: string, depth = 0): string {
   switch (f.type) {
-    case "string":
     case "number":
+      return f.unit !== undefined ? `${expr}.value` : expr;
+    case "string":
     case "boolean":
+    case "literal":
       return expr;
     case "enum":
       return `${expr}.wire`; // the exact wire string the law's zod enum validates
@@ -1365,7 +1423,121 @@ function emitVoHelpers(): string {
  * `toJson` (the authored payload shape — optionals OMITTED when null, matching the zod
  * `.optional()` contract), and toJson-based value equality. A `geo.*` VO emits the
  * fixed RFC 7946 shape (typed `coordinates`; `type` is the constant geometry kind). */
+/** Emit a `union(...)` as a SEALED Dart hierarchy: the sealed base (decode switch on the
+ * blessed `type` discriminator + abstract `toJson`), one final arm class per arm (anonymous
+ * arms carry their fields; NAMED-VO arms hold a single `value` of the named class), and the
+ * load-bearing `<Name>Unknown` arm: a client compiled under OLD law decodes a NEWER law's arm
+ * into `Unknown` (raw json, round-trips on re-write) instead of crashing — which makes adding
+ * an arm ADDITIVE evolution. Exhaustive `switch` over the sealed base forces call sites to
+ * decide what Unknown means for them (the forward-compat prompt we WANT the type system to give). */
+function emitUnionClasses(d: ValueObjectDescriptor): string {
+  const arms = Object.entries(d.union ?? {});
+  const base = [
+    `/// Union \`${d.name}\` — a sum type stored as ONE json leaf (wholesale-replace; the`,
+    `/// \`type\` discriminator names the arm). Adding an arm is ADDITIVE (older clients decode`,
+    `/// it as [${d.name}Unknown]); removing/renaming an arm is a retype (#58 dispositions).`,
+    `sealed class ${d.name} {`,
+    `  const ${d.name}();`,
+    `  Map<String, Object?> toJson();`,
+    `  factory ${d.name}.fromProjected(Map<String, Object?> m) => switch (m['type']) {`,
+    ...arms.map(([key]) => `        '${key}' => ${unionArmClassName(d.name, key)}.fromProjected(m),`),
+    `        _ => ${d.name}Unknown(m),`,
+    `      };`,
+    `}`,
+  ].join("\n");
+
+  const armClasses = arms.map(([key, arm]) => {
+    const cls = unionArmClassName(d.name, key);
+    if ("ref" in arm) {
+      return [
+        `/// The \`${key}\` arm of [${d.name}] — holds the named value object [${arm.ref}]`,
+        `/// (nested under \`value\` on the wire; the named VO stays the one home of its shape).`,
+        `final class ${cls} extends ${d.name} {`,
+        `  final ${arm.ref} value;`,
+        `  const ${cls}(this.value);`,
+        `  factory ${cls}.fromProjected(Map<String, Object?> m) =>`,
+        `      ${cls}(${arm.ref}.fromProjected((m['value']! as Map).cast<String, Object?>()));`,
+        `  @override`,
+        `  Map<String, Object?> toJson() => <String, Object?>{'type': '${key}', 'value': value.toJson()};`,
+        `  @override`,
+        `  bool operator ==(Object other) => other is ${cls} && _voJsonEq(other.toJson(), toJson());`,
+        `  @override`,
+        `  int get hashCode => _voJsonHash(toJson());`,
+        `}`,
+      ].join("\n");
+    }
+    const armFields = Object.entries(arm.fields).map(([wireName, f]) => ({
+      wireName,
+      member: dartMemberName(wireName),
+      f,
+      optional: f.optional === true,
+    }));
+    const armLiterals = armFields.filter((x) => x.f.type === "literal");
+    const fields = armFields.filter((x) => x.f.type !== "literal");
+    const literalGetters = armLiterals.map((x) => `  String get ${x.member} => '${(x.f as { value: string }).value}';`);
+    const literalToLines = armLiterals.map((x) => `        '${x.wireName}': '${(x.f as { value: string }).value}',`);
+    const decls = [
+      ...armFields.filter((x) => x.f.type !== "literal").map((x) => `  final ${dartTypeOfVoField(x.f, cls, x.wireName)}${x.optional ? "?" : ""} ${x.member};`),
+      ...literalGetters,
+    ];
+    const ctor = fields.length === 0
+      ? [`  const ${cls}();`]
+      : [`  const ${cls}({`, ...fields.map((x) => (x.optional ? `    this.${x.member},` : `    required this.${x.member},`)), `  });`];
+    const fromLines = fields.map((x) =>
+      x.optional
+        ? `      ${x.member}: m['${x.wireName}'] == null ? null : ${voFromExpr(x.f, `m['${x.wireName}']!`, cls, x.wireName)},`
+        : `      ${x.member}: ${voFromExpr(x.f, `m['${x.wireName}']!`, cls, x.wireName)},`,
+    );
+    const toLines = fields.map((x) =>
+      x.optional
+        ? `        if (${x.member} != null) '${x.wireName}': ${voToJsonExpr(x.f, `${x.member}!`)},`
+        : `        '${x.wireName}': ${voToJsonExpr(x.f, x.member)},`,
+    );
+    return [
+      `/// The \`${key}\` arm of [${d.name}].`,
+      `final class ${cls} extends ${d.name} {`,
+      ...decls,
+      ...ctor,
+      `  factory ${cls}.fromProjected(Map<String, Object?> m) => ${cls}(`,
+      ...fromLines,
+      `  );`,
+      `  @override`,
+      `  Map<String, Object?> toJson() => <String, Object?>{`,
+      `        'type': '${key}',`,
+      ...literalToLines,
+      ...toLines,
+      `      };`,
+      `  @override`,
+      `  bool operator ==(Object other) => other is ${cls} && _voJsonEq(other.toJson(), toJson());`,
+      `  @override`,
+      `  int get hashCode => _voJsonHash(toJson());`,
+      `}`,
+    ].join("\n");
+  });
+
+  const unknown = [
+    `/// FORWARD-COMPAT arm of [${d.name}]: a wire value whose \`type\` this client's law`,
+    `/// version does not know (a NEWER law added an arm). Carries the raw json VERBATIM —`,
+    `/// re-writing it round-trips unchanged. Handle it explicitly in every switch.`,
+    `final class ${d.name}Unknown extends ${d.name} {`,
+    `  final Map<String, Object?> raw;`,
+    `  const ${d.name}Unknown(this.raw);`,
+    `  /// The unrecognised discriminator value ('' when absent/malformed).`,
+    `  String get type => (raw['type'] ?? '').toString();`,
+    `  @override`,
+    `  Map<String, Object?> toJson() => raw;`,
+    `  @override`,
+    `  bool operator ==(Object other) => other is ${d.name}Unknown && _voJsonEq(other.raw, raw);`,
+    `  @override`,
+    `  int get hashCode => _voJsonHash(raw);`,
+    `}`,
+  ].join("\n");
+
+  return [base, ...armClasses, unknown].join("\n\n");
+}
+
 function emitValueObjectClass(d: ValueObjectDescriptor): string {
+  if (d.union !== undefined) return emitUnionClasses(d);
   if (d.geometry !== undefined) {
     const coordsType = geometryCoordsDart[d.geometry]!;
     const coordsFrom: Record<string, string> = {
@@ -1401,12 +1573,21 @@ function emitValueObjectClass(d: ValueObjectDescriptor): string {
       `}`,
     ].join("\n");
   }
-  const fields = Object.entries(d.fields ?? {}).map(([wireName, f]) => ({
+  const allFields = Object.entries(d.fields ?? {}).map(([wireName, f]) => ({
     wireName,
     member: dartMemberName(wireName),
     f,
     optional: f.optional === true,
   }));
+  // `z.literal(...)` members are CONSTANTS: a getter (never a ctor param), always serialized.
+  const literals = allFields.filter((x) => x.f.type === "literal");
+  const fields = allFields.filter((x) => x.f.type !== "literal");
+  const literalGetters = literals.map(
+    (x) => `  String get ${x.member} => '${(x.f as { value: string }).value}';`,
+  );
+  const literalToLines = literals.map(
+    (x) => `        '${x.wireName}': '${(x.f as { value: string }).value}',`,
+  );
   const decls = fields.map(
     (x) => `  final ${dartTypeOfVoField(x.f, d.name, x.wireName)}${x.optional ? "?" : ""} ${x.member};`,
   );
@@ -1428,10 +1609,9 @@ function emitValueObjectClass(d: ValueObjectDescriptor): string {
     `/// zod \`.optional()\` contract — absent, never JSON null).`,
     `class ${d.name} {`,
     ...decls,
+    ...literalGetters,
     ``,
-    `  const ${d.name}({`,
-    ...ctor,
-    `  });`,
+    ...(fields.length === 0 ? [`  const ${d.name}();`] : [`  const ${d.name}({`, ...ctor, `  });`]),
     ``,
     `  /// Read from the projection's decoded json object.`,
     `  factory ${d.name}.fromProjected(Map<String, Object?> m) {`,
@@ -1442,6 +1622,7 @@ function emitValueObjectClass(d: ValueObjectDescriptor): string {
     ``,
     `  /// The authored payload shape (embed it in a directive payload / \`set()\`).`,
     `  Map<String, Object?> toJson() => <String, Object?>{`,
+    ...literalToLines,
     ...toLines,
     `      };`,
     ``,
@@ -1908,6 +2089,12 @@ export function toJsonExpr(spec: PayloadFieldSpec, accessor: string): string {
       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`;
   }
 }
 
@@ -2942,19 +3129,58 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   const skipValueObjectNames = opts.skipValueObjectNames ?? new Set<string>();
   // VALUE OBJECTS: one generated class per named VO the module carries (composeDomainModule
   // collected + sorted them), minus the package-shared ones (emitted once in the framework file).
-  const localValueObjects = (mod.valueObjects ?? []).filter((d) => !skipValueObjectNames.has(d.name));
+  // Payload-only VOs (a VO used in a directive payload but on no aggregate field) still need
+  // their generated class — collected from the branded payload schemas, deduped by name against
+  // 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]
+    .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 —
   // so skipping a shared VO (the framework-file dedup) skips its enums with it.
-  const voBlock =
-    localValueObjects.length > 0
+  // UNIT extension types (dart_codegen_parity.md P2): every `unit("X", z.number())` tag seen
+  // in local VO descriptors OR directive payloads gets ONE zero-cost wrapper. Opaque by design —
+  // no generated arithmetic/conversions (a physics library is not a type system).
+  const unitNames = new Set<string>();
+  const walkUnitField = (f: ValueObjectFieldDescriptor): void => {
+    if (f.type === "number" && f.unit !== undefined) unitNames.add(f.unit);
+    else if (f.type === "array") walkUnitField(f.items);
+  };
+  for (const d of localValueObjects) {
+    for (const f of Object.values(d.fields ?? {})) walkUnitField(f);
+    for (const arm of Object.values(d.union ?? {})) {
+      if ("fields" in arm) for (const f of Object.values(arm.fields)) walkUnitField(f);
+    }
+  }
+  for (const dir of mod.directives ?? []) {
+    const schema = (dir as { payloadSchema?: unknown }).payloadSchema;
+    if (schema && typeof schema === "object" && zodTypeName(schema as z.ZodTypeAny) === "ZodObject") {
+      try {
+        for (const spec of introspectPayload(schema as z.ZodTypeAny, new Map())) {
+          if (spec.toJson === "wrapped" && !spec.dartType.endsWith("Id")) unitNames.add(spec.dartType);
+        }
+      } catch { /* an unsupported payload shape is reported by the payload emitter, not here */ }
+    }
+  }
+  const unitBlock = [...unitNames].sort().map((u) => [
+    `/// UNIT \`${u}\` — a ZERO-COST wrapper over the wire's plain JSON number (Dart extension`,
+    `/// type): passing a bare double (or another unit) where [${u}] is required is a COMPILE`,
+    `/// error. Opaque tag only — no arithmetic/conversions are generated.`,
+    `extension type const ${u}(double value) {}`,
+  ].join("\n")).join("\n\n");
+  const voBlock = [
+    ...(unitBlock !== "" ? [unitBlock] : []),
+    ...(localValueObjects.length > 0
       ? [
           emitVoHelpers(),
           ...localValueObjects.flatMap((d) => [
-            ...voEnumFields(d).map((e) => emitVoEnum(d.name, e.fieldName, e.values)),
+            ...voEnumFields(d).map((e) => emitVoEnum(e.owner ?? d.name, e.fieldName, e.values)),
             emitValueObjectClass(d),
           ]),
-        ].join("\n\n")
-      : "";
+        ]
+      : []),
+  ].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));
   const localDirectives = mod.directives.filter((d) => !skipDirectiveIds.has(d.id));

package/src/codegen_proof.ts

@@ -44,6 +44,7 @@ import type { FieldOp } from "./ops.js";
 import type { RelationTypeDecl, Rewrite } from "./relation_schema.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import { finishCount } from "./count.js";
+import { voMetaOf, voSample } from "./value_object.js";
 import { mintedCreateField } from "./workspace_routing.js";
 import { deterministicPorts } from "./ctx.js";
 import { __setDispatchDomain } from "./framework/relations.js";
@@ -98,6 +99,12 @@ function sampleString(zt: z.ZodTypeAny, field: string): string {
 
 /** One sample value for one zod shape. NO FALLBACK: an unhandled shape throws, naming its remedy. */
 function sampleOfZod(zt: z.ZodTypeAny, field: string, where: string): unknown {
+  // 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) — the raw-zod walk below cannot see constraints like geo's min-2
+  // coordinates and would synthesize a value the law itself refuses.
+  const vo = voMetaOf(zt);
+  if (vo !== undefined) return voSample(vo);
   switch (zodKind(zt)) {
     case "string":
       return sampleString(zt, field);

package/src/codegen_provider_dart.ts

@@ -171,6 +171,22 @@ function obligationFromJsonExpr(s: PayloadFieldSpec): string {
       // a list. The Dart type drives the cast.
       return s.optional ? `${raw} as ${s.dartType}?` : `${raw} as ${s.dartType}`;
     }
+    case "vo": {
+      // A declared value object — decode through the generated class (typed both ways).
+      return s.optional
+        ? `${raw} == null ? null : ${s.dartType}.fromProjected((${raw} as Map).cast<String, Object?>())`
+        : `${s.dartType}.fromProjected((${raw} as Map).cast<String, Object?>())`;
+    }
+    case "voList": {
+      const elem = s.dartType.replace(/^List<(.*)>$/, "$1");
+      const decode = `(${raw} as List).map((e) => ${elem}.fromProjected((e as Map).cast<String, Object?>())).toList()`;
+      return s.optional ? `${raw} == null ? null : ${decode}` : decode;
+    }
+    case "wrapped": {
+      // typed-id class (String wire) or unit extension type (num wire): wrap the raw scalar.
+      const wrap = (v: string) => `${s.dartType}${s.dartType.endsWith("Id") ? `.fromRow(${v} as String)` : `((${v} as num).toDouble())`}`;
+      return s.optional ? `${raw} == null ? null : ${wrap(raw)}` : wrap(raw);
+    }
   }
 }
 

package/src/codegen_ts.ts

@@ -41,6 +41,7 @@ import type { Field, ValueObjectDescriptor, ValueObjectFieldDescriptor } from ".
 import type { Directive } from "./directive.js";
 import type { DomainModule } from "./codegen_dart.js";
 import type { QueryDecl } from "./query.js";
+import { voMetaOf, collectPayloadValueObjectDescriptors } from "./value_object.js";
 import { finishCount } from "./count.js";
 import { finishSum } from "./sum.js";
 import type { DerivedDecl } from "./derived.js";
@@ -122,6 +123,14 @@ 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 {
+  // 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/
+  // default wrappers must keep flowing through the switch so `| undefined` survives.
+  if (zodKind(zt) === "object" || zodKind(zt) === "union") {
+    const vo = voMetaOf(zt);
+    if (vo !== undefined) return vo.name;
+  }
   switch (zodKind(zt)) {
     case "string":
       return "string";
@@ -282,11 +291,13 @@ function tsTypeOfVoField(f: ValueObjectFieldDescriptor): string {
     case "string":
       return "string";
     case "number":
-      return "number";
+      return "number"; // `.int()`/units are Dart-side nominal products; TS keeps one number
     case "boolean":
       return "boolean";
     case "enum":
       return union(f.values.map((v) => JSON.stringify(v)));
+    case "literal":
+      return JSON.stringify(f.value);
     case "array":
       return `${paren(tsTypeOfVoField(f.items))}[]`;
     case "object":
@@ -305,6 +316,25 @@ function emitValueObjectTs(d: ValueObjectDescriptor): string[] {
       ``,
     ];
   }
+  if (d.union !== undefined) {
+    // A union(...) sum type: the named TS union of its arms. An anonymous arm's fields ride
+    // inline beside the `type` discriminator; a NAMED-VO arm nests under `value` (the named
+    // VO stays the one nominal home of its shape — dart_codegen_parity.md P1).
+    const arms = Object.entries(d.union).map(([key, arm]) => {
+      if ("ref" in arm) return `{ type: ${JSON.stringify(key)}; value: ${arm.ref} }`;
+      const fields = Object.entries(arm.fields)
+        .map(([n, f]) => `${n}${f.optional === true ? "?" : ""}: ${tsTypeOfVoField(f)}`)
+        .join("; ");
+      return fields.length > 0 ? `{ type: ${JSON.stringify(key)}; ${fields} }` : `{ type: ${JSON.stringify(key)} }`;
+    });
+    return [
+      `/** Union \`${d.name}\` — a sum type stored as ONE json leaf (wholesale-replace; the \`type\``,
+      ` *  discriminator names the arm). Adding an arm is ADDITIVE evolution; removing one is a retype. */`,
+      `export type ${d.name} =`,
+      ...arms.map((a, i) => `  | ${a}${i === arms.length - 1 ? ";" : ""}`),
+      ``,
+    ];
+  }
   const lines = Object.entries(d.fields ?? {}).map(
     ([name, f]) => `  ${name}${f.optional === true ? "?" : ""}: ${tsTypeOfVoField(f)};`,
   );
@@ -476,7 +506,11 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   // ── value objects: one interface per named VO, deduped across the package's domains ──
   const voByName = new Map<string, ValueObjectDescriptor>();
   for (const mod of modules) {
-    for (const d of (mod as { valueObjects?: readonly ValueObjectDescriptor[] }).valueObjects ?? []) {
+    // aggregate-carried VOs ∪ payload-only VOs (branded schemas) — both need their interface.
+    const payloadVos = collectPayloadValueObjectDescriptors(
+      ((mod as { directives?: readonly { payloadSchema?: unknown }[] }).directives ?? []),
+    );
+    for (const d of [...((mod as { valueObjects?: readonly ValueObjectDescriptor[] }).valueObjects ?? []), ...payloadVos]) {
       const existing = voByName.get(d.name);
       if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(d)) {
         throw new Error(

package/src/fields.ts

@@ -89,15 +89,28 @@ export type GeometryKind = "Point" | "LineString" | "Polygon";
  */
 export type ValueObjectFieldDescriptor =
   | { readonly type: "string"; readonly optional?: true }
-  | { readonly type: "number"; readonly optional?: true }
+  /** `int: true` when the zod carried `.int()` (Dart `int`, TS `number`); `unit` when the field
+   * was declared through `unit(...)` — the generated Dart extension-type wrapper's name. */
+  | { readonly type: "number"; readonly int?: true; readonly unit?: string; readonly optional?: true }
   | { readonly type: "boolean"; readonly optional?: true }
   | { readonly type: "enum"; readonly values: readonly string[]; readonly optional?: true }
+  /** A `z.literal(<string>)` — a CONSTANT discriminator-style member (generated as a getter). */
+  | { readonly type: "literal"; readonly value: string; readonly optional?: true }
   | { readonly type: "array"; readonly items: ValueObjectFieldDescriptor; readonly optional?: true }
   /** A nested value object, referenced BY NAME (its own descriptor rides alongside). */
   | { readonly type: "object"; readonly ref: string; readonly optional?: true }
   /** A nested GEO value object (RFC 7946 geometry), referenced by name. */
   | { readonly type: "geometry"; readonly ref: string; readonly geometry: GeometryKind; readonly optional?: true };
 
+/**
+ * One arm of a `union(...)` value object: either an ANONYMOUS shape (fields ride inline,
+ * flattened beside the `type` discriminator on the wire) or a NAMED value object (the arm
+ * nests it under `value` on the wire — the named VO stays the one nominal home of its shape).
+ */
+export type UnionArmDescriptor =
+  | { readonly fields: Readonly<Record<string, ValueObjectFieldDescriptor>> }
+  | { readonly ref: string };
+
 /**
  * The canonical descriptor of ONE named value object. A structural VO carries
  * `fields` (keys SORTED — byte-determinism); a `geo.*` VO carries `geometry`
@@ -107,6 +120,9 @@ export interface ValueObjectDescriptor {
   readonly name: string;
   readonly fields?: Readonly<Record<string, ValueObjectFieldDescriptor>>;
   readonly geometry?: GeometryKind;
+  /** A `union(...)` sum type: arm key (the wire `type` discriminator value) → arm descriptor.
+   * Mutually exclusive with `fields`/`geometry`. Keys SORTED (byte-determinism). */
+  readonly union?: Readonly<Record<string, UnionArmDescriptor>>;
 }
 
 /**
@@ -126,6 +142,9 @@ export interface ValueObjectFieldMeta {
   readonly dependencies: readonly ValueObjectDescriptor[];
   /** Present iff this VO is a `geo.*` geometry (the spatial-index pairing check). */
   readonly geometry?: GeometryKind;
+  /** The author-supplied lawful example (validated against the VO's own zod at declaration).
+   * Proof synthesis + docs prefer it over per-field synthesis. */
+  readonly example?: unknown;
 }
 
 export interface Field<T = unknown, K extends FieldKind = FieldKind> {

package/src/index.ts

@@ -47,6 +47,13 @@ export {
 // `geo.*` are the RFC 7946 geometry VOs (pair `geo.point()` with `spatial(...)`).
 export {
   valueObject,
+  variant,
+  unit,
+  idOf,
+  idOfMetaOf,
+  voMetaOf,
+  voSample,
+  NOMOS_VO_BRAND,
   geo,
   type ValueObject,
   type ValueObjectValue,

package/src/shape_compat.ts

@@ -80,6 +80,14 @@ function payloadFieldKind(spec: PayloadFieldSpec): string {
       return "set";
     case "json":
       return "json";
+    case "wrapped":
+      // typed-id (string wire) or unit (number wire) — the interface sees the WIRE kind.
+      return spec.dartType.endsWith("Id") ? "string" : "double";
+    case "vo":
+    case "voList":
+      // Interface kinds stay at the base lane for now (slice D of vo_authoring_end_to_end.md
+      // upgrades these to a first-class "vo" kind) — a VO IS a json leaf structurally.
+      return "json";
     case "scalar":
     default:
       switch (spec.dartType) {

package/src/value_object.ts

@@ -56,6 +56,7 @@ import {
   valueObjectField,
   type Field,
   type GeometryKind,
+  type UnionArmDescriptor,
   type ValueObjectDescriptor,
   type ValueObjectFieldDescriptor,
   type ValueObjectFieldMeta,
@@ -186,6 +187,74 @@ function collectDescriptors(vo: ValueObject<unknown>, into: Map<string, ValueObj
   }
 }
 
+/** `.int()` detection across zod v4's check encodings (mirrors codegen_dart's payload rule). */
+function zodNumberIsInt(zt: z.ZodTypeAny): boolean {
+  const def = zodDef(zt) as { checks?: readonly unknown[]; format?: string };
+  if (def.format === "safeint" || def.format === "int32" || def.format === "int64") return true;
+  for (const c of def.checks ?? []) {
+    const chk = c as { kind?: string; def?: { check?: string; format?: string } };
+    if (chk.kind === "int") return true;
+    if (chk.def?.check === "number_format" && (chk.def.format === "safeint" || chk.def.format === "int32")) return true;
+  }
+  return false;
+}
+
+/**
+ * THE UNIT BRAND (dart_codegen_parity.md P2) — `unit("Millimetres", z.number())` stamps the
+ * schema so the descriptor carries the unit name and the generated Dart wraps the field in a
+ * ZERO-COST extension type (`Millimetres`). Compile-time only: the wire value stays a plain
+ * JSON number; validation is untouched; domainHash-inert. v1 = opaque tags — NO generated
+ * arithmetic or conversions (a physics library is not a type system).
+ */
+export const NOMOS_UNIT_BRAND: unique symbol = Symbol.for("nomos.unit");
+
+const UNIT_NAME_RE = /^[A-Z][A-Za-z0-9_]*$/;
+
+/** Tag a numeric field with a UNIT: `radiusMm: unit("Millimetres", z.number())`. */
+export function unit<Z extends z.ZodTypeAny>(name: string, inner: Z): Z {
+  if (!UNIT_NAME_RE.test(name)) {
+    throw new Error(`unit: '${name}' must be a capitalized identifier — it becomes the generated extension type's name.`);
+  }
+  if (zodKind(inner) !== "number") {
+    throw new Error(`unit '${name}': only z.number() fields carry a unit in v1.`);
+  }
+  Object.defineProperty(inner, NOMOS_UNIT_BRAND, { value: name, enumerable: false });
+  return inner;
+}
+
+/**
+ * THE TYPED-ID BRAND (dart_codegen_parity.md P2) — `idOf(Site)` in a directive payload is
+ * wire-identical to `z.string()` but the generated Dart field is the aggregate's TYPED id
+ * class (`SiteId`), and the generated TS references the branded alias. Passing another
+ * aggregate's id where a SiteId belongs becomes a COMPILE error. Payload-side only — the
+ * kernel keeps seeing a string; validation/domainHash untouched.
+ */
+export const NOMOS_IDOF_BRAND: unique symbol = Symbol.for("nomos.idOf");
+
+/** A payload field holding an EXISTING aggregate's id, typed: `siteId: idOf(Site)`. */
+export function idOf(aggregate: { id: string } | string): z.ZodType<string> {
+  const aggregateType = typeof aggregate === "string" ? aggregate : aggregate.id;
+  if (typeof aggregateType !== "string" || aggregateType === "") {
+    throw new Error("idOf: pass the aggregate handle (idOf(Site)) or its type name.");
+  }
+  const schema = z.string().min(1);
+  Object.defineProperty(schema, NOMOS_IDOF_BRAND, { value: aggregateType, enumerable: false });
+  return schema;
+}
+
+/** Resolve the `idOf(...)` aggregate type of a payload schema (through optional/default). */
+export function idOfMetaOf(zt: z.ZodTypeAny): string | undefined {
+  let cur: z.ZodTypeAny | undefined = zt;
+  for (let hops = 0; cur !== undefined && hops < 16; hops++) {
+    const branded = (cur as unknown as Record<symbol, unknown>)[NOMOS_IDOF_BRAND];
+    if (typeof branded === "string") return branded;
+    const kind = zodKind(cur);
+    if (kind !== "optional" && kind !== "default" && kind !== "nullable") return undefined;
+    cur = zodDef(cur).innerType;
+  }
+  return undefined;
+}
+
 /**
  * Describe one CONSTRAINED zod schema as a descriptor field (NO FALLBACK — an
  * out-of-set shape throws with the field's path so the author fixes the declaration,
@@ -195,12 +264,26 @@ function describeZod(voName: string, path: string, schema: z.ZodTypeAny): ValueO
   switch (zodKind(schema)) {
     case "string":
       return { type: "string" };
-    case "number":
-      return { type: "number" };
+    case "number": {
+      const unitName = (schema as unknown as Record<symbol, unknown>)[NOMOS_UNIT_BRAND];
+      return {
+        type: "number",
+        ...(zodNumberIsInt(schema) ? { int: true as const } : {}),
+        ...(typeof unitName === "string" ? { unit: unitName } : {}),
+      };
+    }
     case "boolean":
       return { type: "boolean" };
     case "enum":
       return { type: "enum", values: zodEnumValues(schema) };
+    case "literal": {
+      const def = zodDef(schema) as { value?: unknown; values?: readonly unknown[] };
+      const v = def.value ?? def.values?.[0];
+      if (typeof v !== "string") {
+        throw new Error(`valueObject '${voName}': field '${path}' — only STRING literals are in the v1 set.`);
+      }
+      return { type: "literal", value: v };
+    }
     case "array": {
       const items = describeZod(voName, `${path}[]`, zodArrayElement(schema));
       if (items.optional === true) {
@@ -226,12 +309,109 @@ function describeZod(voName: string, path: string, schema: z.ZodTypeAny): ValueO
 
 const VO_NAME_RE = /^[A-Za-z][A-Za-z0-9_]*$/;
 
+/**
+ * THE VO BRAND (slice A of vo_authoring_end_to_end.md) — `valueObject()` stamps its zod schema
+ * with the VO's {@link ValueObjectFieldMeta} under this symbol, COMPILE-TIME ONLY: the brand is
+ * a non-enumerable property, never serialized, never read by the engine's validation path, so a
+ * branded schema's package bytes (and domainHash) are byte-identical to an unbranded one.
+ * Every generated-surface introspector (Dart/TS payload gen, interface kinds, proof synthesis)
+ * consults {@link voMetaOf} BEFORE its raw zod-kind switch — the VO keeps its NAME on every
+ * surface instead of degrading to an anonymous json object.
+ */
+export const NOMOS_VO_BRAND: unique symbol = Symbol.for("nomos.vo");
+
+/**
+ * Resolve the value-object identity of a zod schema, unwrapping `.optional()` / `.default()`
+ * wrappers (the brand lives on the VO's own object schema). `undefined` for anything that is
+ * not a declared VO — callers then fall through to their raw-zod lane, so non-VO behaviour is
+ * untouched.
+ */
+export function voMetaOf(zt: z.ZodTypeAny): ValueObjectFieldMeta | undefined {
+  let cur: z.ZodTypeAny | undefined = zt;
+  for (let hops = 0; cur !== undefined && hops < 16; hops++) {
+    const branded = (cur as unknown as Record<symbol, unknown>)[NOMOS_VO_BRAND];
+    if (branded !== undefined) return branded as ValueObjectFieldMeta;
+    const kind = zodKind(cur);
+    if (kind !== "optional" && kind !== "default" && kind !== "nullable") return undefined;
+    cur = zodDef(cur).innerType;
+  }
+  return undefined;
+}
+
+/** The blessed lawful sample per RFC 7946 geometry kind (proof synthesis + docs). */
+const GEOMETRY_SAMPLES: Record<GeometryKind, unknown> = {
+  Point: { type: "Point", coordinates: [0, 0] },
+  LineString: { type: "LineString", coordinates: [[0, 0], [1, 1]] },
+  Polygon: { type: "Polygon", coordinates: [[[0, 0], [0, 1], [1, 1], [0, 0]]] },
+};
+
+function sampleOfDescriptorField(
+  f: ValueObjectFieldDescriptor,
+  fieldName: string,
+  byName: Map<string, ValueObjectDescriptor>,
+): unknown {
+  switch (f.type) {
+    case "string": return `sample-${fieldName}`;
+    case "number": return 1;
+    case "literal": return f.value;
+    case "boolean": return true;
+    case "enum": return f.values[0];
+    case "array": return [sampleOfDescriptorField(f.items, fieldName, byName)];
+    case "geometry": return GEOMETRY_SAMPLES[f.geometry];
+    case "object": {
+      const dep = byName.get(f.ref);
+      if (dep === undefined) throw new Error(`voSample: nested value object '${f.ref}' has no descriptor`);
+      return sampleOfDescriptor(dep, byName);
+    }
+  }
+}
+
+function sampleOfDescriptor(d: ValueObjectDescriptor, byName: Map<string, ValueObjectDescriptor>): unknown {
+  if (d.geometry !== undefined) return GEOMETRY_SAMPLES[d.geometry];
+  if (d.union !== undefined) {
+    // FIRST declared arm (keys are sorted — deterministic); `example:` overrides upstream.
+    const [key, arm] = Object.entries(d.union)[0]!;
+    if ("ref" in arm) {
+      const dep = byName.get(arm.ref);
+      if (dep === undefined) throw new Error(`voSample: union arm VO '${arm.ref}' has no descriptor`);
+      return { type: key, value: sampleOfDescriptor(dep, byName) };
+    }
+    const out: Record<string, unknown> = { type: key };
+    for (const [k, f] of Object.entries(arm.fields)) {
+      if (f.optional === true) continue;
+      out[k] = sampleOfDescriptorField(f, k, byName);
+    }
+    return out;
+  }
+  const out: Record<string, unknown> = {};
+  for (const [k, f] of Object.entries(d.fields ?? {})) {
+    if (f.optional === true) continue; // optional → omitted (mirrors payload synthesis)
+    out[k] = sampleOfDescriptorField(f, k, byName);
+  }
+  return out;
+}
+
+/**
+ * A LAWFUL sample value for a VO (slice C): the author's validated `example` when given, the
+ * blessed geometry sample for `geo.*` kinds, else per-field synthesis (recursing into nested
+ * VOs). Proof synthesis calls this instead of guessing at the raw zod — which is exactly the
+ * lane that refused its own sample on constrained shapes (geo min-2 coordinates).
+ */
+export function voSample(meta: ValueObjectFieldMeta): unknown {
+  if (meta.example !== undefined) return meta.example;
+  const byName = new Map<string, ValueObjectDescriptor>();
+  for (const d of meta.dependencies) byName.set(d.name, d);
+  byName.set(meta.descriptor.name, meta.descriptor);
+  return sampleOfDescriptor(meta.descriptor, byName);
+}
+
 function makeValueObject<T>(
   name: string,
   zodSchema: z.ZodType<T>,
   descriptor: ValueObjectDescriptor,
   dependencies: readonly ValueObjectDescriptor[],
   geometry?: GeometryKind,
+  example?: T,
 ): ValueObject<T> {
   if (!VO_NAME_RE.test(name)) {
     throw new Error(
@@ -239,12 +419,25 @@ function makeValueObject<T>(
         `generated TS interface / Dart class name.`,
     );
   }
+  if (example !== undefined) {
+    const v = zodSchema.safeParse(example);
+    if (!v.success) {
+      throw new Error(
+        `valueObject '${name}': the declared example does not satisfy the VO's own schema — ` +
+          `a lying example would poison proof synthesis. ${v.error.message}`,
+      );
+    }
+  }
   const meta: ValueObjectFieldMeta = {
     name,
     descriptor,
     dependencies,
     ...(geometry !== undefined ? { geometry } : {}),
+    ...(example !== undefined ? { example } : {}),
   };
+  // THE BRAND (slice A): compile-time identity on the schema itself — non-enumerable, never
+  // serialized, domainHash-inert. voMetaOf() is the one resolver every introspector uses.
+  Object.defineProperty(zodSchema, NOMOS_VO_BRAND, { value: meta, enumerable: false });
   const vo: ValueObject<T> = {
     __isValueObject: true,
     name,
@@ -272,6 +465,13 @@ function makeValueObject<T>(
 export function valueObject<const Name extends string, S extends Record<string, ValueObjectShapeEntry>>(
   name: Name,
   shape: S,
+  opts?: {
+    /** A lawful example value, VALIDATED against the VO's own schema at declaration (a lying
+     * example throws here, loudly). Proof synthesis prefers it over per-field synthesis — the
+     * escape hatch for constraint-rich shapes (refinements, cross-field rules) a synthesizer
+     * cannot guess. */
+    example?: ShapeValue<S>;
+  },
 ): ValueObject<ShapeValue<S>> {
   const zodShape: Record<string, z.ZodTypeAny> = {};
   const fields: Record<string, ValueObjectFieldDescriptor> = {};
@@ -308,9 +508,98 @@ export function valueObject<const Name extends string, S extends Record<string,
     z.object(zodShape) as unknown as z.ZodType<ShapeValue<S>>,
     descriptor,
     dependencies,
+    undefined,
+    opts?.example,
   );
 }
 
+// ── variant(...) — sum types as ONE json leaf (dart_codegen_parity.md P1; named `variant`
+// because the ReBAC rewrite set-op already owns `union`) ──────────────
+
+/** One arm of a `variant(...)`: an anonymous shape (the v1 VO field set) or a NAMED value object. */
+export type UnionArmShape = Record<string, ValueObjectShapeEntry> | ValueObject<unknown>;
+
+type UnionArmValue<A> = A extends ValueObject<infer V>
+  ? { value: V }
+  : A extends Record<string, ValueObjectShapeEntry>
+    ? ShapeValue<A>
+    : never;
+
+type UnionValue<Arms extends Record<string, UnionArmShape>> = {
+  [K in keyof Arms & string]: { type: K } & UnionArmValue<Arms[K]>;
+}[keyof Arms & string];
+
+/**
+ * Declare a NAMED SUM TYPE (`variant("Shape", { circle: {...}, rect: {...} })`). The blessed,
+ * FIXED discriminator is `type` (the geo/RFC 7946 convention); its value is the arm key.
+ * On the wire an ANONYMOUS arm's fields ride flattened beside `type`; a NAMED-VO arm nests
+ * its value under `value` (the named VO stays the one nominal home of its shape).
+ *
+ * STORAGE/MERGE: identical to every VO — ONE Lww-class json leaf, replaced WHOLESALE
+ * (switching arms is just a write; no per-arm merge). EVOLUTION: adding an arm is ADDITIVE
+ * (the generated Dart's `Unknown` arm keeps OLD clients decoding a NEWER law's arm without
+ * crashing); removing/renaming an arm is a retype (the #58 dispositions lane).
+ */
+export function variant<const Name extends string, Arms extends Record<string, UnionArmShape>>(
+  name: Name,
+  arms: Arms,
+  opts?: { example?: UnionValue<Arms> },
+): ValueObject<UnionValue<Arms>> {
+  const armKeys = Object.keys(arms).sort();
+  if (armKeys.length === 0) throw new Error(`variant '${name}': at least one arm is required.`);
+  const deps = new Map<string, ValueObjectDescriptor>();
+  const armDescriptors: Record<string, UnionArmDescriptor> = {};
+  const armZods: z.ZodTypeAny[] = [];
+  for (const key of armKeys) {
+    if (!VO_NAME_RE.test(key) || key !== key[0]!.toLowerCase() + key.slice(1)) {
+      throw new Error(`variant '${name}': arm key '${key}' must be a lowerCamel identifier — it is the wire discriminator AND names the generated arm class.`);
+    }
+    const arm = arms[key]!;
+    if (isValueObject(arm)) {
+      if (arm.descriptor.union !== undefined) {
+        throw new Error(`variant '${name}': arm '${key}' is itself a union — unions-of-unions are refused in v1.`);
+      }
+      armDescriptors[key] = { ref: arm.name };
+      armZods.push(z.object({ type: z.literal(key), value: arm.zod as z.ZodTypeAny }));
+      collectDescriptors(arm, deps);
+    } else {
+      const fields: Record<string, ValueObjectFieldDescriptor> = {};
+      const zodShape: Record<string, z.ZodTypeAny> = { type: z.literal(key) };
+      for (const fieldKey of Object.keys(arm).sort()) {
+        if (fieldKey === "type") throw new Error(`variant '${name}': arm '${key}' declares a 'type' field — reserved for the discriminator.`);
+        if (fieldKey === "value") throw new Error(`variant '${name}': arm '${key}' declares a 'value' field — reserved for named-VO arms.`);
+        const entry = arm[fieldKey]!;
+        if (isOptionalValueObject(entry)) {
+          const inner = entry.valueObject;
+          zodShape[fieldKey] = (inner.zod as z.ZodTypeAny).optional();
+          fields[fieldKey] = inner.geometry !== undefined
+            ? { type: "geometry", ref: inner.name, geometry: inner.geometry, optional: true }
+            : { type: "object", ref: inner.name, optional: true };
+          collectDescriptors(inner, deps);
+        } else if (isValueObject(entry)) {
+          zodShape[fieldKey] = entry.zod as z.ZodTypeAny;
+          fields[fieldKey] = entry.geometry !== undefined
+            ? { type: "geometry", ref: entry.name, geometry: entry.geometry }
+            : { type: "object", ref: entry.name };
+          collectDescriptors(entry, deps);
+        } else {
+          fields[fieldKey] = describeZod(name, `${key}.${fieldKey}`, entry);
+          zodShape[fieldKey] = entry;
+        }
+      }
+      armDescriptors[key] = { fields };
+      armZods.push(z.object(zodShape));
+    }
+  }
+  if (deps.has(name)) throw new Error(`variant '${name}': a union cannot nest itself (directly or via a dependency).`);
+  const descriptor: ValueObjectDescriptor = { name, union: armDescriptors };
+  const dependencies = [...deps.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  const zodSchema = (armZods.length === 1
+    ? armZods[0]!
+    : z.discriminatedUnion("type", armZods as [z.ZodObject<z.ZodRawShape>, ...z.ZodObject<z.ZodRawShape>[]])) as unknown as z.ZodType<UnionValue<Arms>>;
+  return makeValueObject(name, zodSchema, descriptor, dependencies, undefined, opts?.example);
+}
+
 // ── geo.* — the RFC 7946 geometry value objects ──────────────────────────────────────
 
 /** An RFC 7946 position: `[lng, lat]` or `[lng, lat, altitude]`. */
@@ -388,6 +677,46 @@ export const geo = {
  * descriptors throw (one name, one shape). Returns `[]` when no field carries a VO —
  * the omit-when-empty input to the `nomosValueObjects` era key.
  */
+/**
+ * Collect the value objects referenced by DIRECTIVE PAYLOADS (top-level fields + array
+ * elements), via the {@link NOMOS_VO_BRAND} the schemas carry. CODEGEN-ONLY (slice B of
+ * vo_authoring_end_to_end.md): the result feeds the generated Dart/TS surfaces so a
+ * payload-only VO still gets its class/interface — it does NOT enter the `nomosValueObjects`
+ * IR key (that stays aggregate-derived, keeping package bytes / domainHash untouched).
+ */
+export function collectPayloadValueObjectDescriptors(
+  directives: readonly { payloadSchema?: unknown }[],
+): ValueObjectDescriptor[] {
+  const byName = new Map<string, ValueObjectDescriptor>();
+  const take = (meta: ValueObjectFieldMeta | undefined) => {
+    if (meta === undefined) return;
+    for (const d of [meta.descriptor, ...meta.dependencies]) {
+      const existing = byName.get(d.name);
+      if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(d)) {
+        throw new Error(`value object '${d.name}' has DIVERGENT shapes across payloads — one name, one shape.`);
+      }
+      byName.set(d.name, d);
+    }
+  };
+  for (const dir of directives) {
+    const schema = dir?.payloadSchema as z.ZodTypeAny | undefined;
+    if (!schema || typeof schema !== "object" || zodKind(schema) !== "object") continue;
+    const rawShape = (zodDef(schema) as { shape?: Record<string, z.ZodTypeAny> | (() => Record<string, z.ZodTypeAny>) }).shape
+      ?? (schema as unknown as { shape?: Record<string, z.ZodTypeAny> }).shape;
+    const shape = typeof rawShape === "function" ? rawShape() : rawShape ?? {};
+    for (const raw of Object.values(shape)) {
+      let zt = raw as z.ZodTypeAny;
+      take(voMetaOf(zt));
+      // unwrap optional/default to reach an array of VOs
+      for (let hops = 0; hops < 8 && (zodKind(zt) === "optional" || zodKind(zt) === "default"); hops++) {
+        zt = zodDef(zt).innerType!;
+      }
+      if (zodKind(zt) === "array") take(voMetaOf(zodArrayElement(zt)));
+    }
+  }
+  return [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
 export function collectValueObjectDescriptors(
   aggregates: readonly { id: string; fields: Record<string, Field> }[],
 ): ValueObjectDescriptor[] {