@githolon/dsl 0.32.0 → 0.33.0

package/src/fields.ts

@@ -72,6 +72,62 @@ export const evidenceRefSchema: z.ZodType<EvidenceRefValue> = z.object({
   storageClass: z.enum(["git", "external"]),
 });
 
+// ── VALUE OBJECTS (composable value objects — `value_object.ts`) ─────────────────────
+// The descriptor types live HERE (dependency-free) so `Field` can carry the metadata
+// without a `fields.ts → value_object.ts` cycle; `value_object.ts` re-exports them.
+
+/** The RFC 7946 geometry kinds a `geo.*` value object can declare (Point is the
+ *  spatial-index-blessed one; see `spatial.ts`). */
+export type GeometryKind = "Point" | "LineString" | "Polygon";
+
+/**
+ * One field of a value-object DESCRIPTOR — the canonical, JSON-schema-ish shape that
+ * rides the package IR (`nomosValueObjects`) and drives TS/Dart codegen. `optional`
+ * is PRESENT only when true (omit-when-false — descriptor bytes are deterministic).
+ * `array.items` is a nested descriptor WITHOUT `optional` (an array of optionals is
+ * not expressible — the v1 constrained set).
+ */
+export type ValueObjectFieldDescriptor =
+  | { readonly type: "string"; readonly optional?: true }
+  | { readonly type: "number"; readonly optional?: true }
+  | { readonly type: "boolean"; readonly optional?: true }
+  | { readonly type: "enum"; readonly values: readonly 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 };
+
+/**
+ * The canonical descriptor of ONE named value object. A structural VO carries
+ * `fields` (keys SORTED — byte-determinism); a `geo.*` VO carries `geometry`
+ * instead (its shape is fixed by RFC 7946, not authored).
+ */
+export interface ValueObjectDescriptor {
+  readonly name: string;
+  readonly fields?: Readonly<Record<string, ValueObjectFieldDescriptor>>;
+  readonly geometry?: GeometryKind;
+}
+
+/**
+ * The value-object metadata a VO-typed `Field` carries (`ValueObject.field()` sets it).
+ * FRONTEND/IR-ONLY: it never enters the kernel wire `Schema` (driver-only — see
+ * `encodeKernelSchema`) nor the canonical manifest, so a VO field's domainHash is
+ * IDENTICAL to a hand-rolled `t.jsonObject()` field. The additive `nomosValueObjects`
+ * USD key (built by `composeDomainModule`/`usd.ts` FROM this metadata) is what makes
+ * the structure visible to tooling.
+ */
+export interface ValueObjectFieldMeta {
+  /** The VO's declared name (the generated TS interface / Dart class name). */
+  readonly name: string;
+  /** This VO's own canonical descriptor. */
+  readonly descriptor: ValueObjectDescriptor;
+  /** Every TRANSITIVELY nested VO's descriptor (self excluded), sorted by name. */
+  readonly dependencies: readonly ValueObjectDescriptor[];
+  /** Present iff this VO is a `geo.*` geometry (the spatial-index pairing check). */
+  readonly geometry?: GeometryKind;
+}
+
 export interface Field<T = unknown, K extends FieldKind = FieldKind> {
   /** The kind tag. `K` is the LITERAL kind so the query DSL can constrain `.ref`
    * to ONLY `kind:'ref'` fields at compile time (`t.ref` → `Field<string,'ref'>`).
@@ -113,6 +169,15 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
    * `encodeKernelSchema`) — so it changes NO hash (identical to `mapValueKind`/`isOptional`).
    */
   readonly jsonShape?: "object";
+  /**
+   * For a `json`-kind field lowered from a NAMED VALUE OBJECT (`ValueObject.field()`):
+   * the VO metadata (name + canonical descriptor + nested-VO dependencies). Drives the
+   * generated TS interface / Dart class and the additive `nomosValueObjects` USD key.
+   * FRONTEND/IR-ONLY — never in the kernel wire `Schema` (driver-only), so the field's
+   * canonical-manifest bytes are identical to a plain `t.jsonObject()` (see
+   * {@link ValueObjectFieldMeta}). `undefined` for every non-VO field.
+   */
+  readonly valueObject?: ValueObjectFieldMeta;
   /**
    * Whether a folded aggregate may LACK this field. A SCALAR field
    * (`string`/`int`/`enum`/`ref`/`json`) that a `.creates` directive does not
@@ -184,6 +249,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     isOptional?: boolean;
     mapValueKind?: FieldKind;
     jsonShape?: "object";
+    valueObject?: ValueObjectFieldMeta;
     encrypted?: true;
     meta?: true;
     facet?: FieldFacet;
@@ -201,6 +267,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     ...(extra.viaField !== undefined ? { viaField: extra.viaField } : {}),
     ...(extra.mapValueKind !== undefined ? { mapValueKind: extra.mapValueKind } : {}),
     ...(extra.jsonShape !== undefined ? { jsonShape: extra.jsonShape } : {}),
+    ...(extra.valueObject !== undefined ? { valueObject: extra.valueObject } : {}),
     ...(extra.encrypted ? { isEncrypted: true as const } : {}),
     ...(extra.meta ? { isMeta: true as const } : {}),
     merge(d: Driver) {
@@ -401,3 +468,20 @@ function refImpl(
   }
   return makeField<string, "ref">("ref", z.string(), Conflict, { refAggregateId: a.id });
 }
+
+/**
+ * INTERNAL (`value_object.ts` — `ValueObject.field()`): construct the JSON-OBJECT value
+ * leaf a named value object lowers to. Storage/merge-identical to `t.jsonObject()`
+ * (kind `"json"`, `jsonShape:"object"`, driver Lww — the whole VO replaces WHOLESALE;
+ * per-subfield merge is what aggregates/maps are for), PLUS the {@link
+ * ValueObjectFieldMeta} that names the VO for codegen + the `nomosValueObjects` IR key.
+ * The zod is the VO's TYPED object schema, so `set(handle, field, value)` and payload
+ * embedding validate the real structure. Not part of `t.*` — reach it via
+ * `valueObject(...)`/`geo.*`'s `.field()`.
+ */
+export function valueObjectField<T>(
+  zod: z.ZodType<T>,
+  valueObject: ValueObjectFieldMeta,
+): Field<T, "json"> {
+  return makeField<T, "json">("json", zod, Lww, { jsonShape: "object", valueObject });
+}

package/src/index.ts

@@ -40,6 +40,25 @@ export {
   secretField,
   publicField,
 } from "./fields.js";
+// FIRST-CLASS COMPOSABLE VALUE OBJECTS (`value_object.ts`): named, reusable, nestable
+// structured values — ONE definition yields the zod (payload validation), the TS type,
+// the generated Dart class, and the `nomosValueObjects` IR descriptor. A VO lowers to a
+// single Lww-class json-object leaf (wholesale-replace merge — no per-subfield merge).
+// `geo.*` are the RFC 7946 geometry VOs (pair `geo.point()` with `spatial(...)`).
+export {
+  valueObject,
+  geo,
+  type ValueObject,
+  type ValueObjectValue,
+  type OptionalValueObject,
+  type ValueObjectShapeEntry,
+  type ValueObjectDescriptor,
+  type ValueObjectFieldDescriptor,
+  type GeometryKind,
+  type GeoPointValue,
+  type GeoLineStringValue,
+  type GeoPolygonValue,
+} from "./value_object.js";
 export {
   type PrincipalEvidence,
   type AttributionPrincipal,

package/src/usd.ts

@@ -464,6 +464,19 @@ export interface UsdLayer {
       readonly reason: string | null;
     }[];
   };
+  /**
+   * FIRST-CLASS VALUE OBJECTS (`value_object.ts`) — the canonical descriptors of every
+   * named value object this layer's aggregates carry (deduped, SORTED by name, nested
+   * VOs included), so tooling/visualizers SEE the structure a VO field stores. PURELY
+   * DESCRIPTIVE: the kernel reads no gate off it (a VO field folds exactly like a
+   * `t.jsonObject()` leaf — one wholesale-replace json value). OMITTED for VO-free law
+   * (byte-identical hash — the era rule); declaring a VO moves the PACKAGE hash only
+   * (the canonical manifest/domainHash is untouched — the VO is not wire law).
+   */
+  readonly nomosValueObjects?: {
+    readonly v: 1;
+    readonly valueObjects: readonly import("./fields.js").ValueObjectDescriptor[];
+  };
 }
 
 /** The reserved variant name declaring a set's DEFAULT (USD has a default variant). */
