@githolon/dsl 0.32.0 → 0.33.0

package/src/codegen_dart.ts

@@ -32,7 +32,7 @@ import { z } from "zod";
 import type { AggregateHandle } from "./aggregate.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import type { RelationTypeDecl } from "./relation_schema.js";
-import type { Field, FieldKind } from "./fields.js";
+import type { Field, FieldKind, ValueObjectDescriptor, ValueObjectFieldDescriptor } from "./fields.js";
 import type { Directive } from "./directive.js";
 import { executeDirectiveToIntent } from "./wire_encode.js";
 import { deterministicPorts } from "./ctx.js";
@@ -347,6 +347,13 @@ interface AggFieldSpec {
    * `undefined` for a non-map field.
    */
   mapValueKind?: FieldKind;
+  /**
+   * For a `json`-kind field lowered from a NAMED VALUE OBJECT (`ValueObject.field()`):
+   * the generated Dart class name. The field decodes via `readJsonObject…` +
+   * `<VoClass>.fromProjected(m)` (the EvidenceRef pattern) and types as the class.
+   * `undefined` for a plain `t.json()`/`t.jsonObject()` field.
+   */
+  voClass?: string;
   /**
    * For a `json`-kind field: the asserted decoded SHAPE (`field.jsonShape`). `"object"`
    * (a `t.jsonObject()` leaf, e.g. `location`) means the value is ALWAYS a JSON object —
@@ -581,8 +588,21 @@ function aggFieldSpec(
         ...(valueClass !== undefined ? { valueClass } : {}),
       };
     case "json":
+      // A NAMED VALUE OBJECT (`ValueObject.field()`) types as its generated Dart class
+      // (typed decode via `.fromProjected`, the EvidenceRef pattern). Otherwise
       // `jsonShape` ("object" via `t.jsonObject()`) chooses strict-object vs
       // permissive read-model type.
+      if (field.valueObject !== undefined) {
+        return {
+          name,
+          wireName,
+          kind: field.kind,
+          dartType: field.valueObject.name,
+          optional,
+          voClass: field.valueObject.name,
+          ...(field.jsonShape !== undefined ? { jsonShape: field.jsonShape } : {}),
+        };
+      }
       return {
         name,
         wireName,
@@ -1166,6 +1186,275 @@ function emitEvidenceRefClass(): string {
   ].join("\n");
 }
 
+// ── value objects → Dart classes (`value_object.ts` descriptors) ─────────────────────
+
+/** The Dart coordinates type per RFC 7946 geometry kind. */
+const geometryCoordsDart: Record<string, string> = {
+  Point: "List<double>",
+  LineString: "List<List<double>>",
+  Polygon: "List<List<List<double>>>",
+};
+
+/**
+ * The generated Dart enum NAME for one VO enum field: `<VoName><FieldName>Enum`
+ * (e.g. `PostalAddressCountryCodeEnum`). The VO is the field's semantic home — the
+ * exact analogue of the aggregate-enum convention's domain prefix (`collectEnums`'s
+ * `<Domain><Field>Enum`), so two barrel-exported domains never collide on a bare name.
+ * IDENTITY = THE VO FIELD, not the value set: two identical value-sets in DIFFERENT
+ * VOs stay separate types (VO names are package-unique, so so are these).
+ */
+function voEnumName(voName: string, fieldName: string): string {
+  return `${voName}${dartTypeNameFromField(fieldName)}Enum`;
+}
+
+/** The tolerant-decode SENTINEL case name — dodge a literal enum value that would
+ * collide with it (`dartIdent("unknownWire") === "unknownWire"`). */
+function voEnumSentinel(values: readonly string[]): string {
+  let s = "unknownWire";
+  while (values.some((v) => dartIdent(v) === s)) s = `${s}_`;
+  return s;
+}
+
+/** Emit ONE generated Dart enum for a VO enum field. TOLERANT DECODE (law evolves —
+ * a new value added by a later law must NOT crash an old client): `fromWire` maps an
+ * unrecognized wire string to the [sentinel] case instead of throwing (the deliberate
+ * divergence from the strict aggregate-enum `fromWire`; VO data crosses law versions). */
+function emitVoEnum(voName: string, fieldName: string, values: readonly string[]): string {
+  const name = voEnumName(voName, fieldName);
+  const sentinel = voEnumSentinel(values);
+  const variants = values.map((v) => `  ${dartIdent(v)}('${v}')`).join(",\n");
+  return [
+    `/// Generated enum for value object field '${voName}.${fieldName}': ${values.join(", ")}.`,
+    `/// TOLERANT DECODE: an unrecognized wire value (law can add enum values; old`,
+    `/// clients must not crash on new data) decodes to [${name}.${sentinel}] — never a throw.`,
+    `/// [wire] is the exact wire string ([${sentinel}].wire is the '__unknown__' marker;`,
+    `/// authoring code constructs KNOWN cases, so toJson never writes it in practice).`,
+    `enum ${name} {`,
+    `${variants},`,
+    `  /// The tolerant-decode sentinel — an enum value this client's law snapshot does not know.`,
+    `  ${sentinel}('__unknown__');`,
+    ``,
+    `  final String wire;`,
+    `  const ${name}(this.wire);`,
+    ``,
+    `  static ${name} fromWire(String wire) =>`,
+    `      ${name}.values.firstWhere((e) => e.wire == wire,`,
+    `          orElse: () => ${name}.${sentinel});`,
+    `}`,
+  ].join("\n");
+}
+
+/** 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);
+  };
+  for (const [fieldName, f] of Object.entries(d.fields ?? {})) walk(fieldName, f);
+  return out;
+}
+
+/** 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 {
+  switch (f.type) {
+    case "string":
+      return "String";
+    case "number":
+      return "double";
+    case "boolean":
+      return "bool";
+    case "enum":
+      // A REAL generated Dart enum (`emitVoEnum`), named by the owning VO field.
+      return voEnumName(voName, fieldName);
+    case "array":
+      return `List<${dartTypeOfVoField(f.items, voName, fieldName)}>`;
+    case "object":
+    case "geometry":
+      return f.ref; // the named VO class (emitted alongside / imported)
+  }
+}
+
+/** A Dart expression converting the RAW decoded json value `expr` to the field's typed
+ * value. `depth` names nested lambda vars (`e0`, `e1`, …) for arrays-of-arrays. */
+function voFromExpr(
+  f: ValueObjectFieldDescriptor,
+  expr: string,
+  voName: string,
+  fieldName: string,
+  depth = 0,
+): string {
+  switch (f.type) {
+    case "string":
+      return `${expr} as String`;
+    case "enum":
+      // 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()`;
+    case "boolean":
+      return `${expr} as bool`;
+    case "array": {
+      const v = `e${depth}`;
+      return `(${expr} as List).map((${v}) => ${voFromExpr(f.items, v, voName, fieldName, depth + 1)}).toList()`;
+    }
+    case "object":
+    case "geometry":
+      return `${f.ref}.fromProjected((${expr} as Map).cast<String, Object?>())`;
+  }
+}
+
+/** 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":
+    case "boolean":
+      return expr;
+    case "enum":
+      return `${expr}.wire`; // the exact wire string the law's zod enum validates
+    case "array": {
+      const inner = voToJsonExpr(f.items, `e${depth}`, depth + 1);
+      return inner === `e${depth}` ? expr : `${expr}.map((e${depth}) => ${inner}).toList()`;
+    }
+    case "object":
+    case "geometry":
+      return `${expr}.toJson()`;
+  }
+}
+
+/** 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 {
+  return [
+    `/// Deep json equality for generated value-object classes (toJson-based).`,
+    `bool _voJsonEq(Object? a, Object? b) {`,
+    `  if (a is Map && b is Map) {`,
+    `    if (a.length != b.length) return false;`,
+    `    for (final k in a.keys) {`,
+    `      if (!b.containsKey(k) || !_voJsonEq(a[k], b[k])) return false;`,
+    `    }`,
+    `    return true;`,
+    `  }`,
+    `  if (a is List && b is List) {`,
+    `    if (a.length != b.length) return false;`,
+    `    for (var i = 0; i < a.length; i++) {`,
+    `      if (!_voJsonEq(a[i], b[i])) return false;`,
+    `    }`,
+    `    return true;`,
+    `  }`,
+    `  return a == b;`,
+    `}`,
+    ``,
+    `/// Deep json hash for generated value-object classes (toJson-based).`,
+    `int _voJsonHash(Object? v) {`,
+    `  if (v is Map) {`,
+    `    return Object.hashAllUnordered(`,
+    `        v.entries.map((e) => Object.hash(e.key, _voJsonHash(e.value))));`,
+    `  }`,
+    `  if (v is List) return Object.hashAll(v.map(_voJsonHash));`,
+    `  return v.hashCode;`,
+    `}`,
+  ].join("\n");
+}
+
+/** Emit ONE generated Dart value-object class from its canonical descriptor: typed
+ * final fields, a const ctor, `fromProjected` (the projection's decoded json object),
+ * `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). */
+function emitValueObjectClass(d: ValueObjectDescriptor): string {
+  if (d.geometry !== undefined) {
+    const coordsType = geometryCoordsDart[d.geometry]!;
+    const coordsFrom: Record<string, string> = {
+      Point: `(m['coordinates']! as List).map((e0) => (e0 as num).toDouble()).toList()`,
+      LineString: `(m['coordinates']! as List).map((e0) => (e0 as List).map((e1) => (e1 as num).toDouble()).toList()).toList()`,
+      Polygon: `(m['coordinates']! as List).map((e0) => (e0 as List).map((e1) => (e1 as List).map((e2) => (e2 as num).toDouble()).toList()).toList()).toList()`,
+    };
+    return [
+      `/// RFC 7946 ${d.geometry} — a \`geo.*\` value object ('${d.name}'). Positions are`,
+      `/// \`[lng, lat]\` or \`[lng, lat, altitude]\` (RFC 7946 order).`,
+      `class ${d.name} {`,
+      `  final ${coordsType} coordinates;`,
+      ``,
+      `  const ${d.name}({required this.coordinates});`,
+      ``,
+      `  /// The RFC 7946 geometry kind (constant).`,
+      `  String get type => '${d.geometry}';`,
+      ``,
+      `  factory ${d.name}.fromProjected(Map<String, Object?> m) =>`,
+      `      ${d.name}(coordinates: ${coordsFrom[d.geometry]!});`,
+      ``,
+      `  Map<String, Object?> toJson() => <String, Object?>{`,
+      `        'type': '${d.geometry}',`,
+      `        'coordinates': coordinates,`,
+      `      };`,
+      ``,
+      `  @override`,
+      `  bool operator ==(Object other) =>`,
+      `      other is ${d.name} && _voJsonEq(other.toJson(), toJson());`,
+      ``,
+      `  @override`,
+      `  int get hashCode => _voJsonHash(toJson());`,
+      `}`,
+    ].join("\n");
+  }
+  const fields = Object.entries(d.fields ?? {}).map(([wireName, f]) => ({
+    wireName,
+    member: dartMemberName(wireName),
+    f,
+    optional: f.optional === true,
+  }));
+  const decls = fields.map(
+    (x) => `  final ${dartTypeOfVoField(x.f, d.name, x.wireName)}${x.optional ? "?" : ""} ${x.member};`,
+  );
+  const ctor = 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}']!`, d.name, x.wireName)},`
+      : `      ${x.member}: ${voFromExpr(x.f, `m['${x.wireName}']!`, d.name, 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 [
+    `/// Generated value object '${d.name}' (value_object.ts). Stored as ONE json-object`,
+    `/// value leaf on its aggregate field — replaced WHOLESALE on write (Lww-class; no`,
+    `/// per-subfield merge). Optional members are OMITTED from [toJson] when null (the`,
+    `/// zod \`.optional()\` contract — absent, never JSON null).`,
+    `class ${d.name} {`,
+    ...decls,
+    ``,
+    `  const ${d.name}({`,
+    ...ctor,
+    `  });`,
+    ``,
+    `  /// Read from the projection's decoded json object.`,
+    `  factory ${d.name}.fromProjected(Map<String, Object?> m) {`,
+    `    return ${d.name}(`,
+    ...fromLines,
+    `    );`,
+    `  }`,
+    ``,
+    `  /// The authored payload shape (embed it in a directive payload / \`set()\`).`,
+    `  Map<String, Object?> toJson() => <String, Object?>{`,
+    ...toLines,
+    `      };`,
+    ``,
+    `  @override`,
+    `  bool operator ==(Object other) =>`,
+    `      other is ${d.name} && _voJsonEq(other.toJson(), toJson());`,
+    ``,
+    `  @override`,
+    `  int get hashCode => _voJsonHash(toJson());`,
+    `}`,
+  ].join("\n");
+}
+
 /** True when ANY aggregate field in the module is `t.evidence()` — gates emitting the
  * shared [emitEvidenceRefClass] once. */
 function moduleUsesEvidence(aggregates: readonly AggregateHandle[]): boolean {
@@ -1235,8 +1524,15 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
         ? `readStrOrNull(data, '${s.wireName}')`
         : `readStr(data, '${aggregate}', '${s.wireName}')`;
     case "json":
-      // A `json`-kind field is typed `String` on the aggregate; the projection may
-      // have parsed its stored JSON into a container — re-stringify to keep `String`.
+      // A NAMED VALUE OBJECT reads the projection's decoded object and wraps it in its
+      // generated class (the EvidenceRef pattern). A plain `json`-kind field is typed
+      // `String` on the aggregate; the projection may have parsed its stored JSON into a
+      // container — re-stringify to keep `String`.
+      if (s.voClass !== undefined) {
+        return opt
+          ? `() { final m = readJsonObjectOrNull(data, '${aggregate}', '${s.wireName}'); return m == null ? null : ${s.voClass}.fromProjected(m); }()`
+          : `${s.voClass}.fromProjected(readJsonObject(data, '${aggregate}', '${s.wireName}'))`;
+      }
       return opt
         ? `readJsonStrOrNull(data, '${s.wireName}')`
         : `readJsonStr(data, '${aggregate}', '${s.wireName}')`;
@@ -1304,6 +1600,8 @@ function readModelDartType(s: AggFieldSpec): string {
       // has an UNKNOWN/non-object decoded shape (a double/bool/list authored as a JSON
       // leaf — the kernel `Value` is Str|Int only), so it is surfaced as the permissive
       // `Object?` (the read engine's decoded value as-is — never coerced/thrown).
+      // A NAMED VALUE OBJECT reads as its generated class (typed decode).
+      if (s.voClass !== undefined) return s.voClass;
       return isJsonObjectLeaf(s) ? "Map<String, Object?>" : "Object?";
     // `position`/`counter` are normalized to `string`/`int` in `aggFieldSpec` (read-collapsed scalars),
     // so these labels are unreachable at runtime — present for FieldKind exhaustiveness.
@@ -1380,6 +1678,12 @@ function parseReadModelField(s: AggFieldSpec, aggregate: string): string {
       // shape (a double/bool/list authored as a JSON leaf), so surface the read engine's
       // decoded value AS-IS via the NON-THROWING `readJsonValueOrNull` (`Object?`, null
       // when absent) — NEVER a strict-object reader that would throw on a legit non-object.
+      if (s.voClass !== undefined) {
+        // A NAMED VALUE OBJECT: the decoded object wrapped in its generated class.
+        return opt
+          ? `() { final m = readJsonObjectOrNull(data, '${aggregate}', '${s.wireName}'); return m == null ? null : ${s.voClass}.fromProjected(m); }()`
+          : `${s.voClass}.fromProjected(readJsonObject(data, '${aggregate}', '${s.wireName}'))`;
+      }
       if (isPermissiveJsonLeaf(s)) {
         return `readJsonValueOrNull(data, '${s.wireName}')`;
       }
@@ -2489,6 +2793,16 @@ export interface DomainModule {
    * AST is hashed; the recursive Check/Expand EVALUATOR is the Rust engine substrate, never authored.
    */
   relationTypes?: RelationTypeDecl[];
+  /**
+   * The domain's FIRST-CLASS VALUE OBJECTS (`value_object.ts`) — the deduped, sorted
+   * canonical descriptors of every named VO the aggregates carry (transitive nested VOs
+   * included; collected by `composeDomainModule`). ADDITIVE + OPTIONAL: a VO-free domain
+   * omits this entirely (the `nomosValueObjects` era rule — package bytes unchanged).
+   * NEVER in the canonical manifest/domainHash: a VO field's manifest bytes equal a plain
+   * `t.jsonObject()` field's. Drives the generated TS interfaces + Dart classes and the
+   * additive `nomosValueObjects` USD key (`usd.ts`).
+   */
+  valueObjects?: readonly ValueObjectDescriptor[];
   /**
    * The domain's FIRST-CLASS WORKSPACE TYPES (`workspace_type.ts`; sharding §10
    * RATIFIED, slice 1) — the law-declared workspace taxonomy
@@ -2598,6 +2912,13 @@ export interface GenerateDartDomainOptions {
    * `import` so skipped framework symbols resolve. Omit when nothing is skipped.
    */
   readonly frameworkImportUri?: string;
+  /**
+   * VALUE OBJECT names whose generated Dart class is emitted ONCE per package in the shared
+   * `nomos_framework.dart` (a VO used by ≥2 domains) and MUST NOT be re-emitted here — this
+   * domain references them via {@link frameworkImportUri}. Empty/absent ⇒ emit every VO the
+   * module carries locally.
+   */
+  readonly skipValueObjectNames?: ReadonlySet<string>;
 }
 
 /** Generate the full Dart source for one domain module. */
@@ -2606,6 +2927,22 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   const skipAggregateIds = opts.skipAggregateIds ?? new Set<string>();
   const skipDirectiveIds = opts.skipDirectiveIds ?? new Set<string>();
   const skipQueryIds = opts.skipQueryIds ?? new Set<string>();
+  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));
+  // 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
+      ? [
+          emitVoHelpers(),
+          ...localValueObjects.flatMap((d) => [
+            ...voEnumFields(d).map((e) => emitVoEnum(d.name, e.fieldName, e.values)),
+            emitValueObjectClass(d),
+          ]),
+        ].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));
@@ -2841,6 +3178,13 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
           ``,
         ]
       : []),
