@githolon/dsl 0.64.0 → 0.65.1

package/dart/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.43.0
+
+- `NomosBridge.foreignReader({cloud})` — a `NomosForeignReader` backed by the device's multi-workspace bridge
+  plane, so a generated `ForeignRef` (`t.foreignRef`) resolves against real data: it mounts the foreign
+  workspace on demand (`connect(session: ws, allowUnborn: true)`, idempotent) and reads it
+  (`session(ws).queryById(id)`); `watch` re-reads on each sync tick. A locator resolver, not a foreign key —
+  the foreign holon is mounted only when you resolve. Requires `nomos_types >= 0.1.1` (the `ForeignRef` types).
+
 ## 0.41.0
 - `NomosTestHarness` emits named phase-progress diagnostics (install → spawn runner → await ready → connect, plus per-session progress in `cluster`) and each `connect()` carries a `connectTimeout` (default 120s) that throws a NAMED remedy instead of hanging — so a multi-test AppSim run can tell install vs runner-wait vs session-block vs deadlock (co2 feedback).
 

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/pubspec.yaml

@@ -11,7 +11,7 @@ description: >-
   Nomos 2 Dart frontend types — the hand-written kernel wire types plus the
   code-generated per-domain aggregate + directive-payload types. (De)serializes
   the EXACT serde JSON the Rust kernel + projection produce/consume.
-version: 0.41.0
+version: 0.43.0
 
 environment:
   sdk: ^3.5.0
@@ -20,7 +20,7 @@ dependencies:
   # The pure-data core (wire types, offer codec, NomosReads, schema validation, error
   # info). nomos_client depends on and re-exports it, so existing imports are unchanged.
   # For local monorepo dev, pubspec_overrides.yaml points this at ../dart_types.
-  nomos_types: ^0.1.0
+  nomos_types: ^0.1.1
   json_schema: ^5.2.2
   crypto: ^3.0.0
 

package/dart_types/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.1.1
+
+- Add `t.foreignRef` runtime types: `ForeignRef<T>` (a typed cross-workspace locator), `NomosForeignReader` /
+  `NomosForeignWorkspaceReader`, the sealed `ForeignResolveResult<T>` (`ForeignFound`/`ForeignNotFound`/
+  `ForeignDenied`/`ForeignUnreachable`), and `ForeignAttestation`. Generated read models type a `foreignRef`
+  field as `ForeignRef<Target>`; `.resolve/.resolveResult/.watch/.exists` are the informational lookup,
+  `.attest` is gated on the attested-read lane. Purely additive.
+
 ## 0.1.0
 - Initial release. The pure-data core split out of `nomos_client`: kernel wire types,
   the offer codec, `NomosReads`, the tri-state `NomosSlot`, aggregate metadata, schema

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/dart_types/pubspec.yaml

@@ -11,7 +11,7 @@ description: >-
   Pure kernel wire/data types for Nomos Dart frontends — no transport, no bridge,
   no runtime. The hand-written serde-JSON-compatible types plus the offer codec,
   reactive read engine, schema validation, and data-only error/trace types.
-version: 0.1.0
+version: 0.1.1
 
 environment:
   sdk: ^3.5.0

package/package.json

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

package/src/codegen_dart.ts

@@ -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/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
@@ -671,6 +674,15 @@ function emitDart(
     writeGenerated(FRAMEWORK_FILE, generateDartDomain(shared.frameworkMod));
   }
 