@@ -995,6 +1008,13 @@ export function emitUsd(
       // conversion's declared flow {directiveId, sink, facet, reason}. Hashed into nomosFlowGate +
       // witnessed fail-closed at runtime (Slice B). Omit-when-empty (a principal-free domain is
       // byte-identical). SORTED for determinism.
+      // FIRST-CLASS VALUE OBJECTS: the module's collected descriptors (composeDomainModule
+      // dedupes + sorts them). Omit-when-empty (era rule — VO-free law is byte-identical).
+      const moduleValueObjects = (l.module as { valueObjects?: readonly import("./fields.js").ValueObjectDescriptor[] }).valueObjects;
+      const nomosValueObjects =
+        moduleValueObjects !== undefined && moduleValueObjects.length > 0
+          ? { v: 1 as const, valueObjects: [...moduleValueObjects] }
+          : undefined;
       const flowEndorse = [...l.module.directives]
         .flatMap((d) => harvestPrincipalFlows(d as never).map((f) => ({ directiveId: d.id, sink: f.sink, facet: f.facet, reason: f.reason })))
         .sort((a, b) =>
@@ -1040,6 +1060,7 @@ export function emitUsd(
         ...(nomosBirthGate !== undefined ? { nomosBirthGate } : {}),
         ...(nomosParentAttestedBirth !== undefined ? { nomosParentAttestedBirth } : {}),
         ...(nomosVerifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll } : {}),
+        ...(nomosValueObjects !== undefined ? { nomosValueObjects } : {}),
         ...(Object.keys(visAggregates).length > 0
           ? { nomosReadVisibility: { v: 1 as const, aggregates: visAggregates } }
           : {}),

package/src/usd_layers.ts

@@ -190,6 +190,9 @@ function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string):
     ...(layer.nomosVerifiedFirstEnroll !== undefined
       ? [`${indent}custom string nomos:verifiedFirstEnrollHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosVerifiedFirstEnroll)))}`]
       : []),
+    ...(layer.nomosValueObjects !== undefined
+      ? [`${indent}custom string nomos:valueObjectsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosValueObjects)))}`]
+      : []),
   ];
 }
 