+    ...(voBlock !== ""
+      ? [
+          `// ---- value objects (named composable json-object leaves; value_object.ts) ----`,
+          voBlock,
+          ``,
+        ]
+      : []),
     `// ---- aggregates (projection types) ----`,
     aggBlock,
     ``,

package/src/codegen_ts.ts

@@ -37,7 +37,7 @@
 import type { z } from "zod";
 
 import type { AggregateHandle } from "./aggregate.js";
-import type { Field } from "./fields.js";
+import type { Field, ValueObjectDescriptor, ValueObjectFieldDescriptor } from "./fields.js";
 import type { Directive } from "./directive.js";
 import type { DomainModule } from "./codegen_dart.js";
 import type { QueryDecl } from "./query.js";
@@ -249,6 +249,9 @@ function tsTypeOfField(field: Field): string {
     case "ref":
       return "string"; // the related aggregate's id
     case "json":
+      // A NAMED VALUE OBJECT field reads as its generated interface (`value_object.ts`);
+      // a bare `t.jsonObject()` stays the anonymous object; a plain `t.json()` is unknown.
+      if (field.valueObject !== undefined) return field.valueObject.name;
       return field.jsonShape === "object" ? "Record<string, unknown>" : "unknown";
     case "set":
       return "string[]"; // `t.set(t.string())` is the one set shape (fields.ts)
@@ -264,6 +267,56 @@ function tsTypeOfField(field: Field): string {
   }
 }
 
