@githolon/dsl 0.38.0 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/codegen_dart.ts

@@ -29,6 +29,7 @@
  * generated, so they stay reproducible from the domain definitions.
  */
 import { z } from "zod";
+import { voMetaOf, collectPayloadValueObjectDescriptors } from "./value_object.js";
 import type { AggregateHandle } from "./aggregate.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import type { RelationTypeDecl } from "./relation_schema.js";
@@ -60,7 +61,9 @@ export type ToJsonWrap =
   | "scalar" // String/int/bool — emit the field directly.
   | "enum" // generated enum — emit `.wire`.
   | "strList" // List<String> — emit directly.
-  | "json"; // nested object — emit the field's `Map<String, Object?>` directly.
+  | "json" // nested object — emit the field's `Map<String, Object?>` directly.
+  | "vo" // a declared value object — emit `.toJson()` (the generated VO class).
+  | "voList"; // a list of value objects — emit `.map((e) => e.toJson()).toList()`.
 
 export interface PayloadFieldSpec {
   name: string;
@@ -262,19 +265,31 @@ function introspectField(
     }
     case "ZodArray": {
       const elem = zodArrayElement(zt);
-      // A `string[]` is a typed `List<String>`. ANY other element type (e.g.
-      // `z.array(z.object(...))` — proposals' replacement `edges`) is arbitrary
-      // JSON DATA to the engine, modelled as `List<Object?>` and shipped verbatim.
+      // A `string[]` is a typed `List<String>`. A list of DECLARED VALUE OBJECTS is typed
+      // with the generated VO class (vo_authoring_end_to_end.md slice B). ANY other element
+      // type is arbitrary JSON DATA to the engine, modelled as `List<Object?>`.
       if (zodTypeName(elem) === "ZodString") {
         return { name, dartType: "List<String>", toJson: "strList" };
       }
+      const elemVo = voMetaOf(elem);
+      if (elemVo !== undefined) {
+        return { name, dartType: `List<${elemVo.name}>`, toJson: "voList" };
+      }
       return { name, dartType: "List<Object?>", toJson: "json" };
     }
-    case "ZodObject":
+    case "ZodObject": {
+      // A DECLARED VALUE OBJECT keeps its name: the payload field is the generated VO class
+      // (typed author path — the same class the read model decodes to), serialised via its
+      // own `toJson()`. An anonymous `z.object(...)` stays the raw-map lane below.
+      const vo = voMetaOf(zt);
+      if (vo !== undefined) {
+        return { name, dartType: vo.name, toJson: "vo" };
+      }
       // Nested object payload (e.g. `target: z.object({targetType, targetId})`). The
       // engine receives it as DATA verbatim, so we model it as an arbitrary JSON map
       // — the call site builds the literal, and `toPayloadJson()` ships it through.
       return { name, dartType: "Map<String, Object?>", toJson: "json" };
+    }
     case "ZodRecord": {
       const valueType = zodRecordValueType(zt);
       const dartType =
@@ -1908,6 +1923,10 @@ export function toJsonExpr(spec: PayloadFieldSpec, accessor: string): string {
       return accessor;
     case "enum":
       return `${accessor}.wire`;
+    case "vo":
+      return `${accessor}.toJson()`;
+    case "voList":
+      return `${accessor}.map((e) => e.toJson()).toList()`;
   }
 }
 
@@ -2942,7 +2961,14 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   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));
+  // Payload-only VOs (a VO used in a directive payload but on no aggregate field) still need
+  // their generated class — collected from the branded payload schemas, deduped by name against
+  // the aggregate-derived set. Codegen-only: the IR key stays aggregate-derived (era rule).
+  const aggVoNames = new Set((mod.valueObjects ?? []).map((d) => d.name));
+  const payloadVos = collectPayloadValueObjectDescriptors(mod.directives ?? []).filter((d) => !aggVoNames.has(d.name));
+  const localValueObjects = [...(mod.valueObjects ?? []), ...payloadVos]
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    .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 =

