@githolon/dsl 0.39.0 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.39.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,7 +29,7 @@
  * generated, so they stay reproducible from the domain definitions.
  */
 import { z } from "zod";
-import { voMetaOf, collectPayloadValueObjectDescriptors } from "./value_object.js";
+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";
@@ -63,7 +63,8 @@ export type ToJsonWrap =
   | "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()`.
+  | "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;
@@ -239,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
@@ -250,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",
@@ -1261,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 {
@@ -1278,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":
@@ -1308,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": {
@@ -1324,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
@@ -1380,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> = {
@@ -1416,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};`,
   );
@@ -1443,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) {`,
@@ -1457,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,
     `      };`,
     ``,
@@ -1927,6 +2093,8 @@ export function toJsonExpr(spec: PayloadFieldSpec, accessor: string): string {
       return `${accessor}.toJson()`;
     case "voList":
       return `${accessor}.map((e) => e.toJson()).toList()`;
+    case "wrapped":
+      return `${accessor}.value`;
   }
 }
 
@@ -2971,16 +3139,48 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
     .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_provider_dart.ts

@@ -182,6 +182,11 @@ function obligationFromJsonExpr(s: PayloadFieldSpec): string {
       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

@@ -127,7 +127,7 @@ function tsTypeOfZod(zt: z.ZodTypeAny, indent: string): string {
   // 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") {
+  if (zodKind(zt) === "object" || zodKind(zt) === "union") {
     const vo = voMetaOf(zt);
     if (vo !== undefined) return vo.name;
   }
@@ -291,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":
@@ -314,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)};`,
   );

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>>;
 }
 
 /**

package/src/index.ts

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

package/src/shape_compat.ts

@@ -80,6 +80,9 @@ 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

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) {
@@ -270,6 +353,7 @@ function sampleOfDescriptorField(
   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)];
@@ -284,6 +368,21 @@ function sampleOfDescriptorField(
 
 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)
@@ -414,6 +513,93 @@ export function valueObject<const Name extends string, S extends Record<string,
   );
 }
 
+// ── 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]`. */