@githolon/dsl 0.48.1 → 0.50.0

package/src/value_object.ts

@@ -52,6 +52,7 @@
  */
 import { z } from "zod";
 
+import type { Driver } from "./drivers.js";
 import {
   valueObjectField,
   type Field,
@@ -129,6 +130,17 @@ export interface ValueObject<T = unknown> {
    * whole), `.optional()`, `.encrypted()` (under the existing `requires(cap)` rules).
    */
   field(): Field<T, "json">;
+  /**
+   * SUGAR for `.field().merge(driver)` — lower this VO DIRECTLY to an aggregate field with
+   * the chosen merge driver: `location: SiteLocation.merge(Lww).optional()`. A VO field is
+   * ONE Lww-class json leaf replaced WHOLESALE, so only the Lww-class family
+   * (`Lww` / `LwwCausal` / `LwwBy`) is accepted — any other driver throws (field-level merge
+   * composition of a VO's subfields is a later slice; model those as aggregate fields / a
+   * `t.map(...)`). The returned `Field` chains the usual modifiers (`.optional()`,
+   * `.encrypted()`, …), so `SiteLocation.merge(Lww).optional()` == `SiteLocation.field()
+   * .merge(Lww).optional()` byte-for-byte.
+   */
+  merge(driver: Driver): Field<T, "json">;
   /** Phantom to keep T load-bearing for inference. */
   readonly _t?: T;
 }
@@ -255,12 +267,48 @@ export function idOfMetaOf(zt: z.ZodTypeAny): string | undefined {
   return undefined;
 }
 
+/** Thread a nested VO's own descriptor + transitive dependencies into `deps` (divergent
+ *  same-name shapes throw — one name, one shape), then return its ref field descriptor. This
+ *  is what makes `z.array(SomeVo.zod)` / a raw `SomeVo.zod` entry plug-and-play: the VO brand
+ *  rides the `.zod`, so the descriptor TREE is threaded rather than lost (vo_first_class.md
+ *  slice 0). */
+function takeVoField(
+  meta: ValueObjectFieldMeta,
+  deps: Map<string, ValueObjectDescriptor>,
+): ValueObjectFieldDescriptor {
+  for (const d of [meta.descriptor, ...meta.dependencies]) {
+    const existing = deps.get(d.name);
+    if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(d)) {
+      throw new Error(
+        `valueObject: two DIVERGENT value objects share the name '${d.name}' — one name, one shape. ` +
+          `Rename one of them (the descriptor is identity-bearing).`,
+      );
+    }
+    deps.set(d.name, d);
+  }
+  return meta.geometry !== undefined
+    ? { type: "geometry", ref: meta.name, geometry: meta.geometry }
+    : { type: "object", ref: meta.name };
+}
+
 /**
  * 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).
+ * never ships an undescribed structure). `deps` collects every nested VO the schema
+ * references BY BRAND (`z.array(SomeVo.zod)`, a raw `SomeVo.zod`) so its descriptor rides
+ * alongside — the caller unions it into the VO's `dependencies`.
  */
-function describeZod(voName: string, path: string, schema: z.ZodTypeAny): ValueObjectFieldDescriptor {
+function describeZod(
+  voName: string,
+  path: string,
+  schema: z.ZodTypeAny,
+  deps: Map<string, ValueObjectDescriptor>,
+): ValueObjectFieldDescriptor {
+  // A VO referenced through its RAW zod (its own brand, no optional wrapper) — emit the
+  // ref + thread its descriptor tree. (Optional wrappers are handled by the switch below,
+  // which recurses to the branded inner schema.)
+  const ownBrand = (schema as unknown as Record<symbol, unknown>)[NOMOS_VO_BRAND];
+  if (ownBrand !== undefined) return takeVoField(ownBrand as ValueObjectFieldMeta, deps);
   switch (zodKind(schema)) {
     case "string":
       return { type: "string" };
@@ -285,7 +333,7 @@ function describeZod(voName: string, path: string, schema: z.ZodTypeAny): ValueO
       return { type: "literal", value: v };
     }
     case "array": {
-      const items = describeZod(voName, `${path}[]`, zodArrayElement(schema));
+      const items = describeZod(voName, `${path}[]`, zodArrayElement(schema), deps);
       if (items.optional === true) {
         throw new Error(
           `valueObject '${voName}': field '${path}' is an array of optionals — not expressible in the v1 set.`,
@@ -295,7 +343,7 @@ function describeZod(voName: string, path: string, schema: z.ZodTypeAny): ValueO
     }
     case "optional":
     case "default": {
-      const inner = describeZod(voName, path, zodDef(schema).innerType!);
+      const inner = describeZod(voName, path, zodDef(schema).innerType!, deps);
       return { ...inner, optional: true };
     }
     default:
@@ -452,7 +500,29 @@ function makeValueObject<T>(
     field(): Field<T, "json"> {
       return valueObjectField(zodSchema, meta);
     },
+    merge(driver: Driver): Field<T, "json"> {
+      const k = driver.kind;
+      if (k !== "Lww" && k !== "LwwCausal" && k !== "LwwBy") {
+        throw new Error(
+          `valueObject '${name}': .merge(${k}) is not a valid value-object field merge — a VO is ONE ` +
+            `Lww-class json leaf replaced WHOLESALE, so only Lww / LwwCausal / LwwBy apply. Field-level ` +
+            `merge composition of a VO's subfields is a later slice; model independently-merging subfields ` +
+            `as aggregate fields or a t.map(...).`,
+        );
+      }
+      return valueObjectField(zodSchema, meta).merge(driver);
+    },
   };
+  // THE HANDLE IS A FIRST-CLASS ZOD SCHEMA (vo_first_class.md slice 1): delegate zod's
+  // internals so the raw HANDLE composes DIRECTLY where a zod is expected — `z.array(Vo)`,
+  // `z.object({ f: Vo })`, a directive payload — with NO `.zod` peeling. Non-enumerable (never
+  // serialized, domainHash-inert) and stamped with the VO brand so describeZod / voMetaOf resolve
+  // the handle exactly like its `.zod`.
+  const inner = zodSchema as unknown as { _zod?: unknown; _def?: unknown; def?: unknown };
+  Object.defineProperty(vo, "_zod", { get: () => inner._zod, enumerable: false });
+  Object.defineProperty(vo, "_def", { get: () => inner._def, enumerable: false });
+  Object.defineProperty(vo, "def", { get: () => inner.def, enumerable: false });
+  Object.defineProperty(vo, NOMOS_VO_BRAND, { value: meta, enumerable: false });
   return vo;
 }
 
@@ -495,7 +565,7 @@ export function valueObject<const Name extends string, S extends Record<string,
           : { type: "object", ref: entry.name };
       collectDescriptors(entry, deps);
     } else {
-      fields[key] = describeZod(name, key, entry);
+      fields[key] = describeZod(name, key, entry, deps);
       zodShape[key] = entry;
     }
   }
@@ -584,7 +654,7 @@ export function variant<const Name extends string, Arms extends Record<string, U
             : { type: "object", ref: entry.name };
           collectDescriptors(entry, deps);
         } else {
-          fields[fieldKey] = describeZod(name, `${key}.${fieldKey}`, entry);
+          fields[fieldKey] = describeZod(name, `${key}.${fieldKey}`, entry, deps);
           zodShape[fieldKey] = entry;
         }
       }