@githolon/dsl 0.32.0 → 0.34.0

package/src/build_package.ts

@@ -54,8 +54,15 @@ import type { ImpureCapabilityDecl } from "./codegen_provider_dart.js";
 import type { WorkspaceTypeDecl } from "./workspace_type.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import { synthesizePreconditionInvariants } from "./precondition.js";
+import {
+  BIRTH_METER_AGGREGATES,
+  BIRTH_METER_QUERIES,
+  synthesizeBirthQuotaInvariants,
+} from "./birth_meter.js";
+import { withBirthMeterExports } from "./birth_meter_ensure.js";
 import type { RelationTypeDecl } from "./relation_schema.js";
 import { domainHash, emitManifestBytes } from "./manifest.js";
+import { collectValueObjectDescriptors } from "./value_object.js";
 import { emitUsd } from "./usd.js";
 import { expandCapabilityExports } from "./capability_exports.js";
 import { RelationTuple } from "./framework/relations.js";
@@ -145,6 +152,11 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   // `capability()` bundles expand into discoverable entries (the package plane's
   // merge point) — the quartet validation below then passes without re-exports.
   merged = expandCapabilityExports(merged);
+  // METERED BIRTH: inject the sanctioning `nomosBirthRecordEnsure` directive + meter aggregates
+  // into a `.births()`-declaring domain at the SAME seam the engine merge applies it — the
+  // Ensure→NomosBirthRecord manifest declaration is what admits the auto-appended record through
+  // the id-mint gate's declared-ensures lane. Birth-free domains are byte-identical (era rule).
+  merged = withBirthMeterExports(merged);
 
   const byId = new Map<string, AggregateHandle>();
   for (const a of [...aggregatesOf(merged), ...(spec.extraAggregates ?? [])]) byId.set(a.id, a);
@@ -157,6 +169,18 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   if (!byId.has(RelationTuple.id) && directives.some((d) => d.aggregateId === RelationTuple.id)) {
     byId.set(RelationTuple.id, RelationTuple);
   }
