@githolon/dsl 0.62.0 → 0.64.0

package/package.json

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

@@ -243,6 +243,27 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
   opts?: { invariant?: AggregateInvariantFn; invariantDeclassify?: string; cap?: number; visibility?: ReadVisibility; global?: boolean },
 ): AggregateHandle<Id, F> & AudienceMethods<Id, F> {
   const { stored, hasMany } = partitionFields(fields);
+  // FOREIGN-REF SIBLING CHECK (pain point #4): a `t.foreignRef({ workspace, target })` field names a
+  // SIBLING string field (`workspaceField`) that holds the foreign workspace id — the target workspace is
+  // DYNAMIC, read from that sibling at resolve time. That link is STRINGLY-TYPED (a bare field name), so a
+  // typo would silently produce a locator pointing at a non-existent workspace field. Catch it HERE, at
+  // compile: the named sibling must exist on THIS aggregate and be a plain string-kind field (it holds a
+  // workspace id). It must be a real string field — not itself a foreignRef/ref — since it carries the raw id.
+  for (const [name, field] of Object.entries(stored)) {
+    const fref = (field as Field).foreignRef;
+    if (fref === undefined) continue;
+    const sibling = stored[fref.workspaceField] as Field | undefined;
+    if (sibling === undefined) {
+      throw new Error(
+        `aggregate '${id}': field '${name}' is a t.foreignRef whose workspace field '${fref.workspaceField}' does not exist on aggregate '${id}' — add a \`${fref.workspaceField}: t.string()\` field to aggregate '${id}', or fix the \`workspace:\` name in the foreignRef`,
+      );
+    }
+    if (sibling.kind !== "string") {
+      throw new Error(
+        `aggregate '${id}': field '${name}' is a t.foreignRef whose workspace field '${fref.workspaceField}' is kind '${sibling.kind}', but it must be a plain string-kind field (it holds the foreign workspace id) — declare \`${fref.workspaceField}: t.string()\``,
+      );
+    }
+  }
   if (opts?.cap !== undefined && (!Number.isInteger(opts.cap) || opts.cap < 1)) {
     throw new Error(`aggregate '${id}': cap must be a positive integer (got ${opts.cap})`);
   }

package/src/codegen_ts.ts

@@ -496,8 +496,12 @@ function tsBaseTypeOfField(field: Field): string {
       } catch {
         return "string";
       }
-    case "ref":
-      return "string"; // the related aggregate's id
+    case "ref": {
+      // A `t.foreignRef` field surfaces as a TYPED cross-workspace locator (hydrated by the accessors from
+      // the raw id + the declared workspace field); a plain same-workspace `t.ref` stays the id string.
+      const fr = (field as { foreignRef?: { targetAggregateId: string } }).foreignRef;
+      return fr !== undefined ? `ForeignRef<${fr.targetAggregateId}Data>` : "string";
+    }
     case "json":
       // A NAMED VALUE OBJECT field reads as its generated interface (`value_object.ts`);
       // a bare `t.jsonObject()` stays the anonymous object; a plain `t.json()` is unknown.
@@ -720,6 +724,76 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       : []),
     `/** One projection row: the aggregate's wire type, its id, and the folded fields. */`,
     `export interface Row<T> { type: string; id: string; data: T }`,