+  // CROSS-DOMAIN `t.foreignRef` (auto import). A foreignRef field typed `ForeignRef<CatalogueListing>` +
+  // `CatalogueListing.fromJson` needs the TARGET aggregate's Dart class — which lives in the target DOMAIN's
+  // generated file. Within ONE package the compiler knows which domain owns each aggregate, so we auto-emit
+  // the import (no manual `dartImports` config). Map every aggregate id → its domain's generated file base.
+  const aggIdToDartFile = new Map<string, string>();
+  for (const m of modules) {
+    for (const agg of (m.aggregates as { id: string }[])) aggIdToDartFile.set(agg.id, m.name);
+  }
+
   // 2b. one generated file per composed domain — the TYPES (`<name>.dart`) + the async bridge
   //     CLIENT (`<name>.client.dart`, the Flutter sibling of `<name>.client.ts`).
   for (const mod of modules) {
@@ -681,7 +693,28 @@ function emitDart(
     // framework import. Only pass the import when this domain actually folds a framework symbol.
     const { modForDart, skips, foldsFramework } = domainDedupOpts(mod, shared);
     const domainFrameworkImport = foldsFramework ? frameworkImportUri : undefined;
-    const src = generateDartDomain(modForDart, {
+    // AUTO cross-domain foreignRef imports: for each foreignRef whose target aggregate lives in ANOTHER
+    // tenant domain, import that domain's generated file so `ForeignRef<Target>` + `Target.fromJson` resolve.
+    // A target that is framework-shared resolves via the frameworkImportUri (not in the tenant map), so it is
+    // skipped here. Merged with any manual `dartImports`; deduped by uri.
+    const foreignRefImportUris = new Set<string>();
+    for (const agg of (modForDart.aggregates as { fields: Record<string, { foreignRef?: { targetAggregateId: string } }> }[])) {
+      for (const f of Object.values(agg.fields)) {
+        const tid = f.foreignRef?.targetAggregateId;
+        if (tid === undefined) continue;
+        const targetFile = aggIdToDartFile.get(tid);
+        if (targetFile !== undefined && targetFile !== modForDart.name) foreignRefImportUris.add(`${targetFile}.dart`);
+      }
+    }
+    const mergedDartImports = [
+      ...(modForDart.dartImports ?? []),
+      ...[...foreignRefImportUris]
+        .filter((uri) => !(modForDart.dartImports ?? []).some((i) => i.uri === uri))
+        .sort()
+        .map((uri) => ({ uri })),
+    ];
+    const modForDartWithImports = mergedDartImports.length > 0 ? { ...modForDart, dartImports: mergedDartImports } : modForDart;
+    const src = generateDartDomain(modForDartWithImports, {
       ...skips,
       ...(domainFrameworkImport !== undefined ? { frameworkImportUri: domainFrameworkImport } : {}),
     });
@@ -854,18 +887,29 @@ function emitDartPackages(
   // ── the TYPES package — pure data, `nomos_types` only ──
   const typesGen = freshGenDir(packages.types);
   const typesSources = new Map<string, string>(); // fileBase → src (for alias validation + purity)
+  // The SIBLING generated type files a types-package file MAY import (a cross-domain `t.foreignRef` types its
+  // field as the target aggregate's class, which lives in the target domain's file). A sibling types file is
+  // still PURE (no runtime/bridge surface — the purity gate exists to keep nomos_client out, not to isolate
+  // domain files from each other; Dart allows type-import cycles for mutual refs).
+  const siblingTypeFiles = new Set<string>([...modules.map((m) => `${m.name}.dart`), `${FRAMEWORK_FILE}.dart`]);
   const writeTypes = (fileBase: string, src: string): void => {
     if (!src.includes(DART_PACKAGE_IMPORT)) {
       fail(`generated Dart for '${fileBase}' does not carry the expected support import — codegen_dart header drifted`);
     }
     const pure = src.replace(DART_PACKAGE_IMPORT, DART_TYPES_IMPORT);
-    // PURITY, fail-closed: only the nomos_types barrel + the relative framework file may be imported.
+    // PURITY, fail-closed: only the nomos_types barrel, the framework file, and SIBLING generated type files
+    // (cross-domain foreignRef targets) may be imported. Runtime/bridge surfaces (nomos_client) stay out.
     for (const line of pure.split("\n")) {
       const m = /^import\s+'([^']+)'/.exec(line.trim());
-      if (m !== null && m[1] !== "package:nomos_types/nomos_types.dart" && m[1] !== `${FRAMEWORK_FILE}.dart`) {
+      if (
+        m !== null &&
+        m[1] !== "package:nomos_types/nomos_types.dart" &&
+        m[1] !== `${FRAMEWORK_FILE}.dart` &&
+        !siblingTypeFiles.has(m[1]!)
+      ) {
         fail(
           `types-package purity: generated '${fileBase}.dart' imports '${m[1]}' — a types file may only ` +
-            `import the nomos_types core (runtime/bridge surfaces belong in the client package)`,
+            `import the nomos_types core, the framework file, or a sibling generated domain file`,
         );
       }
     }
@@ -876,11 +920,28 @@ function emitDartPackages(
   };
 
   if (shared.frameworkMod !== undefined) writeTypes(FRAMEWORK_FILE, generateDartDomain(shared.frameworkMod));
+  // CROSS-DOMAIN foreignRef (layered): map aggregate id → its domain's type file, so a foreignRef field's
+  // target class resolves via a sibling import (the purity gate now permits sibling type files).
+  const aggIdToTypeFile = new Map<string, string>();
+  for (const m of modules) for (const agg of (m.aggregates as { id: string }[])) aggIdToTypeFile.set(agg.id, m.name);
   const perDomain = modules.map((mod) => ({ mod, dd: domainDedupOpts(mod, shared) }));
   for (const { mod, dd } of perDomain) {
+    const frImports = new Set<string>();
+    for (const agg of (dd.modForDart.aggregates as { fields: Record<string, { foreignRef?: { targetAggregateId: string } }> }[])) {
+      for (const f of Object.values(agg.fields)) {
+        const tid = f.foreignRef?.targetAggregateId;
+        const tf = tid !== undefined ? aggIdToTypeFile.get(tid) : undefined;
+        if (tf !== undefined && tf !== dd.modForDart.name) frImports.add(`${tf}.dart`);
+      }
+    }
+    const merged = [
+      ...(dd.modForDart.dartImports ?? []),
+      ...[...frImports].filter((uri) => !(dd.modForDart.dartImports ?? []).some((i) => i.uri === uri)).sort().map((uri) => ({ uri })),
+    ];
+    const modForTypes = merged.length > 0 ? { ...dd.modForDart, dartImports: merged } : dd.modForDart;
     writeTypes(
       mod.name,
-      generateDartDomain(dd.modForDart, {
+      generateDartDomain(modForTypes, {
         ...dd.skips,
         ...(dd.foldsFramework ? { frameworkImportUri: `${FRAMEWORK_FILE}.dart` } : {}),
       }),