+// ── value objects → TS interfaces (`value_object.ts` descriptors) ─────────────────
+
+/** The coordinates TS type per RFC 7946 geometry kind. */
+const geometryCoordsTs: Record<string, string> = {
+  Point: "number[]",
+  LineString: "number[][]",
+  Polygon: "number[][][]",
+};
+
+/** One descriptor field → its TS type text. NO FALLBACK (the descriptor set is closed). */
+function tsTypeOfVoField(f: ValueObjectFieldDescriptor): string {
+  switch (f.type) {
+    case "string":
+      return "string";
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "enum":
+      return union(f.values.map((v) => JSON.stringify(v)));
+    case "array":
+      return `${paren(tsTypeOfVoField(f.items))}[]`;
+    case "object":
+    case "geometry":
+      return f.ref; // the named VO interface (emitted alongside)
+  }
+}
+
+/** Emit one `export interface <VO> { ... }` from its canonical descriptor. A geo VO
+ *  emits the fixed RFC 7946 shape (`{ type: "<kind>"; coordinates: ... }`). */
+function emitValueObjectTs(d: ValueObjectDescriptor): string[] {
+  if (d.geometry !== undefined) {
+    return [
+      `/** RFC 7946 ${d.geometry} — a \`geo.${d.geometry === "Point" ? "point" : d.geometry === "LineString" ? "lineString" : "polygon"}(...)\` value object. */`,
+      `export interface ${d.name} { type: ${JSON.stringify(d.geometry)}; coordinates: ${geometryCoordsTs[d.geometry]}; }`,
+      ``,
+    ];
+  }
+  const lines = Object.entries(d.fields ?? {}).map(
+    ([name, f]) => `  ${name}${f.optional === true ? "?" : ""}: ${tsTypeOfVoField(f)};`,
+  );
+  return [
+    `/** Value object \`${d.name}\` — ONE json-object value leaf, replaced WHOLESALE on write (no per-subfield merge). */`,
+    `export interface ${d.name} {`,
+    ...lines,
+    `}`,
+    ``,
+  ];
+}
+
 /** A loose TS type for a derived/combined field's declared zod `returns`. */
 function tsTypeOfReturns(returns: unknown): string {
   try {
@@ -420,6 +473,26 @@ 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 ?? []) {
+      const existing = voByName.get(d.name);
+      if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(d)) {
+        throw new Error(
+          `codegen-ts: value object '${d.name}' has DIVERGENT shapes across domains — one name, one shape.`,
+        );
+      }
+      voByName.set(d.name, d);
+    }
+  }
+  if (voByName.size > 0) {
+    out.push(`// ── value objects (named, composable json-object leaves — value_object.ts) ──`, ``);
+    for (const [, d] of [...voByName].sort(([a], [b]) => a.localeCompare(b))) {
+      out.push(...emitValueObjectTs(d));
+    }
+  }
+
   out.push(`// ── read models (projection \`data\` shapes; every field is partial-fold optional) ──`, ``);
   for (const [typeId, agg] of [...aggByType].sort(([a], [b]) => a.localeCompare(b))) {
     out.push(`export interface ${typeId}Data {`);

package/src/compile_package_main.ts

@@ -422,8 +422,25 @@ function emitDart(
   const frameworkAggIds: ReadonlySet<string> = new Set(frameworkAggById.keys());
   const frameworkDirIds: ReadonlySet<string> = new Set(frameworkDirById.keys());
   const frameworkQueryIds: ReadonlySet<string> = new Set(frameworkQueryById.keys());
+  // VALUE OBJECTS shared by ≥2 domains: their generated Dart class emits ONCE in the shared
+  // `nomos_framework.dart` (the same collision rule as framework symbols — a barrel re-exporting
+  // two domains must not define one VO class twice). A single-domain VO stays in its domain file.
+  const voDomainsByName = new Map<string, number>();
+  const voDescriptorByName = new Map<string, NonNullable<DomainModule["valueObjects"]>[number]>();
+  for (const mod of modules) {
+    for (const d of mod.valueObjects ?? []) {
+      voDomainsByName.set(d.name, (voDomainsByName.get(d.name) ?? 0) + 1);
+      voDescriptorByName.set(d.name, d);
+    }
+  }
+  const sharedVoNames: ReadonlySet<string> = new Set(
+    [...voDomainsByName.entries()].filter(([, n]) => n > 1).map(([name]) => name),
+  );
+  const sharedVos = [...sharedVoNames]
+    .sort()
+    .map((name) => voDescriptorByName.get(name)!);
   const hasFrameworkSymbols =
-    frameworkAggs.length > 0 || frameworkDirs.length > 0 || frameworkQueries.length > 0;
+    frameworkAggs.length > 0 || frameworkDirs.length > 0 || frameworkQueries.length > 0 || sharedVos.length > 0;
   const FRAMEWORK_FILE = "nomos_framework";
   const frameworkImportUri = hasFrameworkSymbols ? `${FRAMEWORK_FILE}.dart` : undefined;
 
@@ -455,6 +472,8 @@ function emitDart(
       directives: frameworkDirs,
       readModelAggregates: frameworkAggs.map((a) => a.id),
       ...(frameworkQueries.length > 0 ? { queries: frameworkQueries } : {}),
+      // Package-SHARED value objects (used by ≥2 domains) — their class emits here, once.
+      ...(sharedVos.length > 0 ? { valueObjects: sharedVos } : {}),
     };
     writeGenerated(FRAMEWORK_FILE, generateDartDomain(frameworkMod));
   }
@@ -480,12 +499,17 @@ function emitDart(
     const domainFwQueryIds = new Set(
       (modForDart.queries ?? []).filter((q) => frameworkQueryIds.has(q.id)).map((q) => q.id),
     );
-    const foldsFramework = domainFwAggIds.size > 0 || domainFwDirIds.size > 0 || domainFwQueryIds.size > 0;
+    const domainSharedVoNames = new Set(
+      (modForDart.valueObjects ?? []).filter((d) => sharedVoNames.has(d.name)).map((d) => d.name),
+    );
+    const foldsFramework =
+      domainFwAggIds.size > 0 || domainFwDirIds.size > 0 || domainFwQueryIds.size > 0 || domainSharedVoNames.size > 0;
     const domainFrameworkImport = foldsFramework ? frameworkImportUri : undefined;
     const src = generateDartDomain(modForDart, {
       skipAggregateIds: domainFwAggIds,
       skipDirectiveIds: domainFwDirIds,
       skipQueryIds: domainFwQueryIds,
+      skipValueObjectNames: domainSharedVoNames,
       ...(domainFrameworkImport !== undefined ? { frameworkImportUri: domainFrameworkImport } : {}),
     });
     writeGenerated(mod.name, src);