+    // MULTI-WORKSPACE LOCATORS (t.foreignRef): a TYPED cross-workspace edge — the foreign aggregate's id +
+    // the foreign workspace id (from a sibling field). NOT an atomic FK: it does not clone/open the other
+    // holon; `resolve`/`watch` open it ON DEMAND over a realm (openRealm's `.workspace(ws)` surface).
+    // The reader `resolve`/`watch`/`attest` need: the multi-workspace `.workspace(ws)` surface `openRealm()`
+    // returns (a plain `connect()` holon is single-workspace — pass a Realm). `attestForeign` is the attested-
+    // read extension (present only when your law declares `trustSource` + `.readsFrom`). ANY object with this
+    // shape works — the generated client is import-free and binds structurally to your @githolon/client.
+    `export interface NomosForeignReader { workspace(ws: string): { queryById(id: string): Promise<{ type: string; id: string; data: unknown }[]>; watchById?(id: string, cb: (rows: { type: string; id: string; data: unknown }[]) => void, opts?: { intervalMs?: number }): () => void }; attestForeign?(workspace: string, id: string, type: string): Promise<{ id: string; workspace: string; exists: boolean; attestation: string }>; }`,
+    // resolve() collapses "not there" to undefined for the 99% lookup; resolveResult() names WHY — a foreign
+    // read can come back empty because the target does not exist, you lack read access, or the holon is
+    // unreachable, and those are very different. `denied`/`unreachable` are best-effort from the reader's
+    // error (an error whose message mentions auth/permission/forbidden ⇒ denied; else unreachable).
+    `export type ForeignResolveResult<TData> = { status: "found"; row: Row<TData> } | { status: "not-found" } | { status: "denied"; error: unknown } | { status: "unreachable"; error: unknown };`,
+    // A ForeignRef is a TYPED CROSS-WORKSPACE LOCATOR, not an atomic FK. In ~99% of cases you use it as a
+    // lookup — `resolve`/`watch` open the foreign holon on demand so you can do more reads. `exists` is the
+    // cheap "is the target still there?" check. `attest` is the LAW-GRADE one — signed evidence that the
+    // reference resolves — and only works when your law DECLARES the dependency (`trustSource` + a
+    // `.readsFrom(...)` on the directive); it is deliberately NOT a free method, because attesting has cost
+    // and law meaning. Resolving/existence are informational; attestation is what you reach for when the
+    // current workspace's LAW depends on the foreign fact.
+    `export interface ForeignRef<TData> {`,
+    `  /** The foreign aggregate's id (this field's stored value). */`,
+    `  readonly id: string;`,
+    `  /** The foreign workspace id (from the declared sibling workspace field). */`,
+    `  readonly workspace: string;`,
+    `  /** The foreign aggregate type this locator points at. */`,
+    `  readonly type: string;`,
+    `  /** THE LOOKUP (the 99% case): open the foreign workspace + read the target by id — on demand, no clone.`,
+    `   *  Returns undefined for ANY empty outcome; use resolveResult() when you need to know WHY. */`,
+    `  resolve(nomos: NomosForeignReader): Promise<Row<TData> | undefined>;`,
+    `  /** The lookup with the OUTCOME named — found / not-found / denied / unreachable (a foreign read can be`,
+    `   *  empty for very different reasons; do not collapse them when it matters). */`,
+    `  resolveResult(nomos: NomosForeignReader): Promise<ForeignResolveResult<TData>>;`,
+    `  /** Subscribe to the target's read model across the workspace boundary (returns an unsubscribe fn). */`,
+    `  watch(nomos: NomosForeignReader, cb: (row: Row<TData> | undefined) => void, opts?: { intervalMs?: number }): () => void;`,
+    `  /** Cheap existence check — does the referenced target still exist? (found ⇒ true; anything else ⇒ false). */`,
+    `  exists(nomos: NomosForeignReader): Promise<boolean>;`,
+    `  /** LAW-GRADE: signed evidence that the reference resolves, for when your law DEPENDS on the foreign fact.`,
+    `   *  Requires the attested-read lane — declare \`trustSource(workspace, ...)\` + \`.readsFrom(...)\` on the`,
+    `   *  directive; without it (no \`attestForeign\` on the reader) this throws, by design (a locator is not an FK). */`,
+    `  attest(nomos: NomosForeignReader): Promise<{ id: string; workspace: string; exists: boolean; attestation: string }>;`,
+    `}`,
+    `/** Build a typed foreign-ref locator from a row's id + workspace-id values. The generated \`<domain>ForeignRefs\` factory calls this with the declared fields. */`,
+    `export function foreignRef<TData>(type: string, id: string, workspace: string): ForeignRef<TData> {`,
+    `  return {`,
+    `    id, workspace, type,`,
+    `    async resolveResult(nomos) {`,
+    `      if (!id || !workspace) return { status: "not-found" };`,
+    `      try {`,
+    `        const rows = await nomos.workspace(workspace).queryById(id);`,
+    `        const row = (rows.find((r) => r.id === id) ?? rows[0]) as Row<TData> | undefined;`,
+    `        return row !== undefined ? { status: "found", row } : { status: "not-found" };`,
+    `      } catch (error) {`,
+    `        const m = String((error as { message?: unknown })?.message ?? error).toLowerCase();`,
+    `        return { status: /forbid|denied|permission|unauthor|not permitted|403|401/.test(m) ? "denied" : "unreachable", error };`,
+    `      }`,
+    `    },`,
+    `    async resolve(nomos) { const r = await this.resolveResult(nomos); return r.status === "found" ? r.row : undefined; },`,
+    `    watch(nomos, cb, opts) {`,
+    `      const w = nomos.workspace(workspace).watchById;`,
+    `      if (!w || !id || !workspace) { cb(undefined); return () => {}; }`,
+    `      return w(id, (rows) => cb((rows.find((r) => r.id === id) ?? rows[0]) as Row<TData> | undefined), opts);`,
+    `    },`,
+    `    async exists(nomos) { return (await this.resolveResult(nomos)).status === "found"; },`,
+    `    async attest(nomos) {`,
+    `      if (!nomos.attestForeign) throw new Error("attest() needs the attested-read lane — declare trustSource(" + JSON.stringify(workspace) + ", …) + .readsFrom(…) on the directive whose law depends on this reference (a foreignRef is a locator, not an atomic foreign key)");`,
+    `      return nomos.attestForeign(workspace, id, type);`,
+    `    },`,
+    `  };`,
+    `}`,
     ``,
     `/** Arbitrary JSON — the type a RECURSIVE \`z.lazy\` payload subtree degrades to (a self-`,
     ` *  referencing tree/JSON schema can't be a finite named literal, so the engine validates it`,
