@githolon/dsl 0.101.5 → 0.102.0

package/dart/test/vo_read_typing_test.dart

@@ -12,7 +12,7 @@ library;
 
 import 'dart:io';
 
-import 'package:nomos_client/nomos_headless.dart';
+import 'package:nomos_client/src/nms_conformance_runtime.dart';
 import 'package:test/test.dart';
 
 // The fixture's GENERATED Dart read models (support: "package" → imports package:nomos_client).
@@ -22,10 +22,14 @@ String get _root => '${Directory.current.path}/../..';
 String get _repoEntry => '$_root/cloud/web-client/runner/node-entry.ts';
 String get _deployJson =>
     '$_root/bench/scale/fixtures/vo-read-typing/build/vo-read-typing.deploy.json';
-String get _runtimeDir => '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+String get _runtimeDir =>
+    Platform.environment['NOMOS_DART_RUNTIME'] ??
+    Platform.environment['NOMOS_OFFLINE_RUNTIME'] ??
+    '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
 
 String? _missingPrereq() {
-  if (!File(_repoEntry).existsSync()) return 'in-repo runner not found at $_repoEntry';
+  if (!File(_repoEntry).existsSync())
+    return 'in-repo runner not found at $_repoEntry';
   if (!File(_deployJson).existsSync()) {
     return 'compile the fixture: cd bench/scale/fixtures/vo-read-typing && npx nomos-compile';
   }
@@ -37,7 +41,9 @@ String? _missingPrereq() {
 }
 
 void main() {
-  test('OFFLINE: nested VO + map-of-VO read back TYPED via query, by-id, and watch', () async {
+  test(
+      'OFFLINE: nested VO + map-of-VO read back TYPED via query, by-id, and watch',
+      () async {
     final skip = _missingPrereq();
     if (skip != null) {
       markTestSkipped(skip);
@@ -58,24 +64,33 @@ void main() {
         'name': 'HQ',
         'location': {
           'address': {'streetAddress': '1 High St', 'city': 'Leeds'},
-          'point': {'type': 'Point', 'coordinates': [-1.55, 53.8]},
+          'point': {
+            'type': 'Point',
+            'coordinates': [-1.55, 53.8]
+          },
         },
         'rooms': {
           'atrium': {
             'address': {'streetAddress': '1 High St', 'city': 'Leeds'},
-            'point': {'type': 'Point', 'coordinates': [-1.5, 53.79]},
+            'point': {
+              'type': 'Point',
+              'coordinates': [-1.5, 53.79]
+            },
           },
         },
       },
     );
     expect(outcome.created, hasLength(1));
-    final siteId = SiteId.fromRow(outcome.created.single.id);
+    // Deliberately raw framework-mechanism probe: generated tenant applications retain the typed
+    // NomosRef<Site>; this test exercises queryById/watchById beneath that sealed surface.
+    final siteId = outcome.created.single.id;
 
     // ── (1) declared query → typed Site, typed nested VO + typed map-of-VO ──
     final qRows = await harness.bridge.query('sitesByName', {'name': 'HQ'});
     expect(qRows, hasLength(1));
-    final fromQuery =
-        Site.fromJson((qRows.first['data'] as Map).cast<String, dynamic>(), (qRows.first['id'] ?? '').toString());
+    final fromQuery = Site.fromJson(
+        (qRows.first['data'] as Map).cast<String, dynamic>(),
+        (qRows.first['id'] ?? '').toString());
 
     expect(fromQuery.name, 'HQ');
     // Typed nested VO access — no map indexing, no casts.
@@ -90,18 +105,21 @@ void main() {
     expect(fromQuery.rooms['atrium']!.address!.city, 'Leeds');
 
     // ── (2) by-id read → same typed shape ──
-    final byIdRows = await harness.bridge.queryById(siteId.value);
+    final byIdRows = await harness.bridge.queryById(siteId);
     expect(byIdRows, hasLength(1));
-    final fromById =
-        Site.fromJson((byIdRows.first['data'] as Map).cast<String, dynamic>(), (byIdRows.first['id'] ?? '').toString());
+    final fromById = Site.fromJson(
+        (byIdRows.first['data'] as Map).cast<String, dynamic>(),
+        (byIdRows.first['id'] ?? '').toString());
     expect(fromById.location!.point!.coordinates, [-1.55, 53.8]);
     expect(fromById.rooms['atrium']!.point!.coordinates, [-1.5, 53.79]);
 
     // ── (3) watch stream → typed rows, identical decode ──
     final watched = await harness.bridge
-        .watchById(siteId.value)
+        .watchById(siteId)
         .map((rows) => rows
-            .map((r) => Site.fromJson((r['data'] as Map).cast<String, dynamic>(), (r['id'] ?? '').toString()))
+            .map((r) => Site.fromJson(
+                (r['data'] as Map).cast<String, dynamic>(),
+                (r['id'] ?? '').toString()))
             .toList())
         .firstWhere((rows) => rows.isNotEmpty);
     expect(watched, hasLength(1));

package/dart/test/watch_after_offer_stall_test.dart

@@ -8,7 +8,7 @@ library;
 import 'dart:async';
 import 'dart:io';
 
-import 'package:nomos_client/nomos_headless.dart';
+import 'package:nomos_client/src/nms_conformance_runtime.dart';
 import 'package:test/test.dart';
 
 String get _root => '${Directory.current.path}/../..';
@@ -16,6 +16,7 @@ String get _repoEntry => '$_root/cloud/web-client/runner/node-entry.ts';
 String get _gbDeploy => '$_root/examples/guestbook/build/guestbook.deploy.json';
 String get _runtimeDir =>
     Platform.environment['NOMOS_DART_RUNTIME'] ??
+    Platform.environment['NOMOS_OFFLINE_RUNTIME'] ??
     '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
 
 String? _missingPrereq() {

package/dart/test/webview_bridge_test.dart

@@ -7,7 +7,7 @@ import 'dart:async';
 import 'dart:convert';
 import 'dart:io';
 
-import 'package:nomos_client/nomos_client.dart';
+import 'package:nomos_client/src/nms_generated_runtime.dart';
 import 'package:test/test.dart';
 
 /// A fake runner-over-a-transport: records sent requests, replies the way `webview-runner.mjs` does, and can
@@ -16,6 +16,7 @@ class FakeRunner implements BridgeTransport {
   final _incoming = StreamController<Map<String, Object?>>.broadcast();
   final List<Map<String, Object?>> sent = [];
   String? lastWatchSubId;
+  bool acknowledgeUnwatch = true;
 
   FakeRunner() {
     // the runner announces readiness at construction.
@@ -234,7 +235,9 @@ class FakeRunner implements BridgeTransport {
           _incoming.add(reply({'subId': args['subId']}));
           break;
         case 'unwatch':
-          _incoming.add(reply({'subId': args['subId']}));
+          if (acknowledgeUnwatch) {
+            _incoming.add(reply({'subId': args['subId']}));
+          }
           break;
         default:
           _incoming.add({
@@ -631,7 +634,7 @@ void main() {
     final moments = await momentsBridge.moments(limit: 12);
     expect(moments, hasLength(1));
     expect(moments.single.id, 'abc123');
-    expect(moments.single.actorSubject, 'user:ada');
+    expect(moments.single.performedBy, 'user:ada');
     expect(moments.single.action, 'createSite');
     expect((momentsTransport.lastRequest!['args'] as Map)['limit'], 12);
     await momentsBridge.dispose();
@@ -720,7 +723,7 @@ void main() {
     final payload = await bridge.nomosPrepareOwnedRecordAction(
       action: 'share',
       scope: 'owned-reader',
-      record: const NomosRef(
+      record: NmsInternalNomosRefs.create<Object?>(
         workspace: 'ws-1',
         type: 'notes.Note',
         id: 'note-1',
@@ -805,6 +808,16 @@ void main() {
     expect(runner.sent.any((m) => m['op'] == 'unwatch'), isTrue);
   });
 
+  test('watch cancellation is local and never waits for the runner', () async {
+    await bridge.ready;
+    runner.acknowledgeUnwatch = false;
+    final sub = bridge.watch('byAuthor', {'author': 'ada'}).listen((_) {});
+    await Future<void>.delayed(Duration.zero);
+
+    await sub.cancel().timeout(const Duration(milliseconds: 100));
+    expect(runner.sent.any((message) => message['op'] == 'unwatch'), isTrue);
+  });
+
   test('signal events are forwarded on their own stream', () async {
     await bridge.ready;
     final got = <Map<String, Object?>>[];

package/dart/test/wire_test.dart

@@ -7,7 +7,7 @@
 
 import 'dart:convert';
 
-import 'package:nomos_client/nomos_client.dart';
+import 'package:nomos_client/src/nms_generated_runtime.dart';
 import 'package:test/test.dart';
 
 /// Deep round-trip: a JSON string -> Dart fromJson -> toJson -> re-encoded

package/dart_types/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.8.0
+
+- Make `NomosRef<T>` the canonical identity of generated business records. References carry their workspace,
+  aggregate type and record id through actions, queries, navigation and activity without falling back to
+  interchangeable strings.
+- Keep generated business values and framework lifecycle details on separate package boundaries so product
+  code cannot accidentally rebuild Nomos runtime state.
+
 ## 0.7.1
 
 - Add typed framework recovery actions and lifecycle failure shapes without leaking signer, certificate,

package/dart_types/lib/nomos_types.dart

@@ -7,7 +7,7 @@
 /// NO bridge, NO runtime, NO Flutter. Generated per-domain TYPES files depend on ONLY
 /// this, so they resolve without pulling in sessions/workspace lifecycle. The
 /// `nomos_client` package depends on and re-exports this barrel, so existing
-/// `package:nomos_client/nomos_client.dart` imports are unchanged.
+/// Generated application packages consume this pure data layer through their implementation code.
 ///
 ///  - The kernel WIRE types (`Value`, `Field`/`WireField`, `Hlc`, `Op`, `FieldOp`,
 ///    `Event`, `Schema`/`WireDriver`) — byte-compatible with serde_json.
@@ -27,12 +27,13 @@ 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';
+// Foreign references expose identity data, while navigation readers and attestation stay behind the
+// generated application runtime.
+export 'src/foreign_ref.dart' show ForeignRef;
 export 'src/activity.dart';
-export 'src/nomos_ref.dart';
+// NomosRef is inspectable but framework-created. Its constructor and wire codec stay behind the runtime.
+export 'src/nomos_ref.dart' show NomosRef;
+export 'src/invitation.dart' show Identity, User, Recipient, Invitation;
 // Branded identity wrappers (NomosPrincipal / NomosDeviceSecret) for the generated cross-workspace
 // birth methods — actor/authorSecret are distinct types, so a transposition is a compile error.
 export 'src/principal.dart';

package/dart_types/lib/src/activity.dart

@@ -20,21 +20,29 @@ class ActivityRef {
   /// The source workspace (additive — empty on rows rendered before refs carried it).
   final String workspace;
 
-  const ActivityRef({required this.type, required this.id, this.workspace = ''});
+  const ActivityRef(
+      {required this.type, required this.id, this.workspace = ''});
 
   /// The canonical reference view (`nomos://<workspace>/<type>/<id>`).
-  NomosRef get ref => NomosRef(workspace: workspace, type: type, id: id);
+  NomosRef<Object?> get ref => NmsInternalNomosRefs.create<Object?>(
+      workspace: workspace, type: type, id: id);
 
   factory ActivityRef.fromJson(Map<String, dynamic> j) => ActivityRef(
       type: (j['type'] ?? '') as String,
       id: (j['id'] ?? '') as String,
       workspace: (j['workspace'] ?? '') as String);
-  Map<String, dynamic> toJson() =>
-      {'type': type, 'id': id, if (workspace.isNotEmpty) 'workspace': workspace};
+  Map<String, dynamic> toJson() => {
+        'type': type,
+        'id': id,
+        if (workspace.isNotEmpty) 'workspace': workspace
+      };
 
   @override
   bool operator ==(Object other) =>
-      other is ActivityRef && other.type == type && other.id == id && other.workspace == workspace;
+      other is ActivityRef &&
+      other.type == type &&
+      other.id == id &&
+      other.workspace == workspace;
   @override
   int get hashCode => Object.hash(type, id, workspace);
 }
@@ -73,8 +81,8 @@ class ActivityEvent {
   /// The declared STABLE event kind (e.g. `"site.created"`).
   final String kind;
 
-  /// The intent's author (principal) — the "who".
-  final String actorSubject;
+  /// Who performed the business action.
+  final String performedBy;
 
   /// When it happened (the intent's physical HLC timestamp, ISO-8601 when available).
   final String occurredAt;
@@ -113,7 +121,7 @@ class ActivityEvent {
   const ActivityEvent({
     required this.eventId,
     required this.kind,
-    required this.actorSubject,
+    required this.performedBy,
     required this.occurredAt,
     required this.title,
     required this.message,
@@ -131,7 +139,7 @@ class ActivityEvent {
   factory ActivityEvent.fromJson(Map<String, dynamic> j) => ActivityEvent(
         eventId: (j['eventId'] ?? '') as String,
         kind: (j['kind'] ?? '') as String,
-        actorSubject: (j['actorSubject'] ?? '') as String,
+        performedBy: (j['performedBy'] ?? j['actorSubject'] ?? '') as String,
         occurredAt: (j['occurredAt'] ?? '') as String,
         title: (j['title'] ?? '') as String,
         message: (j['message'] ?? '') as String,
@@ -139,8 +147,9 @@ class ActivityEvent {
         messageKey: (j['messageKey'] ?? '') as String,
         params: ((j['params'] as Map?)?.cast<String, dynamic>() ?? const {})
             .map((k, v) => MapEntry(k, '$v')),
-        refs: ((j['refs'] as Map?)?.cast<String, dynamic>() ?? const {})
-            .map((k, v) => MapEntry(k, ActivityRef.fromJson((v as Map).cast<String, dynamic>()))),
+        refs: ((j['refs'] as Map?)?.cast<String, dynamic>() ?? const {}).map(
+            (k, v) => MapEntry(
+                k, ActivityRef.fromJson((v as Map).cast<String, dynamic>()))),
         category: j['category'] as String?,
         icon: j['icon'] as String?,
         severity: ActivitySeverity.fromWire(j['severity'] as String?),
@@ -151,7 +160,7 @@ class ActivityEvent {
   Map<String, dynamic> toJson() => {
         'eventId': eventId,
         'kind': kind,
-        'actorSubject': actorSubject,
+        'performedBy': performedBy,
         'occurredAt': occurredAt,
         'title': title,
         'message': message,
@@ -170,4 +179,5 @@ class ActivityEvent {
 /// Interpolate `{name}` placeholders in [template] from [vars] — the render helper the generated
 /// `renderActivity` uses. A missing var renders empty (the compiler already validated every placeholder).
 String renderActivityTemplate(String template, Map<String, String> vars) =>
-    template.replaceAllMapped(RegExp(r'\{([a-zA-Z0-9_]+)\}'), (m) => vars[m.group(1)] ?? '');
+    template.replaceAllMapped(
+        RegExp(r'\{([a-zA-Z0-9_]+)\}'), (m) => vars[m.group(1)] ?? '');

package/dart_types/lib/src/foreign_ref.dart

@@ -1,13 +1,6 @@
-// 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.
+// NOMOS — the FOREIGN-REF runtime (t.foreignRef): a typed cross-application business reference.
+// Tenant code may retain and pass the reference to generated business methods. The generated application
+// implementation alone can decode or follow it; workspace routing and evidence remain framework concerns.
 //
 // 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
@@ -23,15 +16,9 @@ import 'nomos_ref.dart';
 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
+/// One foreign workspace's by-id read surface. 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 {
@@ -40,13 +27,13 @@ abstract class NomosForeignWorkspaceReader {
   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).
+  /// reader offers no watch lane (then the internal watcher 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
+/// The outcome of an internal foreign-reference resolution, 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.
+/// very different. The generated application collapses these details into its business-shaped API.
 sealed class ForeignResolveResult<T> {
   const ForeignResolveResult();
 }
@@ -74,64 +61,49 @@ class ForeignUnreachable<T> extends ForeignResolveResult<T> {
   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, inspectable cross-application business reference. Tenant code can retain, serialize and pass
+/// it back to generated application methods; navigation, decoding and attestation remain framework state.
+final class ForeignRef<T> {
+  final NomosRef<T> _ref;
+  final T Function(Map<String, dynamic> data, [String id]) _decode;
 
-/// 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;
+  const ForeignRef._(this._ref, this._decode);
 
-  /// The foreign workspace id (from the declared sibling workspace field).
-  final String workspace;
+  String get workspace => _ref.workspace;
+  String get type => _ref.type;
+  String get id => _ref.id;
+  NomosRef<T> get ref => _ref;
 
-  /// The foreign aggregate type this locator points at.
-  final String type;
+  @override
+  bool operator ==(Object other) =>
+      other is ForeignRef<T> && other._ref == _ref;
 
-  /// The canonical reference view (`nomos://<workspace>/<type>/<id>`) — a [ForeignRef] IS a typed view over
-  /// the one reference triple.
-  NomosRef get ref => NomosRef(workspace: workspace, type: type, id: id);
+  @override
+  int get hashCode => _ref.hashCode;
 
-  /// 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;
+  @override
+  String toString() => 'ForeignRef<$T>';
+}
 
-  const ForeignRef({
-    required this.id,
-    required this.workspace,
-    required this.type,
+/// The one private codec/navigation door used by generated application implementation code.
+/// It is intentionally excluded from `package:nomos_types/nomos_types.dart`.
+abstract final class NmsInternalForeignRefs {
+  static ForeignRef<T> create<T>({
+    required String id,
+    required String workspace,
+    required String type,
     required T Function(Map<String, dynamic> data, [String id]) fromJson,
-  }) : _decode = fromJson;
+  }) =>
+      ForeignRef<T>._(
+        NmsInternalNomosRefs.create<T>(
+            workspace: workspace, type: type, id: id),
+        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) {
+  static T? _decodeRows<T>(
+      ForeignRef<T> reference, List<Map<String, dynamic>> rows) {
     if (rows.isEmpty) return null;
+    final id = NmsInternalNomosRefs.id(reference._ref);
     Map<String, dynamic>? match;
     for (final r in rows) {
       if (r['id'] == id) {
@@ -144,35 +116,37 @@ class ForeignRef<T> {
     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);
+    return reference._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 {
+  static Future<ForeignResolveResult<T>> resolveResult<T>(
+      ForeignRef<T> reference, NomosForeignReader nomos) async {
+    final id = NmsInternalNomosRefs.id(reference._ref);
+    final workspace = NmsInternalNomosRefs.workspace(reference._ref);
     if (id.isEmpty || workspace.isEmpty) return ForeignNotFound<T>();
     try {
       final rows = await nomos.foreignWorkspace(workspace).queryById(id);
-      final row = _decodeRows(rows);
+      final row = _decodeRows(reference, 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);
+      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);
+  static Future<T?> resolve<T>(
+      ForeignRef<T> reference, NomosForeignReader nomos) async {
+    final r = await resolveResult(reference, 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) {
+  static void Function() watch<T>(ForeignRef<T> reference,
+      NomosForeignReader nomos, void Function(T? row) cb) {
+    final id = NmsInternalNomosRefs.id(reference._ref);
+    final workspace = NmsInternalNomosRefs.workspace(reference._ref);
     if (id.isEmpty || workspace.isEmpty) {
       cb(null);
       return () {};
@@ -183,38 +157,13 @@ class ForeignRef<T> {
       return () {};
     }
     final sub = stream.listen(
-      (rows) => cb(_decodeRows(rows)),
+      (rows) => cb(_decodeRows(reference, 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);
+  static Future<bool> exists<T>(
+          ForeignRef<T> reference, NomosForeignReader nomos) async =>
+      (await resolveResult(reference, nomos)) is ForeignFound<T>;
 }