@githolon/dsl 0.63.0 → 0.65.0

package/dart/lib/src/webview_bridge.dart

@@ -19,7 +19,13 @@ import 'dart:convert';
 import 'dart:math';
 
 import 'package:nomos_types/nomos_types.dart'
-    show nomosErrorFromInfo, NomosTraceContext, NomosErrorInfo;
+    show
+        nomosErrorFromInfo,
+        NomosTraceContext,
+        NomosErrorInfo,
+        NomosForeignReader,
+        NomosForeignWorkspaceReader,
+        ForeignAttestation;
 
 /// The protocol version the runner and the bridge agree on (`webview-runner.mjs` `WEBVIEW_BRIDGE_VERSION`).
 const int kWebviewBridgeVersion = 1;
@@ -840,6 +846,15 @@ class NomosBridge {
   NomosSession session(String workspace) =>
       _sessionViews.putIfAbsent(workspace, () => NomosSession(this, workspace));
 
+  /// A [NomosForeignReader] backed by THIS bridge's multi-workspace plane — what a generated `ForeignRef`
+  /// (a `t.foreignRef` cross-workspace locator) resolves against: `row.data.listing.resolve(bridge.foreignReader())`.
+  /// `foreignWorkspace(ws).queryById(id)` MOUNTS the foreign workspace on this device's plane ON DEMAND
+  /// ([connect] is idempotent — "first connect wins", and `allowUnborn` so a missing workspace reads empty →
+  /// `ForeignNotFound`, not a throw) and reads it. [cloud] is the cloud the foreign workspaces sync from
+  /// (usually the same cloud your primary workspace uses); omit for a purely local plane. This is a LOCATOR
+  /// resolver, not a foreign key — the foreign holon is sovereign, mounted only when you choose to resolve.
+  NomosForeignReader foreignReader({String? cloud}) => _BridgeForeignReader(this, cloud);
+
   /// The workspace names [connect] has opened on this plane (the live sessions).
   List<String> get connectedSessions => List.unmodifiable(_sessionNames);
 
@@ -1728,3 +1743,74 @@ class NomosSession extends NomosBridge {
   @override
   List<Map<String, Object?>> get recentSpans => parent.recentSpans;
 }
+
+/// THE BRIDGE-BACKED FOREIGN READER — a [NomosForeignReader] over a device's multi-workspace [NomosBridge]
+/// plane. Constructed via `bridge.foreignReader({cloud})`; a generated `ForeignRef` resolves against it.
+/// Mounting a foreign workspace has real cost (it opens + syncs that holon on demand) — which is the honest
+/// price of a cross-workspace read, paid only when you resolve, never up front.
+class _BridgeForeignReader implements NomosForeignReader {
+  _BridgeForeignReader(this._bridge, this._cloud);
+  final NomosBridge _bridge;
+  final String? _cloud;
+
+  @override
+  NomosForeignWorkspaceReader foreignWorkspace(String workspace) =>
+      _BridgeForeignWorkspaceReader(_bridge, workspace, _cloud);
+
+  // No attestation hook by default — `ForeignRef.attest` throws unless the app wires the attested-read lane
+  // (trustSource + .readsFrom). That gate is the security model (a locator is not a foreign key), not a
+  // limitation: unverifiable "evidence" would be the real footgun.
+  @override
+  Future<ForeignAttestation> Function(String workspace, String id, String type)? get attestForeign => null;
+}
+
+/// A per-workspace read handle on the bridge plane — mounts [_workspace] lazily on the first read.
+class _BridgeForeignWorkspaceReader implements NomosForeignWorkspaceReader {
+  _BridgeForeignWorkspaceReader(this._bridge, this._workspace, this._cloud);
+  final NomosBridge _bridge;
+  final String _workspace;
+  final String? _cloud;
+  Future<void>? _mounting;
+
+  // Mount ONCE (idempotent on the plane — "first connect wins"). `allowUnborn` so a not-yet-born foreign
+  // workspace reads empty (→ ForeignNotFound) rather than throwing. A genuinely unreachable cloud throws,
+  // which resolveResult classifies as ForeignUnreachable.
+  Future<void> _ensureMounted() =>
+      _mounting ??= _bridge.connect(
+        cloud: _cloud,
+        workspace: _workspace,
+        session: _workspace,
+        allowUnborn: true,
+      );
+
+  @override
+  Future<List<Map<String, dynamic>>> queryById(String id) async {
+    await _ensureMounted();
+    return _bridge.session(_workspace).queryById(id);
+  }
+
+  // Reactive: emit the current value, then re-read on every plane sync tick (the foreign workspace's folds
+  // arrive as sync events). Chatty but correct — a foreignRef watch is a convenience, not a hot path.
+  @override
+  Stream<List<Map<String, dynamic>>>? watchById(String id) {
+    late final StreamController<List<Map<String, dynamic>>> ctrl;
+    StreamSubscription<Object?>? sub;
+    Future<void> emit() async {
+      try {
+        if (!ctrl.isClosed) ctrl.add(await queryById(id));
+      } catch (_) {
+        // a transient read failure is not fatal to the subscription — the next sync tick retries.
+      }
+    }
+    ctrl = StreamController<List<Map<String, dynamic>>>(
+      onListen: () {
+        unawaited(emit());
+        sub = _bridge.session(_workspace).syncEvents.listen((_) => unawaited(emit()));
+      },
+      onCancel: () async {
+        await sub?.cancel();
+      },
+    );
+    return ctrl.stream;
+  }
+}

package/dart_types/lib/nomos_types.dart

@@ -27,3 +27,7 @@ export 'src/schema_validation.dart';
 export 'src/aggregate_meta.dart';
 export 'src/error_info.dart';
 export 'src/errors.dart';
+// The FOREIGN-REF locator runtime (t.foreignRef): the typed cross-workspace `ForeignRef<T>` + the structural
+// `NomosForeignReader`/`NomosForeignWorkspaceReader` read surfaces + the named resolve outcomes. Pure data +
+// abstract interfaces (no bridge) — so both the layered TYPES package and nomos_client resolve them.
+export 'src/foreign_ref.dart';

package/dart_types/lib/src/foreign_ref.dart

@@ -0,0 +1,214 @@
+// NOMOS — the FOREIGN-REF runtime (t.foreignRef): a TYPED CROSS-WORKSPACE LOCATOR, the Dart twin of the
+// TS client's `ForeignRef`/`NomosForeignReader` (codegen_ts.ts). A `t.foreignRef({ workspace, target })`
+// field stores the foreign aggregate's id, alongside a SIBLING field on the same aggregate holding the
+// foreign WORKSPACE id (so the target workspace is dynamic per row). The generated read model surfaces the
+// field as a `ForeignRef<T>` — NOT a raw string — so the app can `resolve`/`watch`/`attest` the target on
+// demand WITHOUT cloning the other holon: it opens the foreign workspace's read surface lazily.
+//
+// A ForeignRef is a LOCATOR, not an atomic foreign key: reading it is informational (resolve/exists/watch);
+// only `attest` is law-grade (signed evidence the reference resolves) and it works ONLY when the law
+// DECLARES the dependency (`trustSource` + `.readsFrom`) — otherwise it throws, by design.
+//
+// These types live in the pure `nomos_types` core (no bridge, no lifecycle) so BOTH the layered TYPES
+// package (frontend-safe) AND the runtime `nomos_client` package resolve them; `nomos_client` re-exports
+// this barrel, and its `NomosBridge` implements [NomosForeignReader] over the device's multi-workspace plane.
+library;
+
+/// Reads a FOREIGN workspace on demand — the surface a [ForeignRef] resolves against. It is STRUCTURAL: any
+/// object with this shape works. `nomos_client`'s `NomosBridge` implements it over the device's local
+/// multi-workspace plane (`bridge.session(ws).queryById(id)`, mounting the workspace lazily); the TS twin is
+/// the `openRealm()` reader. A plain single-workspace holon is NOT one — pass the multi-workspace reader.
+abstract class NomosForeignReader {
+  /// A read handle for [workspace] (mounted on the local plane on demand, never cloned).
+  NomosForeignWorkspaceReader foreignWorkspace(String workspace);
+
+  /// The LAW-GRADE attestation hook — non-`null` ONLY when the app wires the attested-read lane
+  /// (`trustSource` + `.readsFrom`). `null` here ⇒ [ForeignRef.attest] throws, by design (a locator is not an
+  /// atomic foreign key). Override in a reader that carries the attested-read lane.
+  Future<ForeignAttestation> Function(String workspace, String id, String type)?
+      get attestForeign => null;
+}
+
+/// One foreign workspace's by-id read surface (used by [ForeignRef.resolve]/[ForeignRef.watch]). Returns the
+/// RAW projection rows (`[{type,id,data}, …]`) — the ForeignRef decodes the matching row's flat `data` map
+/// via the target `fromJson` it captured at construction (the same shape [NomosReads.decodeRows] consumes).
+abstract class NomosForeignWorkspaceReader {
+  /// The projection rows for kernel aggregate [id] (a by-id read). Each row is a `{type, id, data}` map, its
+  /// `data` the flat already-decoded field map. An EMPTY list ⇒ the target has not been folded / is absent.
+  Future<List<Map<String, dynamic>>> queryById(String id);
+
+  /// OPTIONAL reactive by-id read — the target's rows re-emitted on each projection tick. `null` when this
+  /// reader offers no watch lane (then [ForeignRef.watch] calls back once with `null` and no-ops).
+  Stream<List<Map<String, dynamic>>>? watchById(String id) => null;
+}
+
+/// The OUTCOME of a [ForeignRef.resolveResult], with the reason NAMED — a foreign read can come back empty
+/// because the target does not exist, the reader lacks access, or the holon is unreachable, and those are
+/// very different. [ForeignRef.resolve] collapses them all to `null`; use this when the WHY matters.
+sealed class ForeignResolveResult<T> {
+  const ForeignResolveResult();
+}
+
+/// The target resolved — its typed [row] is present.
+class ForeignFound<T> extends ForeignResolveResult<T> {
+  final T row;
+  const ForeignFound(this.row);
+}
+
+/// The reference does not resolve to a folded aggregate (no such id in the target workspace).
+class ForeignNotFound<T> extends ForeignResolveResult<T> {
+  const ForeignNotFound();
+}
+
+/// The read was REFUSED — the reader's error looked like an auth/permission denial (best-effort classified).
+class ForeignDenied<T> extends ForeignResolveResult<T> {
+  final Object error;
+  const ForeignDenied(this.error);
+}
+
+/// The foreign holon could not be reached (any error that did not look like a denial).
+class ForeignUnreachable<T> extends ForeignResolveResult<T> {
+  final Object error;
+  const ForeignUnreachable(this.error);
+}
+
+/// LAW-GRADE signed evidence that a [ForeignRef] resolves — returned by [ForeignRef.attest] on the
+/// attested-read lane (`trustSource` + `.readsFrom`). Pure data.
+class ForeignAttestation {
+  /// The foreign aggregate's id the attestation is over.
+  final String id;
+
+  /// The foreign workspace the attestation is over.
+  final String workspace;
+
+  /// Whether the target existed at attestation time.
+  final bool exists;
+
+  /// The opaque signed attestation blob (the law-grade evidence).
+  final String attestation;
+
+  const ForeignAttestation({
+    required this.id,
+    required this.workspace,
+    required this.exists,
+    required this.attestation,
+  });
+}
+
+/// A TYPED CROSS-WORKSPACE LOCATOR (`t.foreignRef`) — the foreign aggregate's [id] + the foreign [workspace]
+/// (from the declared sibling workspace field) + the target aggregate [type], plus the target `fromJson`
+/// captured at construction so [resolve]/[watch] can DECODE it. NOT an atomic foreign key: [resolve]/[watch]
+/// open the foreign holon ON DEMAND (no clone). [exists] is the cheap "is it still there?" check; [attest] is
+/// the law-grade one (see [ForeignAttestation]). The generated read model builds these from a projection row
+/// (the raw id field + the sibling workspace field); [id] stays the raw stored id.
+class ForeignRef<T> {
+  /// The foreign aggregate's id (this field's stored value).
+  final String id;
+
+  /// The foreign workspace id (from the declared sibling workspace field).
+  final String workspace;
+
+  /// The foreign aggregate type this locator points at.
+  final String type;
+
+  /// The target's decoder (the aggregate `fromJson` factory), applied to a resolved row's flat `data` map.
+  final T Function(Map<String, dynamic> data, [String id]) _decode;
+
+  const ForeignRef({
+    required this.id,
+    required this.workspace,
+    required this.type,
+    required T Function(Map<String, dynamic> data, [String id]) fromJson,
+  }) : _decode = fromJson;
+
+  /// Pick the matching row (by [id], else the first) from a raw `{type,id,data}` row list and decode its flat
+  /// `data` via the captured `fromJson` (threading the row `id`, mirroring [NomosReads.decodeRows]). `null`
+  /// when the list is empty or the matched row carries no object `data`.
+  T? _decodeRows(List<Map<String, dynamic>> rows) {
+    if (rows.isEmpty) return null;
+    Map<String, dynamic>? match;
+    for (final r in rows) {
+      if (r['id'] == id) {
+        match = r;
+        break;
+      }
+    }
+    match ??= rows.first;
+    final data = match['data'];
+    if (data is! Map<String, dynamic>) return null;
+    final rawId = match['id'];
+    final rowId = rawId is String ? rawId : (rawId?.toString() ?? id);
+    return _decode(data, rowId);
+  }
+
+  /// THE LOOKUP WITH THE OUTCOME NAMED — found / not-found / denied / unreachable. Opens the foreign
+  /// workspace's read surface, reads the target by [id], and classifies an empty/errored read (a thrown
+  /// auth/permission-looking error ⇒ denied; any other throw ⇒ unreachable; an empty read ⇒ not-found).
+  Future<ForeignResolveResult<T>> resolveResult(NomosForeignReader nomos) async {
+    if (id.isEmpty || workspace.isEmpty) return ForeignNotFound<T>();
+    try {
+      final rows = await nomos.foreignWorkspace(workspace).queryById(id);
+      final row = _decodeRows(rows);
+      return row != null ? ForeignFound<T>(row) : ForeignNotFound<T>();
+    } catch (error) {
+      final m = error.toString().toLowerCase();
+      final denied = RegExp(r'forbid|denied|permission|unauthor|not permitted|403|401').hasMatch(m);
+      return denied ? ForeignDenied<T>(error) : ForeignUnreachable<T>(error);
+    }
+  }
+
+  /// THE LOOKUP (the 99% case): open the foreign workspace + read the target by [id] — on demand, no clone.
+  /// Returns `null` for ANY empty outcome (not-found / denied / unreachable); use [resolveResult] for the WHY.
+  Future<T?> resolve(NomosForeignReader nomos) async {
+    final r = await resolveResult(nomos);
+    return r is ForeignFound<T> ? r.row : null;
+  }
+
+  /// Subscribe to the target's read model across the workspace boundary. Returns an unsubscribe fn. Calls
+  /// [cb] with `null` once (and no-ops) when the id/workspace is empty or the reader offers no watch lane.
+  void Function() watch(NomosForeignReader nomos, void Function(T? row) cb) {
+    if (id.isEmpty || workspace.isEmpty) {
+      cb(null);
+      return () {};
+    }
+    final stream = nomos.foreignWorkspace(workspace).watchById(id);
+    if (stream == null) {
+      cb(null);
+      return () {};
+    }
+    final sub = stream.listen(
+      (rows) => cb(_decodeRows(rows)),
+      onError: (Object _) => cb(null),
+    );
+    return sub.cancel;
+  }
+
+  /// Cheap existence check — does the referenced target still exist? (found ⇒ `true`; anything else ⇒ `false`).
+  Future<bool> exists(NomosForeignReader nomos) async =>
+      (await resolveResult(nomos)) is ForeignFound<T>;
+
+  /// 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 atomic FK).
+  Future<ForeignAttestation> attest(NomosForeignReader nomos) {
+    final hook = nomos.attestForeign;
+    if (hook == null) {
+      throw StateError(
+        'attest() needs the attested-read lane — declare trustSource("$workspace", …) + '
+        '.readsFrom(…) on the directive whose law depends on this reference '
+        '(a foreignRef is a locator, not an atomic foreign key)',
+      );
+    }
+    return hook(workspace, id, type);
+  }
+
+  @override
+  bool operator ==(Object other) =>
+      other is ForeignRef<T> &&
+      other.id == id &&
+      other.workspace == workspace &&
+      other.type == type;
+
+  @override
+  int get hashCode => Object.hash(id, workspace, type);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.63.0",
+  "version": "0.65.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_dart.ts

@@ -426,6 +426,19 @@ interface AggFieldSpec {
    * non-ref field (or a ref whose target type is unknown — falls back to `String`).
    */
   refIdClass?: string;
+  /**
+   * For a `t.foreignRef` field (a TYPED CROSS-WORKSPACE LOCATOR, not an atomic FK): the target
+   * aggregate's Dart class (e.g. `CatalogueListing`). The field's Dart type is `ForeignRef<Target>`
+   * (from the shared `nomos_types` runtime), NOT the target's typed-id class — so the app can
+   * `resolve`/`watch`/`attest` the foreign target on demand. `undefined` for a plain same-workspace
+   * `ref` field (which stays its target's typed id class via {@link refIdClass}).
+   */
+  foreignRefTarget?: string;
+  /**
+   * For a `t.foreignRef` field: the wire name of the SIBLING field on THIS aggregate holding the foreign
+   * WORKSPACE id (the locator's `workspace`, dynamic per row). `undefined` for a non-foreignRef field.
+   */
+  foreignRefWorkspaceField?: string;
   /**
    * Whether the field is OPTIONAL on a folded aggregate — derived from the DSL field
    * schema (GAP 1). A `set`/`map` is a COLLECTION: it is ALWAYS empty-defaultable
@@ -726,7 +739,23 @@ function aggFieldSpec(
         ...(field.jsonShape !== undefined ? { jsonShape: field.jsonShape } : {}),
       };
     case "ref": {
-      // A `ref` field carries ANOTHER aggregate's id — type it as that target's
+      // A `t.foreignRef` field is a TYPED CROSS-WORKSPACE LOCATOR (not an atomic FK): surface it as
+      // `ForeignRef<Target>` (the shared `nomos_types` runtime type) — the raw stored id + the sibling
+      // workspace field give the app `resolve`/`watch`/`attest` on demand, without cloning the other holon.
+      // This takes precedence over the same-workspace typed-id path below.
+      if (field.foreignRef !== undefined) {
+        const target = field.foreignRef.targetAggregateId;
+        return {
+          name,
+          wireName,
+          kind: field.kind,
+          dartType: `ForeignRef<${target}>`,
+          optional,
+          foreignRefTarget: target,
+          foreignRefWorkspaceField: field.foreignRef.workspaceField,
+        };
+      }
+      // A plain same-workspace `ref` field carries ANOTHER aggregate's id — type it as that target's
       // TYPED id class (cross-aggregate ref typing), so e.g. a `Building.siteId`
       // ref is a `SiteId`, never a bare String. The target wire id is recorded on
       // the field (`refAggregateId`); fall back to `String` only if it is absent.
@@ -1910,6 +1939,26 @@ function collectionDefaultParam(s: AggFieldSpec): string {
  * spike path may emit); an `enum` is its bare wire string; a `json` field is the
  * stored JSON which may have re-parsed into a container (re-stringified to keep the
  * aggregate's `String` type). */
+/** The decode expression for a `t.foreignRef` field: build the shared `ForeignRef<Target>` locator from the
+ * row's raw id (this field's stored string) + the sibling workspace field (the foreign workspace id) +
+ * the target aggregate's `fromJson` decoder. `id` stays the raw stored id. An optional/absent field decodes
+ * `null`. Shared by the aggregate class and the read model (both surface the field as `ForeignRef<Target>`). */
+function foreignRefExpr(s: AggFieldSpec, aggregate: string): string {
+  const target = s.foreignRefTarget as string;
+  const wsField = s.foreignRefWorkspaceField as string;
+  const idReader = s.optional
+    ? `readStrOrNull(data, '${s.wireName}')`
+    : `readStr(data, '${aggregate}', '${s.wireName}')`;
+  // The sibling workspace field may not have folded yet — default it to '' (a locator with an empty
+  // workspace resolves to not-found, never throws).
+  const wsExpr = `(readStrOrNull(data, '${wsField}') ?? '')`;
+  const build = (idVar: string): string =>
+    `ForeignRef<${target}>(id: ${idVar}, workspace: ${wsExpr}, type: '${target}', fromJson: ${target}.fromJson)`;
+  return s.optional
+    ? `() { final v = ${idReader}; return v == null ? null : ${build("v")}; }()`
+    : build(idReader);
+}
+
 function parseField(s: AggFieldSpec, aggregate: string): string {
   // A `.optional()` scalar reads through the `…OrNull` tolerant reader (returns null
   // when the flat `data` lacks it — a freshly-folded aggregate need not have folded
@@ -1918,6 +1967,9 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
   const opt = s.optional;
   switch (s.kind) {
     case "ref": {
+      // A `t.foreignRef` field decodes to the shared `ForeignRef<Target>` locator (raw id + sibling
+      // workspace field + the target `fromJson`), not a typed-id class.
+      if (s.foreignRefTarget !== undefined) return foreignRefExpr(s, aggregate);
       // A ref reads its id STRING, then wraps it via `.fromRow` (NOT the public
       // `.fromMinted`, which asserts the type tag). A ref may
       // legitimately point at a not-yet-minted aggregate whose id carries no
@@ -2003,6 +2055,13 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
 function slotDecodeCallback(s: AggFieldSpec, mode: "aggregate" | "readModel"): string {
   switch (s.kind) {
     case "ref":
+      // A null-admitting `t.foreignRef` (exotic): the sibling workspace field is not reachable from this
+      // single leaf, so the locator carries the raw id with an empty workspace (resolves to not-found until
+      // read through the normal field path). A plain ref keeps its typed-id decode.
+      if (s.foreignRefTarget !== undefined) {
+        const t = s.foreignRefTarget;
+        return `(v) => ForeignRef<${t}>(id: v as String, workspace: '', type: '${t}', fromJson: ${t}.fromJson)`;
+      }
       return s.refIdClass !== undefined
         ? `(v) => ${s.refIdClass}.fromRow(v as String)`
         : `(v) => v as String`;
@@ -2066,6 +2125,9 @@ export function readModelClassName(aggregateType: string): string {
 function readModelDartType(s: AggFieldSpec): string {
   switch (s.kind) {
     case "ref":
+      // A `t.foreignRef` field surfaces as the typed cross-workspace `ForeignRef<Target>` locator; a plain
+      // same-workspace ref stays its target's typed-id class (or a bare String when the target is unknown).
+      if (s.foreignRefTarget !== undefined) return `ForeignRef<${s.foreignRefTarget}>`;
       return s.refIdClass ?? "String";
     case "json":
       // A `t.jsonObject()` leaf (`jsonShape:"object"`, e.g. `location`) is the DECODED
@@ -2128,6 +2190,9 @@ function parseReadModelField(s: AggFieldSpec, aggregate: string): string {
   const opt = s.optional;
   switch (s.kind) {
     case "ref": {
+      // A `t.foreignRef` field decodes to the shared `ForeignRef<Target>` locator (same as the aggregate
+      // class); a plain same-workspace ref stays its target's typed-id class.
+      if (s.foreignRefTarget !== undefined) return foreignRefExpr(s, aggregate);
       const reader = opt
         ? `readStrOrNull(data, '${s.wireName}')`
         : `readStr(data, '${aggregate}', '${s.wireName}')`;

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/compile_package_main.ts

@@ -423,6 +423,9 @@ const DART_SUPPORT_CORE_SRC = [
   // `<name>.client.dart` reference these through the barrel. No external pub deps.
   "error_info.dart",
   "errors.dart",
+  // The foreign-ref locator runtime (ForeignRef<T>/NomosForeignReader/…, t.foreignRef) — a generated read
+  // model with a `t.foreignRef` field references `ForeignRef<Target>` through the barrel, so it must vendor.
+  "foreign_ref.dart",
 ] as const;
 // The RUNTIME support files, vendored from `nomos_client` (dsl/dart/lib/src): the async WebView
 // bridge the generated `<name>.client.dart` drives, and the provider surface. Their

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,6 +411,7 @@ 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
@@ -428,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 } : {}),
@@ -753,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".
@@ -761,9 +802,9 @@ 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>> | (() => 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";
@@ -775,6 +816,12 @@ export const t = {
         });
       },
     };
+  }) 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
@@ -795,8 +842,12 @@ export const t = {
 type RefTarget = AggregateHandle<string, Record<string, Field>> | (() => AggregateHandle<string, Record<string, Field>>);
 
 interface RefFn {
-  /** Same-workspace reference. Pass a THUNK (`t.ref(() => Agg)`) to break a bidirectional declaration cycle. */
-  (target: RefTarget): Field<string, "ref">;
+  /** 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>>,

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));