@@ -1145,6 +1219,11 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   }
 
   out.push(`// ── read models (projection \`data\` shapes; partial-fold optional, EXCEPT .fromBirth()`, `//    fields — their presence is gate law, so the type is non-optional) ──`, ``);
+  const foreignRefFields: { agg: string; field: string; workspaceField: string; target: string }[] = [];
+  // wrap a read accessor return expression through the foreignRef row-hydrator (identity + byte-identical
+  // when the package declares no foreignRef, so non-foreignRef packages are unchanged).
+  const wrapP = (expr: string): string => (foreignRefFields.length > 0 ? `_hydrateP(${expr})` : expr);
+  const wrapRows = (expr: string): string => (foreignRefFields.length > 0 ? `_hydrateRows(${expr})` : expr);
   for (const [typeId, agg] of [...aggByType].sort(([a], [b]) => a.localeCompare(b))) {
     out.push(`export interface ${typeId}Data {`);
     for (const [name, field] of Object.entries(agg.fields)) {
@@ -1152,10 +1231,54 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       const doc = nullDocLine(field);
       if (doc !== undefined) out.push(`  /** ${doc} */`);
       out.push(`  ${name}${required ? "" : "?"}: ${tsTypeOfField(field as Field)};`);
+      const fr = (field as { foreignRef?: { workspaceField: string; targetAggregateId: string } }).foreignRef;
+      if (fr !== undefined) foreignRefFields.push({ agg: typeId, field: name, workspaceField: fr.workspaceField, target: fr.targetAggregateId });
     }
     for (const extra of extrasByType.get(typeId) ?? []) out.push(extra);
     out.push(`}`, ``);
   }