@@ -997,6 +1000,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const birthGateByDomain = new Map<string, UsdLayer["nomosBirthGate"]>();
   const parentAttestedBirthByDomain = new Map<string, UsdLayer["nomosParentAttestedBirth"]>();
   const verifiedFirstEnrollByDomain = new Map<string, UsdLayer["nomosVerifiedFirstEnroll"]>();
+  const valueObjectsByDomain = new Map<string, UsdLayer["nomosValueObjects"]>();
   for (const p of prims) {
     if (p.attrs.get("nomos:kind") === "domain") {
       const domain = attrString(p, "nomos:domain");
@@ -1068,6 +1072,11 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof vfeHex === "string") {
         verifiedFirstEnrollByDomain.set(domain, JSON.parse(unhexUtf8(vfeHex)) as UsdLayer["nomosVerifiedFirstEnroll"]);
       }
+      // FIRST-CLASS VALUE OBJECTS: the hex-carried descriptor set (descriptive, not a gate).
+      const voHex = p.attrs.get("nomos:valueObjectsHex");
+      if (typeof voHex === "string") {
+        valueObjectsByDomain.set(domain, JSON.parse(unhexUtf8(voHex)) as UsdLayer["nomosValueObjects"]);
+      }
     }
   }
 
@@ -1169,6 +1178,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const birthGate = birthGateByDomain.get(domain);
       const parentAttestedBirth = parentAttestedBirthByDomain.get(domain);
       const verifiedFirstEnroll = verifiedFirstEnrollByDomain.get(domain);