+  // BIRTH-METER AUTO-ENSURE (metered birth, slice A — the same "discoverable without re-exports"
+  // courtesy as RelationTuple): a domain declaring ≥1 `.births()` directive gets the meter aggregates
+  // (NomosBirthRecord/BirthPolicy/BirthGrant) injected so the auto-record folds + projects, and the
+  // meter queries injected so the captured reads route/re-derive. Era-safe: only a birth-declaring
+  // domain gains them, so no existing (birth-free) manifest hash drifts — and a birth-declaring domain
+  // recompiled under this DSL moves hash ANYWAY (the meter IS its new era).
+  const declaresBirth = directives.some((d) => (d as { birthsChild?: boolean }).birthsChild === true);
+  if (declaresBirth) {
+    for (const a of BIRTH_METER_AGGREGATES) {
+      if (!byId.has(a.id)) byId.set(a.id, a);
+    }
+  }
   const aggregates = [...byId.values()];
   const directiveIds = new Set(directives.map((d) => d.id));
   for (const task of spec.impureCapabilities ?? []) {
@@ -187,7 +211,39 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   // hand-authored `workspaceInvariant(...)` occupies — so downstream treats them identically. Era-safe:
   // a directive with no precondition synthesizes nothing (byte-identical manifest).
   for (const d of directives) workspaceInvariants.push(...synthesizePreconditionInvariants(d));
+  // METERED BIRTH (slice A2): synthesize THE BIRTH-QUOTA invariant for every `.births()` directive —
+  // the same desugaring lane as preconditions, so the manifest (`nomosInvariantGate`) and the sealed
+  // engine (which synthesizes from the SAME directives in `buildDomainSlice`) can never disagree.
+  for (const d of directives) workspaceInvariants.push(...synthesizeBirthQuotaInvariants(d));
+  // The meter's declared queries route like any exported query (read manifest + captured-read re-derive).
+  if (declaresBirth) {
+    const haveQuery = new Set(queries.map((q) => q.id));
+    for (const q of BIRTH_METER_QUERIES) {
+      if (!haveQuery.has(q.id)) queries.push(q);
+    }
+  }
   const relationTypes = [...(spec.relationTypes ?? [])];
+  // FIRST-CLASS VALUE OBJECTS (value_object.ts): the deduped, sorted descriptors of every
+  // named VO the domain's aggregates carry (transitive nested VOs included) — the input to
+  // the additive `nomosValueObjects` USD key. Omit-when-empty (era rule): a VO-free domain's
+  // module — and thus its USD/package bytes — is byte-identical to before VOs existed.
+  const valueObjects = collectValueObjectDescriptors(aggregates);
+  // SPATIAL × VO PAIRING (fail at build, not at fold): a spatial index over a VO-typed field
+  // must index a GEO value object (an RFC 7946 geometry — the R*Tree's bbox source). A
+  // structural VO (e.g. a PostalAddress) has no geometry to index. Non-VO fields (a
+  // hand-rolled `t.jsonObject()` GeoJSON leaf) pass through unchecked, exactly as before.
+  for (const s of spatials) {
+    const agg = byId.get(s.of);
+    const field = agg?.fields[s.on];
+    const vo = field?.valueObject;
+    if (vo !== undefined && vo.geometry === undefined) {
+      throw new Error(
+        `build-package: spatial '${s.id}' indexes '${s.of}.${s.on}', a '${vo.name}' value object with NO ` +
+          `geometry — the R*Tree needs an RFC 7946 geometry leaf. Give the geometry its OWN field ` +
+          `(e.g. \`point: geo.point().field()\`) and index that (v1: no sub-path indexing).`,
+      );
+    }
+  }
   const dartImports = [...(spec.dartImports ?? [])];
   // THE PEER-SOVEREIGN ROOT-OF-TRUST: a home/child law that exports `requireParentAttestedBirth` declares
   // it requires a parent-attested-birth cert chain. Discovered by shape across the module list (the SAME
@@ -233,6 +289,9 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
     // Omit-when-empty — the relation schema is hashed law (P1); a relation-free domain's
     // canonical manifest/USD stays byte-identical (the nomosRelations era rule).
     ...(relationTypes.length > 0 ? { relationTypes } : {}),
+    // Omit-when-empty — the `nomosValueObjects` era rule: a VO-free domain's USD/package
+    // bytes are byte-identical to before value objects existed.
+    ...(valueObjects.length > 0 ? { valueObjects } : {}),
     // THE PEER-SOVEREIGN ROOT-OF-TRUST: omit-when-false — a law that doesn't require parent-attested
     // birth is byte-identical in the canonical manifest/USD (the nomosParentAttestedBirth era rule).
     ...(parentAttestedBirth ? { parentAttestedBirth } : {}),

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_engine.ts

@@ -41,6 +41,7 @@
  * re-baking is a later, gated step. SYNTHETIC framework units only.
  */
 import type { Directive } from "./directive.js";
+import { isNamespacedAggregate, READ_PROJECTION_DELIMITER } from "./read_projection_namespace.js";
 import type { AggregateHandle, AggregateInvariantFn } from "./aggregate.js";
 import type { ComposeOptions } from "./compose.js";
 import { flattenUsd, usdHash, type UsdDocument, type UsdPrim } from "./usd.js";
@@ -274,7 +275,17 @@ export function compileEngineModule(
           `id "${directiveId}".`,
       );
     }
-    if (binding.directive.aggregateId !== prim.target) {
+    // READ-PROJECTION NAMESPACING: the USD law's target is the QUALIFIED type name for a
+    // non-global aggregate (`<domain>__<handleId>`); the executable binding keeps the bare
+    // handle id (the source literal). Accept either the bare id (global / pre-namespacing law)
+    // or the domain-qualified form (the prim's own layer domain — the 2nd path segment).
+    const aggGlobal = (binding.agg as { global?: boolean }).global;
+    const targetMatches = (aggId: string): boolean =>
+      prim.target === aggId ||
+      (isNamespacedAggregate(aggGlobal === undefined ? { id: aggId } : { id: aggId, global: aggGlobal }) &&
+        prim.target.endsWith(`${READ_PROJECTION_DELIMITER}${aggId}`) &&
+        prim.target.length > READ_PROJECTION_DELIMITER.length + aggId.length);
+    if (!targetMatches(binding.directive.aggregateId)) {
       throw new EngineCompileError(
         "binding-mismatch",
         directiveId,
@@ -282,7 +293,7 @@ export function compileEngineModule(
           `USD law's target is "${prim.target}".`,
       );
     }
-    if (binding.agg.id !== prim.target) {
+    if (!targetMatches(binding.agg.id)) {
       throw new EngineCompileError(
         "binding-mismatch",
         directiveId,