+  // MULTI-WORKSPACE LOCATOR FACTORY (t.foreignRef): per aggregate, a typed builder that turns a projection
+  // row into a `ForeignRef<TargetData>` — reading the foreign id (the field) + the foreign workspace id (the
+  // declared sibling field). The read model stays honest (the field is the raw stored id string); this gives
+  // the TYPED locator with resolve/watch on top, without cloning the other holon.
+  if (foreignRefFields.length > 0) {
+    const byAgg = new Map<string, typeof foreignRefFields>();
+    for (const f of foreignRefFields) { const l = byAgg.get(f.agg) ?? []; l.push(f); byAgg.set(f.agg, l); }
+    out.push(`// ── foreign-ref locators (t.foreignRef): typed cross-workspace edges (resolve/watch on demand) ──`);
+    out.push(`export const ${camel(opts.packageName)}ForeignRefs = {`);
+    for (const [agg, fields] of [...byAgg].sort(([a], [b]) => a.localeCompare(b))) {
+      out.push(`  ${agg}: {`);
+      for (const f of fields) {
+        out.push(
+          `    /** \`${agg}.${f.field}\` → \`${f.target}\` in the workspace named by \`${f.workspaceField}\`. */`,
+          `    ${f.field}: (row: ${agg}Data): ForeignRef<${f.target}Data> => foreignRef(${JSON.stringify(f.target)}, String(row.${f.field} ?? ""), String((row as Record<string, unknown>)[${JSON.stringify(f.workspaceField)}] ?? "")),`,
+        );
+      }
+      out.push(`  },`);
+    }
+    out.push(`} as const;`, ``);
+    // ROW HYDRATION: the read model surfaces a foreignRef field as a typed `ForeignRef` locator (so
+    // `row.data.<field>.resolve(nomos)` works directly). The projection stores the raw id string; the read
+    // accessors pipe rows through `_hydrateRows`, which — for aggregates that declare foreignRefs — replaces
+    // each foreignRef field with a locator built from its id + the declared sibling workspace field.
+    // `row.data.<field>.id` is still the raw id. Identity for any aggregate without foreignRefs.
+    const hydrateSpecs: Record<string, { field: string; wsField: string; target: string }[]> = {};
+    for (const f of foreignRefFields) { (hydrateSpecs[f.agg] ??= []).push({ field: f.field, wsField: f.workspaceField, target: f.target }); }
+    out.push(
+      `const _FOREIGN_REFS: Record<string, { field: string; wsField: string; target: string }[]> = ${JSON.stringify(hydrateSpecs)};`,
+      `function _hydrateRows<T>(rows: Row<T>[]): Row<T>[] {`,
+      `  return rows.map((row) => {`,
+      `    const specs = _FOREIGN_REFS[row.type];`,
+      `    if (specs === undefined || row.data == null) return row;`,
+      `    const data: Record<string, unknown> = { ...(row.data as Record<string, unknown>) };`,
+      `    for (const s of specs) { const v = data[s.field]; if (typeof v === "string") data[s.field] = foreignRef(s.target, v, String(data[s.wsField] ?? "")); }`,
+      `    return { ...row, data: data as T };`,
+      `  });`,
+      `}`,
+      `const _hydrateP = <T>(p: Promise<Row<T>[]>): Promise<Row<T>[]> => p.then(_hydrateRows);`,
+      ``,
+    );
+  }
 
   // ── DERIVED BIRTH LANES (sharding §10 RATIFIED, slice 1) ──
   // A `workspaceType(...).hasMany(...)` taxonomy DERIVES typed birth helpers over