package/src/codegen_proof.ts

@@ -44,6 +44,7 @@ import type { FieldOp } from "./ops.js";
 import type { RelationTypeDecl, Rewrite } from "./relation_schema.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import { finishCount } from "./count.js";
+import { voMetaOf, voSample } from "./value_object.js";
 import { mintedCreateField } from "./workspace_routing.js";
 import { deterministicPorts } from "./ctx.js";
 import { __setDispatchDomain } from "./framework/relations.js";
@@ -98,6 +99,12 @@ function sampleString(zt: z.ZodTypeAny, field: string): string {
 
 /** One sample value for one zod shape. NO FALLBACK: an unhandled shape throws, naming its remedy. */
 function sampleOfZod(zt: z.ZodTypeAny, field: string, where: string): unknown {
+  // VALUE OBJECTS FIRST (vo_authoring_end_to_end.md slice C): a declared VO carries its own
+  // lawful sample (the author's validated `example`, the blessed geometry sample, or per-field
+  // descriptor synthesis) — the raw-zod walk below cannot see constraints like geo's min-2
+  // coordinates and would synthesize a value the law itself refuses.
+  const vo = voMetaOf(zt);
+  if (vo !== undefined) return voSample(vo);
   switch (zodKind(zt)) {
     case "string":
       return sampleString(zt, field);

package/src/codegen_provider_dart.ts

@@ -171,6 +171,17 @@ function obligationFromJsonExpr(s: PayloadFieldSpec): string {
       // a list. The Dart type drives the cast.
       return s.optional ? `${raw} as ${s.dartType}?` : `${raw} as ${s.dartType}`;
     }
+    case "vo": {
+      // A declared value object — decode through the generated class (typed both ways).
+      return s.optional
+        ? `${raw} == null ? null : ${s.dartType}.fromProjected((${raw} as Map).cast<String, Object?>())`
+        : `${s.dartType}.fromProjected((${raw} as Map).cast<String, Object?>())`;
+    }
+    case "voList": {
+      const elem = s.dartType.replace(/^List<(.*)>$/, "$1");
+      const decode = `(${raw} as List).map((e) => ${elem}.fromProjected((e as Map).cast<String, Object?>())).toList()`;
+      return s.optional ? `${raw} == null ? null : ${decode}` : decode;
+    }
   }
 }
 

package/src/codegen_ts.ts

@@ -41,6 +41,7 @@ import type { Field, ValueObjectDescriptor, ValueObjectFieldDescriptor } from ".
 import type { Directive } from "./directive.js";
 import type { DomainModule } from "./codegen_dart.js";
 import type { QueryDecl } from "./query.js";
+import { voMetaOf, collectPayloadValueObjectDescriptors } from "./value_object.js";
 import { finishCount } from "./count.js";
 import { finishSum } from "./sum.js";
 import type { DerivedDecl } from "./derived.js";
@@ -122,6 +123,14 @@ const paren = (t: string) => (t.includes("|") || t.includes("&") ? `(${t})` : t)
 
 /** Recursive zod → TS type text. NO FALLBACK: an unhandled shape throws. */
 function tsTypeOfZod(zt: z.ZodTypeAny, indent: string): string {
+  // A DECLARED VALUE OBJECT keeps its NAME (vo_authoring_end_to_end.md slice B): the payload
+  // references the same exported interface the read model uses — one name, both directions —
+  // instead of an anonymous inline literal type. Checked on the BARE object only: optional/
+  // default wrappers must keep flowing through the switch so `| undefined` survives.
+  if (zodKind(zt) === "object") {
+    const vo = voMetaOf(zt);
+    if (vo !== undefined) return vo.name;
+  }
   switch (zodKind(zt)) {
     case "string":
       return "string";
@@ -476,7 +485,11 @@ 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 ?? []) {
+    // aggregate-carried VOs ∪ payload-only VOs (branded schemas) — both need their interface.
+    const payloadVos = collectPayloadValueObjectDescriptors(
+      ((mod as { directives?: readonly { payloadSchema?: unknown }[] }).directives ?? []),
+    );
+    for (const d of [...((mod as { valueObjects?: readonly ValueObjectDescriptor[] }).valueObjects ?? []), ...payloadVos]) {
       const existing = voByName.get(d.name);
       if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(d)) {
         throw new Error(

package/src/fields.ts

@@ -126,6 +126,9 @@ export interface ValueObjectFieldMeta {
   readonly dependencies: readonly ValueObjectDescriptor[];
   /** Present iff this VO is a `geo.*` geometry (the spatial-index pairing check). */
   readonly geometry?: GeometryKind;
+  /** The author-supplied lawful example (validated against the VO's own zod at declaration).
+   * Proof synthesis + docs prefer it over per-field synthesis. */
+  readonly example?: unknown;
 }
 
 export interface Field<T = unknown, K extends FieldKind = FieldKind> {

package/src/index.ts

@@ -47,6 +47,9 @@ export {
 // `geo.*` are the RFC 7946 geometry VOs (pair `geo.point()` with `spatial(...)`).
 export {
   valueObject,
+  voMetaOf,
+  voSample,
+  NOMOS_VO_BRAND,
   geo,
   type ValueObject,
   type ValueObjectValue,

package/src/shape_compat.ts

@@ -80,6 +80,11 @@ function payloadFieldKind(spec: PayloadFieldSpec): string {
       return "set";
     case "json":
       return "json";
+    case "vo":
+    case "voList":
+      // Interface kinds stay at the base lane for now (slice D of vo_authoring_end_to_end.md
+      // upgrades these to a first-class "vo" kind) — a VO IS a json leaf structurally.
+      return "json";
     case "scalar":
     default:
       switch (spec.dartType) {

package/src/value_object.ts

@@ -226,12 +226,93 @@ function describeZod(voName: string, path: string, schema: z.ZodTypeAny): ValueO
 
 const VO_NAME_RE = /^[A-Za-z][A-Za-z0-9_]*$/;
 
+/**
+ * THE VO BRAND (slice A of vo_authoring_end_to_end.md) — `valueObject()` stamps its zod schema
+ * with the VO's {@link ValueObjectFieldMeta} under this symbol, COMPILE-TIME ONLY: the brand is
+ * a non-enumerable property, never serialized, never read by the engine's validation path, so a
+ * branded schema's package bytes (and domainHash) are byte-identical to an unbranded one.
+ * Every generated-surface introspector (Dart/TS payload gen, interface kinds, proof synthesis)
+ * consults {@link voMetaOf} BEFORE its raw zod-kind switch — the VO keeps its NAME on every
+ * surface instead of degrading to an anonymous json object.
+ */
+export const NOMOS_VO_BRAND: unique symbol = Symbol.for("nomos.vo");
+
+/**
+ * Resolve the value-object identity of a zod schema, unwrapping `.optional()` / `.default()`
+ * wrappers (the brand lives on the VO's own object schema). `undefined` for anything that is
+ * not a declared VO — callers then fall through to their raw-zod lane, so non-VO behaviour is
+ * untouched.
+ */
+export function voMetaOf(zt: z.ZodTypeAny): ValueObjectFieldMeta | undefined {
+  let cur: z.ZodTypeAny | undefined = zt;
+  for (let hops = 0; cur !== undefined && hops < 16; hops++) {
+    const branded = (cur as unknown as Record<symbol, unknown>)[NOMOS_VO_BRAND];
+    if (branded !== undefined) return branded as ValueObjectFieldMeta;
+    const kind = zodKind(cur);
+    if (kind !== "optional" && kind !== "default" && kind !== "nullable") return undefined;
+    cur = zodDef(cur).innerType;
+  }
+  return undefined;
+}
+
+/** The blessed lawful sample per RFC 7946 geometry kind (proof synthesis + docs). */
+const GEOMETRY_SAMPLES: Record<GeometryKind, unknown> = {
+  Point: { type: "Point", coordinates: [0, 0] },
+  LineString: { type: "LineString", coordinates: [[0, 0], [1, 1]] },
+  Polygon: { type: "Polygon", coordinates: [[[0, 0], [0, 1], [1, 1], [0, 0]]] },
+};
+
+function sampleOfDescriptorField(
+  f: ValueObjectFieldDescriptor,
+  fieldName: string,
+  byName: Map<string, ValueObjectDescriptor>,
+): unknown {
+  switch (f.type) {
+    case "string": return `sample-${fieldName}`;
+    case "number": return 1;
+    case "boolean": return true;
+    case "enum": return f.values[0];
+    case "array": return [sampleOfDescriptorField(f.items, fieldName, byName)];
+    case "geometry": return GEOMETRY_SAMPLES[f.geometry];
+    case "object": {
+      const dep = byName.get(f.ref);
+      if (dep === undefined) throw new Error(`voSample: nested value object '${f.ref}' has no descriptor`);
+      return sampleOfDescriptor(dep, byName);
+    }
+  }
+}
+
+function sampleOfDescriptor(d: ValueObjectDescriptor, byName: Map<string, ValueObjectDescriptor>): unknown {
+  if (d.geometry !== undefined) return GEOMETRY_SAMPLES[d.geometry];
+  const out: Record<string, unknown> = {};
+  for (const [k, f] of Object.entries(d.fields ?? {})) {
+    if (f.optional === true) continue; // optional → omitted (mirrors payload synthesis)
+    out[k] = sampleOfDescriptorField(f, k, byName);
+  }
+  return out;
+}
+
+/**
+ * A LAWFUL sample value for a VO (slice C): the author's validated `example` when given, the
+ * blessed geometry sample for `geo.*` kinds, else per-field synthesis (recursing into nested
+ * VOs). Proof synthesis calls this instead of guessing at the raw zod — which is exactly the
+ * lane that refused its own sample on constrained shapes (geo min-2 coordinates).
+ */
+export function voSample(meta: ValueObjectFieldMeta): unknown {
+  if (meta.example !== undefined) return meta.example;
+  const byName = new Map<string, ValueObjectDescriptor>();
+  for (const d of meta.dependencies) byName.set(d.name, d);
+  byName.set(meta.descriptor.name, meta.descriptor);
+  return sampleOfDescriptor(meta.descriptor, byName);
+}
+
 function makeValueObject<T>(
   name: string,
   zodSchema: z.ZodType<T>,
   descriptor: ValueObjectDescriptor,
   dependencies: readonly ValueObjectDescriptor[],
   geometry?: GeometryKind,
+  example?: T,
 ): ValueObject<T> {
   if (!VO_NAME_RE.test(name)) {
     throw new Error(
@@ -239,12 +320,25 @@ function makeValueObject<T>(
         `generated TS interface / Dart class name.`,
     );
   }
+  if (example !== undefined) {
+    const v = zodSchema.safeParse(example);
+    if (!v.success) {
+      throw new Error(
+        `valueObject '${name}': the declared example does not satisfy the VO's own schema — ` +
+          `a lying example would poison proof synthesis. ${v.error.message}`,
+      );
+    }
+  }
   const meta: ValueObjectFieldMeta = {
     name,
     descriptor,
     dependencies,
     ...(geometry !== undefined ? { geometry } : {}),
+    ...(example !== undefined ? { example } : {}),
   };
+  // THE BRAND (slice A): compile-time identity on the schema itself — non-enumerable, never
+  // serialized, domainHash-inert. voMetaOf() is the one resolver every introspector uses.
+  Object.defineProperty(zodSchema, NOMOS_VO_BRAND, { value: meta, enumerable: false });
   const vo: ValueObject<T> = {
     __isValueObject: true,
     name,
@@ -272,6 +366,13 @@ function makeValueObject<T>(
 export function valueObject<const Name extends string, S extends Record<string, ValueObjectShapeEntry>>(
   name: Name,
   shape: S,
+  opts?: {
+    /** A lawful example value, VALIDATED against the VO's own schema at declaration (a lying
+     * example throws here, loudly). Proof synthesis prefers it over per-field synthesis — the
+     * escape hatch for constraint-rich shapes (refinements, cross-field rules) a synthesizer
+     * cannot guess. */
+    example?: ShapeValue<S>;
+  },
 ): ValueObject<ShapeValue<S>> {
   const zodShape: Record<string, z.ZodTypeAny> = {};
   const fields: Record<string, ValueObjectFieldDescriptor> = {};
@@ -308,6 +409,8 @@ export function valueObject<const Name extends string, S extends Record<string,
     z.object(zodShape) as unknown as z.ZodType<ShapeValue<S>>,
     descriptor,
     dependencies,
+    undefined,
+    opts?.example,
   );
 }
 
@@ -388,6 +491,46 @@ export const geo = {
  * descriptors throw (one name, one shape). Returns `[]` when no field carries a VO —
  * the omit-when-empty input to the `nomosValueObjects` era key.
  */
+/**
+ * Collect the value objects referenced by DIRECTIVE PAYLOADS (top-level fields + array
+ * elements), via the {@link NOMOS_VO_BRAND} the schemas carry. CODEGEN-ONLY (slice B of
+ * vo_authoring_end_to_end.md): the result feeds the generated Dart/TS surfaces so a
+ * payload-only VO still gets its class/interface — it does NOT enter the `nomosValueObjects`
+ * IR key (that stays aggregate-derived, keeping package bytes / domainHash untouched).
+ */
+export function collectPayloadValueObjectDescriptors(
+  directives: readonly { payloadSchema?: unknown }[],
+): ValueObjectDescriptor[] {
+  const byName = new Map<string, ValueObjectDescriptor>();
+  const take = (meta: ValueObjectFieldMeta | undefined) => {
+    if (meta === undefined) return;
+    for (const d of [meta.descriptor, ...meta.dependencies]) {
+      const existing = byName.get(d.name);
+      if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(d)) {
+        throw new Error(`value object '${d.name}' has DIVERGENT shapes across payloads — one name, one shape.`);
+      }
+      byName.set(d.name, d);
+    }
+  };
+  for (const dir of directives) {
+    const schema = dir?.payloadSchema as z.ZodTypeAny | undefined;
+    if (!schema || typeof schema !== "object" || zodKind(schema) !== "object") continue;
+    const rawShape = (zodDef(schema) as { shape?: Record<string, z.ZodTypeAny> | (() => Record<string, z.ZodTypeAny>) }).shape
+      ?? (schema as unknown as { shape?: Record<string, z.ZodTypeAny> }).shape;
+    const shape = typeof rawShape === "function" ? rawShape() : rawShape ?? {};
+    for (const raw of Object.values(shape)) {
+      let zt = raw as z.ZodTypeAny;
+      take(voMetaOf(zt));
+      // unwrap optional/default to reach an array of VOs
+      for (let hops = 0; hops < 8 && (zodKind(zt) === "optional" || zodKind(zt) === "default"); hops++) {
+        zt = zodDef(zt).innerType!;
+      }
+      if (zodKind(zt) === "array") take(voMetaOf(zodArrayElement(zt)));
+    }
+  }
+  return [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
 export function collectValueObjectDescriptors(
   aggregates: readonly { id: string; fields: Record<string, Field> }[],
 ): ValueObjectDescriptor[] {