@githolon/dsl 0.31.1 → 0.33.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));
+}