@@ -1494,7 +1617,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     for (const sp of (mod.spatials ?? []) as { id: string; of: string; on: string }[]) {
       methods.push(
         `    /** Declared spatial index \`${sp.id}\` — rows of \`${sp.of}\` whose \`${sp.on}\` geometry intersects the bbox (R*Tree probe). */`,
-        `    ${lcFirst(camel(sp.id))}: (bbox: { minX: number; minY: number; maxX: number; maxY: number } | { minLng: number; minLat: number; maxLng: number; maxLat: number }) => (holon.spatialWithin ?? (() => { throw new Error("this holon predates spatial reads — upgrade @githolon/client"); }))(${JSON.stringify(sp.id)}, bbox) as Promise<Row<${sp.of}Data>[]>,`,
+        `    ${lcFirst(camel(sp.id))}: (bbox: { minX: number; minY: number; maxX: number; maxY: number } | { minLng: number; minLat: number; maxLng: number; maxLat: number }) => ${wrapP(`(holon.spatialWithin ?? (() => { throw new Error("this holon predates spatial reads — upgrade @githolon/client"); }))(${JSON.stringify(sp.id)}, bbox) as Promise<Row<${sp.of}Data>[]>`)},`,
       );
     }
     for (const q of (mod.queries ?? []) as QueryDecl[]) {
@@ -1511,8 +1634,8 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       methods.push(
         `    /** Declared query \`${q.id}\` (indexed probe — routed by the read manifest).${qScopes.length ? " Encrypted field(s) decrypt when the bound { keyStore } holds the scope key; else they stay opaque envelopes." : ""} */`,
         qScopes.length
-          ? `    ${lcFirst(camel(q.id))}: async (params: { ${params} }) => holon.query(${JSON.stringify(q.id)}, params, await _readKeys(keyStore, ${JSON.stringify(qScopes)})) as Promise<Row<${q.returns}Data>[]>,`
-          : `    ${lcFirst(camel(q.id))}: (params: { ${params} }) => holon.query(${JSON.stringify(q.id)}, params) as Promise<Row<${q.returns}Data>[]>,`,
+          ? `    ${lcFirst(camel(q.id))}: async (params: { ${params} }) => ${wrapP(`holon.query(${JSON.stringify(q.id)}, params, await _readKeys(keyStore, ${JSON.stringify(qScopes)})) as Promise<Row<${q.returns}Data>[]>`)},`
+          : `    ${lcFirst(camel(q.id))}: (params: { ${params} }) => ${wrapP(`holon.query(${JSON.stringify(q.id)}, params) as Promise<Row<${q.returns}Data>[]>`)},`,
       );
       // THE LOGICAL PAGED ROW SURFACE (sharding §5.3, ruling 2 — slice 4): emitted
       // ONLY for packed-taxonomy domains (taxonomy-free clients stay byte-identical).
@@ -1553,15 +1676,17 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       methods.push(
         `    /** Read one ${agg.id} by aggregate id.${aScopes.length ? " Encrypted field(s) decrypt when the bound { keyStore } holds the scope key." : ""} */`,
         aScopes.length
-          ? `    ${lcFirst(camel(agg.id))}ById: async (id: string) => holon.queryById(id, await _readKeys(keyStore, ${JSON.stringify(aScopes)})) as Promise<Row<${agg.id}Data>[]>,`
-          : `    ${lcFirst(camel(agg.id))}ById: (id: string) => holon.queryById(id) as Promise<Row<${agg.id}Data>[]>,`,
+          ? `    ${lcFirst(camel(agg.id))}ById: async (id: string) => ${wrapP(`holon.queryById(id, await _readKeys(keyStore, ${JSON.stringify(aScopes)})) as Promise<Row<${agg.id}Data>[]>`)},`
+          : `    ${lcFirst(camel(agg.id))}ById: (id: string) => ${wrapP(`holon.queryById(id) as Promise<Row<${agg.id}Data>[]>`)},`,
         `    /** Every ${agg.id} (the type-index probe — O(result), not a scan). */`,
         aScopes.length
-          ? `    list${agg.id}s: async () => holon.query("aggregatesByType", { __type: ${JSON.stringify(agg.id)} }, await _readKeys(keyStore, ${JSON.stringify(aScopes)})) as Promise<Row<${agg.id}Data>[]>,`
-          : `    list${agg.id}s: () => holon.query("aggregatesByType", { __type: ${JSON.stringify(agg.id)} }) as Promise<Row<${agg.id}Data>[]>,`,
+          ? `    list${agg.id}s: async () => ${wrapP(`holon.query("aggregatesByType", { __type: ${JSON.stringify(agg.id)} }, await _readKeys(keyStore, ${JSON.stringify(aScopes)})) as Promise<Row<${agg.id}Data>[]>`)},`
+          : `    list${agg.id}s: () => ${wrapP(`holon.query("aggregatesByType", { __type: ${JSON.stringify(agg.id)} }) as Promise<Row<${agg.id}Data>[]>`)},`,
         `    /** Watch one ${agg.id} by aggregate id (local reactive read; returns stop()). */`,
         `    watch${agg.id}ById: (id: string, cb: (rows: Row<${agg.id}Data>[]) => void, opts?: { intervalMs?: number }) =>`,
-        `      holon.watchById(id, cb as (rows: unknown) => void, opts),`,
+        foreignRefFields.length > 0
+          ? `      holon.watchById(id, ((rows: Row<${agg.id}Data>[]) => cb(_hydrateRows(rows))) as (rows: unknown) => void, opts),`
+          : `      holon.watchById(id, cb as (rows: unknown) => void, opts),`,
       );
     }
 

package/src/fields.ts

@@ -268,6 +268,21 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
   readonly clearRequires?: string;
   /** For `t.ref` cross-workspace edges: the foreign workspace id, if any. */
   readonly refWorkspace?: string;
