@githolon/dsl 0.62.0 → 0.63.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.62.0",
+  "version": "0.63.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/fields.ts

@@ -397,6 +397,12 @@ function makeField<T, K extends FieldKind = FieldKind>(
   extra: {
     refWorkspace?: string;
     refAggregateId?: string;
+    /** LAZY target resolution — `t.ref(() => Agg)` / `t.hasMany(() => Agg)`. Breaks a BIDIRECTIONAL
+     *  declaration cycle (a Parent's `hasMany(Child)` ⇄ a Child's `ref(Parent)`): the thunk is stored and
+     *  resolved on FIRST read of `refAggregateId` (at manifest build — after all module consts init), so
+     *  neither side needs the other to already exist at its own `const`. Consumers read `refAggregateId`
+     *  transparently (a memoized getter). */
+    refAggregateIdThunk?: () => string;
     viaField?: string;
     isOptional?: boolean;
     fromBirth?: true;
@@ -496,6 +502,21 @@ function makeField<T, K extends FieldKind = FieldKind>(
       return makeField<T, K>(kind, zod, driver, { ...extra, facet }) as Field<T, K> & { readonly facet: Fa };
     },
   };
+  // LAZY REF TARGET: when the target was given as a thunk (`t.ref(() => Agg)` / `t.hasMany(() => Agg)` — to
+  // break a bidirectional declaration cycle), expose `refAggregateId` as a MEMOIZED getter that resolves the
+  // thunk on first read (build time, after all module consts init). Consumers read `refAggregateId` as usual.
+  if (extra.refAggregateIdThunk !== undefined) {
+    const thunk = extra.refAggregateIdThunk;
+    let resolved: string | undefined;
+    Object.defineProperty(f, "refAggregateId", {
+      configurable: true,
+      enumerable: true,
+      get() {
+        if (resolved === undefined) resolved = thunk();
+        return resolved;
+      },
+    });
+  }
   return f;
 }
 
@@ -740,13 +761,16 @@ export const t = {
    * (one event on the CHILD, parent untouched), and the read engine serves `parent.children` as the
    * managed `Child by parent` index. The dev never builds a write-amplifying parent collection.
    */
-  hasMany(child: AggregateHandle<string, Record<string, Field>>): {
+  hasMany(child: AggregateHandle<string, Record<string, Field>> | (() => AggregateHandle<string, Record<string, Field>>)): {
     via(backref: string): Field<string[], "hasMany">;
   } {
+    // THUNK form (`t.hasMany(() => Child)`) — the common bidirectional case (a Parent's `hasMany(Child)` ⇄ a
+    // Child's `ref(Parent)`): pass a thunk so the Parent needn't wait for the Child's `const` to exist.
+    const isThunk = typeof child === "function";
     return {
       via(backref: string): Field<string[], "hasMany"> {
         return makeField<string[], "hasMany">("hasMany", z.array(z.string()), Conflict, {
-          refAggregateId: child.id,
+          ...(isThunk ? { refAggregateIdThunk: () => child().id } : { refAggregateId: child.id }),
           viaField: backref,
         });
       },
@@ -768,8 +792,11 @@ export const t = {
   },
 };
 
+type RefTarget = AggregateHandle<string, Record<string, Field>> | (() => AggregateHandle<string, Record<string, Field>>);
+
 interface RefFn {
-  (target: AggregateHandle<string, Record<string, Field>>): Field<string, "ref">;
+  /** Same-workspace reference. Pass a THUNK (`t.ref(() => Agg)`) to break a bidirectional declaration cycle. */
+  (target: RefTarget): Field<string, "ref">;
   (
     workspaceId: string,
     target: AggregateHandle<string, Record<string, Field>>,
@@ -777,7 +804,7 @@ interface RefFn {
 }
 
 function refImpl(
-  a: string | AggregateHandle<string, Record<string, Field>>,
+  a: string | RefTarget,
   b?: AggregateHandle<string, Record<string, Field>>,
 ): Field<string, "ref"> {
   if (typeof a === "string") {
@@ -787,6 +814,10 @@ function refImpl(
       refAggregateId: target.id,
     });
   }
+  // THUNK form (`t.ref(() => Agg)`) — resolve lazily to break a bidirectional declaration cycle.
+  if (typeof a === "function") {
+    return makeField<string, "ref">("ref", z.string(), Conflict, { refAggregateIdThunk: () => a().id });
+  }
   return makeField<string, "ref">("ref", z.string(), Conflict, { refAggregateId: a.id });
 }