+      const valueObjects = valueObjectsByDomain.get(domain);
       return {
         path: `/Nomos/${domain}`,
         prims: [...b.prims].sort(byPath),
@@ -1189,6 +1199,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),
         ...(parentAttestedBirth !== undefined ? { nomosParentAttestedBirth: parentAttestedBirth } : {}),
         ...(verifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll: verifiedFirstEnroll } : {}),
+        ...(valueObjects !== undefined ? { nomosValueObjects: valueObjects } : {}),
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));

package/src/value_object.ts

@@ -0,0 +1,413 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * FIRST-CLASS COMPOSABLE VALUE OBJECTS — `valueObject(name, shape)` + the `geo.*`
+ * geometry VOs.
+ *
+ * THE TENANT GAP THIS CLOSES: a structured value on an aggregate was a hand-rolled
+ * `t.jsonObject()` plus a privately-kept zod schema per site — untyped in the generated
+ * clients, invisible in the package IR. A value object is the NAMED, REUSABLE,
+ * COMPOSABLE version of that same leaf:
+ *
+ *   const PostalAddress = valueObject("PostalAddress", {
+ *     streetAddress: z.string(), city: z.string(), countryCode: z.string(),
+ *   });
+ *   const GeoPoint = geo.point("GeoPoint");                    // RFC 7946 Point
+ *   const SiteLocation = valueObject("SiteLocation", {
+ *     address: PostalAddress.optional(),
+ *     point: GeoPoint.optional(),
+ *   });
+ *   // on an aggregate:
+ *   location: SiteLocation.field().optional(),
+ *
+ * ONE definition produces: the zod schema (the SAME zod the engine validates — embed
+ * `SiteLocation.zod` in a directive payload), the inferred TS type (`SiteLocation.field()`
+ * types `set()` and the generated `.client.ts` names the interface), the generated Dart
+ * class (typed decode from the projection's json-object value), and a canonical
+ * descriptor that rides the package IR (the additive `nomosValueObjects` USD key) so
+ * tooling/visualizers can SEE the structure.
+ *
+ * STORAGE / MERGE SEMANTICS (the v1 boundary — state it, don't blur it): a VO field IS
+ * the existing `t.jsonObject()` value-leaf lane — ONE Lww-class leaf, replaced WHOLESALE
+ * on write (exactly the encrypted-envelope rule). There is NO per-subfield merge: two
+ * concurrent writes to different subfields of one VO converge to ONE writer's whole
+ * value. When subfields must merge independently, model them as aggregate fields or a
+ * `t.map(...)` — that is what aggregates/maps are for.
+ *
+ * ERA SAFETY: the VO metadata never enters the kernel wire schema or the canonical
+ * manifest — a domain's domainHash with a VO field equals the same domain with a plain
+ * `t.jsonObject()` field. The `nomosValueObjects` USD key is emitted IFF a domain's
+ * aggregates carry ≥1 VO field; a VO-free domain's package bytes are untouched.
+ *
+ * THE v1 CONSTRAINED FIELD SET (no fallback — anything else throws at compile):
+ * `z.string()` · `z.number()` (int or float) · `z.boolean()` · `z.enum([...])` ·
+ * `z.array(<any of these>)` · a nested `ValueObject` · and `.optional()` on any of
+ * them (arrays of optionals excluded). Unions, records, maps, tuples, dates etc. are
+ * deliberately OUT — this surface is forever; grow it deliberately.
+ */
+import { z } from "zod";
+
+import {
+  valueObjectField,
+  type Field,
+  type GeometryKind,
+  type ValueObjectDescriptor,
+  type ValueObjectFieldDescriptor,
+  type ValueObjectFieldMeta,
+} from "./fields.js";
+// LOCAL zod introspection (the same `_def ?? def` convention as codegen_ts.ts) —
+// deliberately NOT imported from codegen_ts.js: this module rides the RUNTIME barrel
+// (the engine lump bundles it, `--platform=neutral`), and codegen_ts transitively
+// imports `node:crypto` via workspace_routing. Keep this file node-builtin-free.
+type ZodInternalDef = {
+  type?: string | z.ZodTypeAny;
+  innerType?: z.ZodTypeAny;
+  element?: z.ZodTypeAny;
+  entries?: Record<string, string | number>;
+};
+function zodDef(zt: z.ZodTypeAny): ZodInternalDef {
+  const raw = zt as unknown as { _def?: ZodInternalDef; def?: ZodInternalDef };
+  return raw._def ?? raw.def ?? {};
+}
+function zodKind(zt: z.ZodTypeAny): string {
+  const t = zodDef(zt).type;
+  return typeof t === "string" ? t : "unknown";
+}
+function zodEnumValues(zt: z.ZodTypeAny): string[] {
+  const raw = zt as unknown as { options?: readonly unknown[] };
+  if (raw.options !== undefined) return raw.options.map(String);
+  const entries = zodDef(zt).entries;
+  if (entries !== undefined) return Object.values(entries).map(String);
+  throw new Error("valueObject: ZodEnum has no values");
+}
+function zodArrayElement(zt: z.ZodTypeAny): z.ZodTypeAny {
+  const def = zodDef(zt);
+  if (def.element !== undefined) return def.element;
+  if (typeof def.type !== "string" && def.type !== undefined) return def.type;
+  throw new Error("valueObject: ZodArray has no element type");
+}
+
+export type { GeometryKind, ValueObjectDescriptor, ValueObjectFieldDescriptor } from "./fields.js";
+
+/** An `.optional()`-wrapped value object — valid ONLY inside a `valueObject(...)` shape. */
+export interface OptionalValueObject<T = unknown> {
+  readonly __isOptionalValueObject: true;
+  readonly valueObject: ValueObject<T>;
+}
+
+/**
+ * A NAMED, COMPOSABLE value object — produced by {@link valueObject} / {@link geo}.
+ * Carries the zod (validation + TS inference), the canonical descriptor (the IR/codegen
+ * shape), and lowers onto an aggregate via {@link ValueObject.field}.
+ */
+export interface ValueObject<T = unknown> {
+  readonly __isValueObject: true;
+  /** The declared name — the generated TS interface / Dart class name. */
+  readonly name: string;
+  /** The zod schema — the single source of truth (embed it in directive payloads). */
+  readonly zod: z.ZodType<T>;
+  /** This VO's own canonical descriptor (field names sorted; byte-deterministic). */
+  readonly descriptor: ValueObjectDescriptor;
+  /** Every transitively nested VO's descriptor (self excluded), sorted by name. */
+  readonly dependencies: readonly ValueObjectDescriptor[];
+  /** Present iff this is a `geo.*` geometry VO (the spatial-index pairing). */
+  readonly geometry?: GeometryKind;
+  /** Mark this VO optional INSIDE another `valueObject(...)` shape (nesting only —
+   *  for an optional aggregate FIELD use `.field().optional()`). */
+  optional(): OptionalValueObject<T>;
+  /**
+   * Lower this VO to an aggregate FIELD: one `t.jsonObject()`-class value leaf
+   * (kind `json`, `jsonShape:"object"`, Lww) whose whole value is this VO —
+   * WHOLESALE-REPLACE merge, no per-subfield merge (v1). Chain the usual field
+   * modifiers: `.merge(Lww/LwwCausal/LwwBy)` (Lww-class only — the value is replaced
+   * whole), `.optional()`, `.encrypted()` (under the existing `requires(cap)` rules).
+   */
+  field(): Field<T, "json">;
+  /** Phantom to keep T load-bearing for inference. */
+  readonly _t?: T;
+}
+
+/** Infer the authored TS type of a ValueObject. */
+export type ValueObjectValue<V> = V extends ValueObject<infer T> ? T : never;
+
+/** A `valueObject(...)` shape entry: a constrained zod schema, a nested VO, or an optional VO. */
+export type ValueObjectShapeEntry = z.ZodTypeAny | ValueObject<unknown> | OptionalValueObject<unknown>;
+
+type EntryValue<E> =
+  E extends OptionalValueObject<infer T> ? T | undefined
+  : E extends ValueObject<infer T> ? T
+  : E extends z.ZodType<infer T> ? T
+  : never;
+
+type OptionalKeys<S> = {
+  [K in keyof S]: undefined extends EntryValue<S[K]> ? K : never;
+}[keyof S];
+
+/** The inferred value type of a shape: optional entries become optional properties. */
+export type ShapeValue<S> = { [K in Exclude<keyof S, OptionalKeys<S>>]: EntryValue<S[K]> } & {
+  [K in OptionalKeys<S>]?: EntryValue<S[K]>;
+};
+
+const isValueObject = (v: unknown): v is ValueObject<unknown> =>
+  typeof v === "object" && v !== null && (v as { __isValueObject?: boolean }).__isValueObject === true;
+
+const isOptionalValueObject = (v: unknown): v is OptionalValueObject<unknown> =>
+  typeof v === "object" &&
+  v !== null &&
+  (v as { __isOptionalValueObject?: boolean }).__isOptionalValueObject === true;
+
+/** Collect a VO's descriptor + its transitive dependencies into `into` (name-keyed). */
+function collectDescriptors(vo: ValueObject<unknown>, into: Map<string, ValueObjectDescriptor>): void {
+  const existing = into.get(vo.name);
+  if (existing !== undefined) {
+    if (JSON.stringify(existing) !== JSON.stringify(vo.descriptor)) {
+      throw new Error(
+        `valueObject: two DIVERGENT value objects share the name '${vo.name}' — one name, one shape. ` +
+          `Rename one of them (the descriptor is identity-bearing).`,
+      );
+    }
+    return;
+  }
+  into.set(vo.name, vo.descriptor);
+  for (const dep of vo.dependencies) {
+    const prior = into.get(dep.name);
+    if (prior !== undefined && JSON.stringify(prior) !== JSON.stringify(dep)) {
+      throw new Error(
+        `valueObject: two DIVERGENT value objects share the name '${dep.name}' — one name, one shape. ` +
+          `Rename one of them (the descriptor is identity-bearing).`,
+      );
+    }
+    into.set(dep.name, dep);
+  }
+}
+
+/**
+ * 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,
+ * never ships an undescribed structure).
+ */
+function describeZod(voName: string, path: string, schema: z.ZodTypeAny): ValueObjectFieldDescriptor {
+  switch (zodKind(schema)) {
+    case "string":
+      return { type: "string" };
+    case "number":
+      return { type: "number" };
+    case "boolean":
+      return { type: "boolean" };
+    case "enum":
+      return { type: "enum", values: zodEnumValues(schema) };
+    case "array": {
+      const items = describeZod(voName, `${path}[]`, zodArrayElement(schema));
+      if (items.optional === true) {
+        throw new Error(
+          `valueObject '${voName}': field '${path}' is an array of optionals — not expressible in the v1 set.`,
+        );
+      }
+      return { type: "array", items };
+    }
+    case "optional":
+    case "default": {
+      const inner = describeZod(voName, path, zodDef(schema).innerType!);
+      return { ...inner, optional: true };
+    }
+    default:
+      throw new Error(
+        `valueObject '${voName}': field '${path}' uses zod shape '${zodKind(schema)}', which is outside ` +
+          `the v1 value-object field set (string | number | boolean | enum | array | nested valueObject, ` +
+          `each optionally .optional()). Model richer shapes as aggregates/maps, or nest a valueObject.`,
+      );
+  }
+}
+
+const VO_NAME_RE = /^[A-Za-z][A-Za-z0-9_]*$/;
+
+function makeValueObject<T>(
+  name: string,
+  zodSchema: z.ZodType<T>,
+  descriptor: ValueObjectDescriptor,
+  dependencies: readonly ValueObjectDescriptor[],
+  geometry?: GeometryKind,
+): ValueObject<T> {
+  if (!VO_NAME_RE.test(name)) {
+    throw new Error(
+      `valueObject: name '${name}' is not a valid identifier ([A-Za-z][A-Za-z0-9_]*) — it becomes the ` +
+        `generated TS interface / Dart class name.`,
+    );
+  }
+  const meta: ValueObjectFieldMeta = {
+    name,
+    descriptor,
+    dependencies,
+    ...(geometry !== undefined ? { geometry } : {}),
+  };
+  const vo: ValueObject<T> = {
+    __isValueObject: true,
+    name,
+    zod: zodSchema,
+    descriptor,
+    dependencies,
+    ...(geometry !== undefined ? { geometry } : {}),
+    optional(): OptionalValueObject<T> {
+      return { __isOptionalValueObject: true, valueObject: vo };
+    },
+    field(): Field<T, "json"> {
+      return valueObjectField(zodSchema, meta);
+    },
+  };
+  return vo;
+}
+
+/**
+ * Declare a NAMED, COMPOSABLE value object. `shape` entries come from the v1
+ * constrained set (see the module banner): plain zod scalars/enums/arrays, nested
+ * `ValueObject`s, or `SomeVo.optional()`. Returns a {@link ValueObject} carrying the
+ * zod schema, the inferred TS type, the canonical descriptor (+ transitive nested-VO
+ * descriptors), and `.field()` to place it on an aggregate.
+ */
+export function valueObject<const Name extends string, S extends Record<string, ValueObjectShapeEntry>>(
+  name: Name,
+  shape: S,
+): ValueObject<ShapeValue<S>> {
+  const zodShape: Record<string, z.ZodTypeAny> = {};
+  const fields: Record<string, ValueObjectFieldDescriptor> = {};
+  const deps = new Map<string, ValueObjectDescriptor>();
+  for (const key of Object.keys(shape).sort()) {
+    const entry = shape[key]!;
+    if (isOptionalValueObject(entry)) {
+      const inner = entry.valueObject;
+      zodShape[key] = (inner.zod as z.ZodTypeAny).optional();
+      fields[key] =
+        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[key] = entry.zod as z.ZodTypeAny;
+      fields[key] =
+        entry.geometry !== undefined
+          ? { type: "geometry", ref: entry.name, geometry: entry.geometry }
+          : { type: "object", ref: entry.name };
+      collectDescriptors(entry, deps);
+    } else {
+      fields[key] = describeZod(name, key, entry);
+      zodShape[key] = entry;
+    }
+  }
+  if (deps.has(name)) {
+    throw new Error(`valueObject '${name}': a value object cannot nest itself (directly or via a dependency).`);
+  }
+  const descriptor: ValueObjectDescriptor = { name, fields };
+  const dependencies = [...deps.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  return makeValueObject(
+    name,
+    z.object(zodShape) as unknown as z.ZodType<ShapeValue<S>>,
+    descriptor,
+    dependencies,
+  );
+}
+
+// ── geo.* — the RFC 7946 geometry value objects ──────────────────────────────────────
+
+/** An RFC 7946 position: `[lng, lat]` or `[lng, lat, altitude]`. */
+const positionZod = z.array(z.number()).min(2).max(3);
+
+/** The authored TS shape of a `geo.point(...)` value (RFC 7946 Point). */
+export interface GeoPointValue {
+  type: "Point";
+  /** `[lng, lat]` or `[lng, lat, altitude]` (RFC 7946 position order). */
+  coordinates: number[];
+}
+/** The authored TS shape of a `geo.lineString(...)` value (RFC 7946 LineString). */
+export interface GeoLineStringValue {
+  type: "LineString";
+  coordinates: number[][];
+}
+/** The authored TS shape of a `geo.polygon(...)` value (RFC 7946 Polygon). */
+export interface GeoPolygonValue {
+  type: "Polygon";
+  coordinates: number[][][];
+}
+
+function geoZod(kind: GeometryKind, coordinates: z.ZodTypeAny): z.ZodTypeAny {
+  return z.object({ type: z.literal(kind), coordinates });
+}
+
+/**
+ * The GEO value objects — RFC 7946 geometries as named VOs, and THE BLESSED WAY to
+ * declare a spatial-indexable field: give the geometry its OWN aggregate field
+ * (`point: GeoPoint.field()`) and pair it with `spatial(id).of(Agg).on("point")` —
+ * the R*Tree indexes the field's GeoJSON geometry directly. (v1 boundary: the spatial
+ * lane indexes a TOP-LEVEL field; a geometry nested inside another VO — e.g.
+ * `location.point` — is data, not an indexable path.)
+ */
+export const geo = {
+  /** An RFC 7946 **Point** (`{type:"Point", coordinates:[lng,lat(,alt)?]}`) — the v1
+   *  spatial-index geometry. */
+  point(name = "GeoPoint"): ValueObject<GeoPointValue> {
+    return makeValueObject<GeoPointValue>(
+      name,
+      geoZod("Point", positionZod) as z.ZodType<GeoPointValue>,
+      { name, geometry: "Point" },
+      [],
+      "Point",
+    );
+  },
+  /** An RFC 7946 **LineString** (≥2 positions). */
+  lineString(name = "GeoLineString"): ValueObject<GeoLineStringValue> {
+    return makeValueObject<GeoLineStringValue>(
+      name,
+      geoZod("LineString", z.array(positionZod).min(2)) as z.ZodType<GeoLineStringValue>,
+      { name, geometry: "LineString" },
+      [],
+      "LineString",
+    );
+  },
+  /** An RFC 7946 **Polygon** (linear rings — ≥4 positions each, first == last by RFC;
+   *  ring closure is the author's contract, not re-validated here). */
+  polygon(name = "GeoPolygon"): ValueObject<GeoPolygonValue> {
+    return makeValueObject<GeoPolygonValue>(
+      name,
+      geoZod("Polygon", z.array(z.array(positionZod).min(4))) as z.ZodType<GeoPolygonValue>,
+      { name, geometry: "Polygon" },
+      [],
+      "Polygon",
+    );
+  },
+};
+
+// ── module-plane collection (composeDomainModule / codegen) ──────────────────────────
+
+/**
+ * Collect the DEDUPED, SORTED value-object descriptors used by a set of aggregates
+ * (each VO field's own descriptor + its transitive dependencies). Divergent same-name
+ * descriptors throw (one name, one shape). Returns `[]` when no field carries a VO —
+ * the omit-when-empty input to the `nomosValueObjects` era key.
+ */
+export function collectValueObjectDescriptors(
+  aggregates: readonly { id: string; fields: Record<string, Field> }[],
+): ValueObjectDescriptor[] {
+  const byName = new Map<string, ValueObjectDescriptor>();
+  for (const agg of aggregates) {
+    for (const field of Object.values(agg.fields)) {
+      const meta = field.valueObject;
+      if (meta === undefined) continue;
+      const all = [meta.descriptor, ...meta.dependencies];
+      for (const d of all) {
+        const existing = byName.get(d.name);
+        if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(d)) {
+          throw new Error(
+            `valueObject: aggregate '${agg.id}' uses a value object named '${d.name}' whose shape DIVERGES ` +
+              `from another use of the same name — one name, one shape. Rename one of them.`,
+          );
+        }
+        byName.set(d.name, d);
+      }
+    }
+  }
+  return [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}