+  /**
+   * `t.foreignRef({ workspace, target })` — a TYPED CROSS-WORKSPACE LOCATOR (not an atomic FK). Stored as
+   * the foreign aggregate's id STRING (kind `"ref"`, zero kernel change); this meta names WHERE the foreign
+   * workspace id lives (`workspaceField` — a sibling field on THIS aggregate, so the target workspace is
+   * DYNAMIC) + the TARGET aggregate/domain (typed codegen). The read model surfaces it as a typed locator
+   * (`ForeignRef<TargetData>` = `{ id, workspace }`), NEVER auto-cloning the other holon; the generated
+   * client's `resolve(nomos)`/`watch(nomos)` open the foreign workspace on demand. Law that DEPENDS on the
+   * foreign fact opts into attested evidence separately (`trustSource`/`.readsFrom`). Present ⇒ codegen emits
+   * the locator; absent ⇒ a plain `t.ref`. Additive IR (`nomosForeignRefs`), era-safe.
+   */
+  readonly foreignRef?: {
+    readonly workspaceField: string;
+    readonly targetAggregateId: string;
+    readonly targetDomain?: string;
+  };
   /** For `t.ref` (the target) AND `t.hasMany` (the child type): the related aggregate's wire id. */
   readonly refAggregateId?: string;
   /** For `t.hasMany(Child).via(backref)`: the back-reference field NAME on the child. Virtual. */
@@ -396,7 +411,14 @@ function makeField<T, K extends FieldKind = FieldKind>(
   driver: Driver,
   extra: {
     refWorkspace?: string;
+    foreignRef?: { workspaceField: string; targetAggregateId: string; targetDomain?: 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;
@@ -422,6 +444,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     ...(extra.facet !== undefined ? { facet: extra.facet } : {}),
     ...(extra.refWorkspace !== undefined ? { refWorkspace: extra.refWorkspace } : {}),
     ...(extra.refAggregateId !== undefined ? { refAggregateId: extra.refAggregateId } : {}),
+    ...(extra.foreignRef !== undefined ? { foreignRef: extra.foreignRef } : {}),
     ...(extra.viaField !== undefined ? { viaField: extra.viaField } : {}),
     ...(extra.mapValueKind !== undefined ? { mapValueKind: extra.mapValueKind } : {}),
     ...(extra.jsonShape !== undefined ? { jsonShape: extra.jsonShape } : {}),
@@ -496,6 +519,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;
 }
 
@@ -732,6 +770,30 @@ export const t = {
    *    routing is the kernel's job.
    */
   ref: refImpl as RefFn,
+  /**
+   * `t.foreignRef({ workspace, target })` — a TYPED CROSS-WORKSPACE LOCATOR. Use for an edge into ANOTHER
+   * holon (a catalogue listing shared into an estate, a media/blob ref, a home's "accessible estate" card):
+   * the field STORES the foreign aggregate's id, `workspace` names a SIBLING field holding the foreign
+   * workspace id (so the target workspace is dynamic), and `target` types it to the foreign aggregate. The
+   * read model surfaces a typed `ForeignRef` locator ({ id, workspace }); it does NOT clone/open the other
+   * holon — the generated client's `resolve(nomos)`/`watch(nomos)` do that on demand. It is a LOCATOR, not a
+   * database join: law that depends on the foreign FACT opts into attested evidence via `trustSource` +
+   * `.readsFrom(...)`. Same-workspace edges stay `t.ref`/`t.hasMany`; this is the honest cross-workspace twin.
+   */
+  foreignRef(opts: {
+    workspace: string;
+    target: AggregateHandle<string, Record<string, Field>>;
+    domain?: string;
+  }): Field<string, "ref"> {
+    return makeField<string, "ref">("ref", z.string(), Conflict, {
+      refAggregateId: opts.target.id,
+      foreignRef: {
+        workspaceField: opts.workspace,
+        targetAggregateId: opts.target.id,
+        ...(opts.domain !== undefined ? { targetDomain: opts.domain } : {}),
+      },
+    });
+  },
   /**
    * A 1:N INVERSE relation — the read side of a `t.ref` on the child (`aggregate_lifecycle_and_relations.md`).
    * `t.hasMany(Child).via("parent")` on a Parent declares "the Children whose `parent` ref points here".
@@ -740,17 +802,26 @@ 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>>): {
-    via(backref: string): Field<string[], "hasMany">;
-  } {
+  hasMany: (function 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,
         });
       },
     };
+  }) as {
+    /** 1:N inverse by aggregate HANDLE. */
+    (child: AggregateHandle<string, Record<string, Field>>): { via(backref: string): Field<string[], "hasMany"> };
+    /** 1:N inverse by a THUNK (`t.hasMany(() => Child)`) — a DISTINCT overload so the arrow's return is
+     *  contextually the WIDE handle, breaking the bidirectional `const` cycle (no circular-`any`). */
+    (child: () => AggregateHandle<string, Record<string, Field>>): { via(backref: string): Field<string[], "hasMany"> };
   },
   /**
    * A content-addressed EVIDENCE reference (`evidence.md` §6/§9.2). The authored value is
@@ -768,8 +839,15 @@ export const t = {
   },
 };
 
+type RefTarget = AggregateHandle<string, Record<string, Field>> | (() => AggregateHandle<string, Record<string, Field>>);
+
 interface RefFn {
+  /** Same-workspace reference by aggregate HANDLE. */
   (target: AggregateHandle<string, Record<string, Field>>): Field<string, "ref">;
+  /** Same-workspace reference by a THUNK (`t.ref(() => Agg)`) — breaks a bidirectional declaration cycle.
+   *  A DISTINCT overload (not a union arm) so TS contextually types the arrow's return as the WIDE handle,
+   *  which is what keeps `const A = ...ref(() => B)` / `const B = ...ref(() => A)` from a circular-`any`. */
+  (target: () => AggregateHandle<string, Record<string, Field>>): Field<string, "ref">;
   (
     workspaceId: string,
     target: AggregateHandle<string, Record<string, Field>>,
@@ -777,7 +855,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 +865,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 });
 }
 

package/src/usd.ts

@@ -585,6 +585,24 @@ export interface UsdLayer {
    * (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).
    */
+  /**
+   * MULTI-WORKSPACE LOCATORS (`t.foreignRef`) — the self-describing cross-workspace edges this domain
+   * declares: `{aggregate, field, workspaceField, target, targetDomain?}` sorted by (aggregate, field).
+   * Descriptive law metadata (codegen emits a typed `ForeignRef` locator + resolve/watch; proof knows the
+   * edge shape without proving the concrete foreign workspace). A LOCATOR, not an atomic FK — law that
+   * depends on the foreign fact opts into attested evidence separately (`nomosAttestedReadGate`). OMITTED
+   * when the domain declares no foreignRef (era-safe — hash-identical to before this key existed).
+   */
+  readonly nomosForeignRefs?: {
+    readonly v: 1;
+    readonly refs: readonly {
+      readonly aggregate: string;
+      readonly field: string;
+      readonly workspaceField: string;
+      readonly target: string;
+      readonly targetDomain?: string;
+    }[];
+  };
   readonly nomosValueObjects?: {
     readonly v: 1;
     readonly valueObjects: readonly import("./fields.js").ValueObjectDescriptor[];
@@ -1329,6 +1347,17 @@ export function emitUsd(
       const voUsages = collectValueObjectUsages(
         l.module.aggregates as unknown as readonly { id: string; fields: Record<string, import("./fields.js").Field> }[],
       );
+      // MULTI-WORKSPACE LOCATORS: collect every `t.foreignRef` field across the module's aggregates.
+      const foreignRefList: { aggregate: string; field: string; workspaceField: string; target: string; targetDomain?: string }[] = [];
+      for (const agg of l.module.aggregates) {
+        for (const [fname, f] of Object.entries((agg as { fields: Record<string, { foreignRef?: { workspaceField: string; targetAggregateId: string; targetDomain?: string } }> }).fields)) {
+          const fr = f.foreignRef;
+          if (fr === undefined) continue;
+          foreignRefList.push({ aggregate: agg.id, field: fname, workspaceField: fr.workspaceField, target: fr.targetAggregateId, ...(fr.targetDomain !== undefined ? { targetDomain: fr.targetDomain } : {}) });
+        }
+      }
+      foreignRefList.sort((a, b) => (a.aggregate !== b.aggregate ? (a.aggregate < b.aggregate ? -1 : 1) : a.field < b.field ? -1 : a.field > b.field ? 1 : 0));
+      const nomosForeignRefs = foreignRefList.length > 0 ? { v: 1 as const, refs: foreignRefList } : undefined;
       const nomosValueObjects =
         moduleValueObjects !== undefined && moduleValueObjects.length > 0
           ? {
@@ -1388,6 +1417,7 @@ export function emitUsd(
         ...(nomosParentAttestedBirth !== undefined ? { nomosParentAttestedBirth } : {}),
         ...(nomosVerifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll } : {}),
         ...(eraCertGate !== undefined ? { nomosEraCertGate: eraCertGate } : {}),
+        ...(nomosForeignRefs !== undefined ? { nomosForeignRefs } : {}),
         ...(nomosValueObjects !== undefined ? { nomosValueObjects } : {}),
         ...(Object.keys(visAggregates).length > 0
           ? { nomosReadVisibility: { v: 1 as const, aggregates: visAggregates } }

package/src/usd_layers.ts

@@ -206,6 +206,9 @@ function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string):
     ...(layer.nomosValueObjects !== undefined
       ? [`${indent}custom string nomos:valueObjectsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosValueObjects)))}`]
       : []),
+    ...(layer.nomosForeignRefs !== undefined
+      ? [`${indent}custom string nomos:foreignRefsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosForeignRefs)))}`]
+      : []),
   ];
 }
 
@@ -948,7 +951,9 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         valueObjects = { v: 1, valueObjects: descs, ...(uses.length > 0 ? { usages: uses } : {}) };
       }
     }
-    return {
+        let foreignRefs: UsdLayer["nomosForeignRefs"];
+    for (const l of stack) { if (l.nomosForeignRefs !== undefined) foreignRefs = l.nomosForeignRefs; }
+return {
       path,
       prims: [...prims.keys()].sort().map((p) => prims.get(p)!),
       ...(identityManifest !== undefined ? { nomosIdentityManifest: identityManifest } : {}),
@@ -973,6 +978,7 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
       ...(verifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll: verifiedFirstEnroll } : {}),
       ...(eraCertGate !== undefined ? { nomosEraCertGate: eraCertGate } : {}),
       ...(valueObjects !== undefined ? { nomosValueObjects: valueObjects } : {}),
+      ...(foreignRefs !== undefined ? { nomosForeignRefs: foreignRefs } : {}),
     };
   });
 
@@ -1112,6 +1118,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const verifiedFirstEnrollByDomain = new Map<string, UsdLayer["nomosVerifiedFirstEnroll"]>();
   const eraCertGateByDomain = new Map<string, UsdLayer["nomosEraCertGate"]>();
   const valueObjectsByDomain = new Map<string, UsdLayer["nomosValueObjects"]>();
+  const foreignRefsByDomain = new Map<string, UsdLayer["nomosForeignRefs"]>();
   for (const p of prims) {
     if (p.attrs.get("nomos:kind") === "domain") {
       const domain = attrString(p, "nomos:domain");
@@ -1207,6 +1214,10 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof voHex === "string") {
         valueObjectsByDomain.set(domain, JSON.parse(unhexUtf8(voHex)) as UsdLayer["nomosValueObjects"]);
       }
+      const frHex = p.attrs.get("nomos:foreignRefsHex");
+      if (typeof frHex === "string") {
+        foreignRefsByDomain.set(domain, JSON.parse(unhexUtf8(frHex)) as UsdLayer["nomosForeignRefs"]);
+      }
     }
   }
 
@@ -1317,6 +1328,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const verifiedFirstEnroll = verifiedFirstEnrollByDomain.get(domain);
       const eraCertGate = eraCertGateByDomain.get(domain);
       const valueObjects = valueObjectsByDomain.get(domain);
+      const foreignRefs2 = foreignRefsByDomain.get(domain);
       return {
         path: `/Nomos/${domain}`,
         prims: [...b.prims].sort(byPath),
@@ -1342,6 +1354,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(verifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll: verifiedFirstEnroll } : {}),
         ...(eraCertGate !== undefined ? { nomosEraCertGate: eraCertGate } : {}),
         ...(valueObjects !== undefined ? { nomosValueObjects: valueObjects } : {}),
+      ...(foreignRefs2 !== undefined ? { nomosForeignRefs: foreignRefs2 } : {}),
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));