@githolon/dsl 0.67.0 → 0.69.0

package/dart/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 0.46.0
+
+- Custody lifecycle on `NomosBridge`/`NomosSession`: `connect(..., onCustodyBreak: CustodyBreakPolicy)`,
+  `custodyStatus()`, the `custodyEvents` stream, `resolveCustodyBreak()` (the ask lane — put the decision in
+  front of the user), `salvagedIntents`/`reofferSalvaged`/`discardSalvaged`. A rebirth/supersession is a
+  first-class typed event: named truthfully, decided by the app, local work never silently adopted nor lost.
+  Requires `nomos_types >= 0.1.4`.
+
+## 0.45.0
+
+- `offerOutcome(...)` — the one outcome-returning offer lane generated clients now call for EVERY directive:
+  returns `NomosOfferOutcome` with workspace-stamped `created` (`NomosCreated` gains `workspace` + a
+  `NomosRef get ref` view). Activity raw rows carry `created` + `workspace`. Requires `nomos_types >= 0.1.3`.
+
 ## 0.44.0
 
 - Activity-feed runtime reads on `NomosBridge`/`NomosSession`: `activityLog({base, limit})` — the committed

package/dart/lib/src/webview_bridge.dart

@@ -23,9 +23,13 @@ import 'package:nomos_types/nomos_types.dart'
         nomosErrorFromInfo,
         NomosTraceContext,
         NomosErrorInfo,
+        NomosRef,
         NomosForeignReader,
         NomosForeignWorkspaceReader,
-        ForeignAttestation;
+        ForeignAttestation,
+        CustodyBreakPolicy,
+        NomosCustodyEvent,
+        NomosCustodyStatus;
 
 /// The protocol version the runner and the bridge agree on (`webview-runner.mjs` `WEBVIEW_BRIDGE_VERSION`).
 const int kWebviewBridgeVersion = 1;
@@ -104,7 +108,15 @@ class SyncStatus {
 class NomosCreated {
   final String type;
   final String id;
-  const NomosCreated({required this.type, required this.id});
+
+  /// The workspace the offer ran on (NomosRef). Additive — defaults to '' on older runners that
+  /// don't stamp it; then [ref] is workspace-blank (still a valid locator on the local plane).
+  final String workspace;
+  const NomosCreated({required this.type, required this.id, this.workspace = ''});
+
+  /// The canonical [NomosRef] view — the `{workspace,type,id}` triple, followable/serializable
+  /// (`nomos://<workspace>/<type>/<id>`). One reference, everywhere.
+  NomosRef get ref => NomosRef(workspace: workspace, type: type, id: id);
   @override
   String toString() => id;
 }
@@ -604,6 +616,10 @@ class NomosOfferOutcome {
   final String head;
   final List<NomosCreated> created;
 
+  /// The workspace the offer ran on (NomosRef). Additive; '' on older runners. Each [created] ref already
+  /// carries this, so `outcome.created.first.ref` is the full followable `{workspace,type,id}` locator.
+  final String workspace;
+
   /// The born child workspace name(s), when the offer ran a `.births()` directive (else empty). Each is a
   /// LOCAL workspace on this device's plane, resident in the shared engine plane the moment it is born:
   /// `bridge.session(name)` returns its handle, and `bridge.connect(session: name)` (no `restoreFrom`) mounts
@@ -616,6 +632,7 @@ class NomosOfferOutcome {
   const NomosOfferOutcome({
     required this.head,
     required this.created,
+    this.workspace = '',
     this.born = const [],
     this.birthOutcomes = const [],
   });
@@ -642,6 +659,11 @@ class NomosBridge {
       StreamController<Map<String, Object?>>.broadcast();
   final StreamController<Map<String, Object?>> _signalEvents =
       StreamController<Map<String, Object?>>.broadcast();
+  // CUSTODY LIFECYCLE (rebirth_and_custody_lifecycle.md): each `custody` event carries the raw map (session +
+  // custody:{kind,break,…}); a Flutter app binds a break dialog / posture banner to this. Kind "ask" awaits
+  // [resolveCustodyBreak].
+  final StreamController<NomosCustodyEvent> _custodyEvents =
+      StreamController<NomosCustodyEvent>.broadcast();
   final StreamController<Map<String, Object?>> _flameEvents =
       StreamController<Map<String, Object?>>.broadcast();
   final StreamController<Map<String, Object?>> _spanEvents =
@@ -757,6 +779,13 @@ class NomosBridge {
       }
       return;
     }
+    if (event == 'custody') {
+      // Custody lifecycle: { event:'custody', session, custody:{ kind, break, … } }. Decode + fan out so the
+      // app can react (kind "ask" → show a dialog then call resolveCustodyBreak; others are informational).
+      final ev = NomosCustodyEvent.fromMessage(m);
+      if (ev != null && !_custodyEvents.isClosed) _custodyEvents.add(ev);
+      return;
+    }
     if (event == 'transfer') {
       // LIVE pack byte-progress { received, total, kind } — the real loading bar (host Content-Length).
       final tp = TransferProgress.fromMessage(m);
@@ -878,6 +907,7 @@ class NomosBridge {
       String? restoreFrom,
       bool allowUnborn = false,
       bool recover = false,
+      CustodyBreakPolicy? onCustodyBreak,
       String? session,
       int? maxMounted}) async {
     final ws = session ?? workspace;
@@ -903,10 +933,51 @@ class NomosBridge {
       // RECOVER-IN-PLACE over a corrupt restoreFrom snapshot: salvage local-only writes + DLQ, refold fresh
       // from cloud, re-offer the salvaged work. The report lands on [lastRecovery]. Nothing local is lost.
       if (recover) 'recover': true,
+      // CUSTODY-BREAK POLICY (rebirth_and_custody_lifecycle.md): "adopt"/"reject" decide automatically;
+      // "ask" surfaces the break on [custodyEvents] (kind "ask") and awaits [resolveCustodyBreak]. Omitted ⇒
+      // fail closed (the break surfaces as an error on the sync/pull that hit it; the holon stays local).
+      if (onCustodyBreak != null) 'onCustodyBreak': onCustodyBreak.wire,
     }));
     _lastRecovery = (r['recovery'] as Map?)?.cast<String, Object?>();
   }
 
+  /// The custody lifecycle stream (rebirth_and_custody_lifecycle.md) — a rebirth/divergence surfaces here as a
+  /// typed [NomosCustodyEvent]. Bind a Flutter break dialog / posture banner to it; for a `CustodyBreakPolicy.
+  /// ask` session, an event of `kind == 'ask'` awaits [resolveCustodyBreak].
+  Stream<NomosCustodyEvent> get custodyEvents => _custodyEvents.stream;
+
+  /// Where a session sits on the custody spectrum (incarnation, posture, pending/salvaged local work,
+  /// supersession history) — for a status banner or a "you're offline on old truth" indicator.
+  Future<NomosCustodyStatus> custodyStatus({String? session}) async =>
+      NomosCustodyStatus.fromJson(
+          _asMap(await _call('custodyStatus', {if (session != null) 'session': session})));
+
+  /// Continue an `ask`-policy custody break with the user's decision (adopt|reject) — the async UX lane.
+  Future<Map<String, Object?>> resolveCustodyBreak(String decision,
+          {String? session}) async =>
+      _asMap(await _call('resolveCustodyBreak', {
+        'decision': decision,
+        if (session != null) 'session': session,
+      }));
+
+  /// The parked salvaged intents (re-offerable local work an `adopt` rescued) — metadata only.
+  Future<List<Map<String, Object?>>> salvagedIntents({String? session}) async {
+    final r = _asMap(await _call('salvagedIntents', {if (session != null) 'session': session}));
+    return ((r['salvaged'] as List?) ?? const [])
+        .map((e) => (e as Map).cast<String, Object?>())
+        .toList();
+  }
+
+  /// Re-offer parked salvaged work under the current (adopted) law — the explicit app move (never automatic
+  /// across incarnations). [id] re-offers one; omitted re-offers all.
+  Future<Map<String, Object?>> reofferSalvaged({String? id, String? session}) async =>
+      _asMap(await _call('reofferSalvaged',
+          {if (id != null) 'id': id, if (session != null) 'session': session}));
+
+  /// Discard one parked salvaged intent — the app's explicit choice.
+  Future<Map<String, Object?>> discardSalvaged(String id, {String? session}) async =>
+      _asMap(await _call('discardSalvaged', {'id': id, if (session != null) 'session': session}));
+
   /// The salvage report from the most recent `connect(recover: true)` — `{ salvagedWrites, requeuedDeadLetters,
   /// unsalvageable }`, or null if the connection didn't recover. Show "recovered N writes" / surface
   /// `unsalvageable` (writes the current law refused — kept in the DLQ, never dropped).
@@ -965,6 +1036,32 @@ class NomosBridge {
     List<Map<String, Object?>>? attestations,
     bool? force,
     String? session,
+  }) =>
+      offerOutcome(
+        domain: domain,
+        directiveId: directiveId,
+        payload: payload,
+        actor: actor,
+        domainHash: domainHash,
+        attestations: attestations,
+        force: force,
+        session: session,
+      );
+
+  /// THE ONE OUTCOME-RETURNING OFFER LANE — [offerDirective] answering the full typed [NomosOfferOutcome]
+  /// (head + law-minted `created` NomosRefs + births), for EVERY generated method (create or mutate). A pure
+  /// mutation returns `created: []`; a `.creates(...)` plan returns the minted aggregate id(s), each already
+  /// carrying the session [workspace] so `outcome.created.first.ref` is a complete followable NomosRef with no
+  /// query-after round-trip. [offerCreates] is the historical alias (identical behavior).
+  Future<NomosOfferOutcome> offerOutcome({
+    required String domain,
+    required String directiveId,
+    required Object? payload,
+    String? actor,
+    String? domainHash,
+    List<Map<String, Object?>>? attestations,
+    bool? force,
+    String? session,
   }) async {
     final r = _asMap(await _call('offerDirective', {
       'domain': domain,
@@ -992,13 +1089,17 @@ class NomosBridge {
             .map((m) => (m['workspace'] ?? '').toString())
             .where((s) => s.isNotEmpty),
     ]..removeWhere((s) => s.isEmpty);
+    // The offer ran on this workspace (NomosRef) — stamp every minted ref with it so it is a complete locator.
+    final ws = (r['workspace'] ?? '').toString();
     return NomosOfferOutcome(
       head: r['head'].toString(),
+      workspace: ws,
       created: ((r['created'] as List?) ?? const [])
           .whereType<Map>()
           .map((m) => NomosCreated(
               type: (m['type'] ?? '').toString(),
-              id: (m['id'] ?? '').toString()))
+              id: (m['id'] ?? '').toString(),
+              workspace: ws))
           .toList(),
       born: bornNames,
       birthOutcomes: births,
@@ -1669,6 +1770,7 @@ class NomosBridge {
     _stopStatusPoll();
     if (!_syncEvents.isClosed) await _syncEvents.close();
     if (!_signalEvents.isClosed) await _signalEvents.close();
+    if (!_custodyEvents.isClosed) await _custodyEvents.close();
     if (!_flameEvents.isClosed) await _flameEvents.close();
     if (!_spanEvents.isClosed) await _spanEvents.close();
     if (!_transferEvents.isClosed) await _transferEvents.close();

package/dart/pubspec.lock

@@ -191,7 +191,7 @@ packages:
       path: "../dart_types"
       relative: true
     source: path
-    version: "0.1.0"
+    version: "0.1.2"
   package_config:
     dependency: transitive
     description:

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.44.0
+version: 0.46.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.2
+  nomos_types: ^0.1.4
   json_schema: ^5.2.2
   crypto: ^3.0.0
 

package/dart_types/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 0.1.4
+
+- Custody-lifecycle types: `NomosCustodyBreak`, `NomosCustodyStatus`, `NomosCustodyEvent`,
+  `CustodyBreakPolicy` (adopt/reject/ask) — a workspace rebirth surfaces as a typed, app-decidable event.
+  Purely additive.
+
+## 0.1.3
+
+- `NomosRef` — THE one typed reference `{workspace, type, id}`: value semantics, the canonical
+  `nomos://<workspace>/<type>/<id>` uri (`uri`/`parse`, encode round-trip), `fromJson` (object or uri),
+  `resolve()` over the multi-workspace reader. `ActivityRef` gains `workspace` + a `.ref` view; `ForeignRef`
+  gains `.ref`. Every reference shape now converges on the one triple. Purely additive.
+
 ## 0.1.2
 
 - Activity-feed runtime types: `ActivityEvent` (the shared activity row — kind/actor/occurredAt, rendered

package/dart_types/lib/nomos_types.dart

@@ -32,3 +32,7 @@ export 'src/errors.dart';
 // abstract interfaces (no bridge) — so both the layered TYPES package and nomos_client resolve them.
 export 'src/foreign_ref.dart';
 export 'src/activity.dart';
+export 'src/nomos_ref.dart';
+// The CUSTODY-LIFECYCLE types (rebirth_and_custody_lifecycle.md): NomosCustodyBreak / NomosCustodyStatus /
+// CustodyBreakPolicy — custody incompatibility as a first-class, typed, app-decidable event. Pure data.
+export 'src/custody.dart';

package/dart_types/lib/src/activity.dart

@@ -8,22 +8,35 @@
 // the generated pure `renderActivity` lives) AND the runtime `nomos_client` package resolve them.
 library;
 
+import 'nomos_ref.dart';
+
 /// A declared navigation target on an activity row: the referenced aggregate/contract TYPE + the resolved id
 /// (read from a payload field the directive named). Replaces the old enricher's blind id-probing — the app
 /// knows exactly what `id` points at and can deep-link/resolve it.
 class ActivityRef {
   final String type;
   final String id;
-  const ActivityRef({required this.type, required this.id});
 
-  factory ActivityRef.fromJson(Map<String, dynamic> j) =>
-      ActivityRef(type: (j['type'] ?? '') as String, id: (j['id'] ?? '') as String);
-  Map<String, dynamic> toJson() => {'type': type, 'id': id};
+  /// 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 = ''});
+
+  /// The canonical reference view (`nomos://<workspace>/<type>/<id>`).
+  NomosRef get ref => NomosRef(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};
 
   @override
-  bool operator ==(Object other) => other is ActivityRef && other.type == type && other.id == id;
+  bool operator ==(Object other) =>
+      other is ActivityRef && other.type == type && other.id == id && other.workspace == workspace;
   @override
-  int get hashCode => Object.hash(type, id);
+  int get hashCode => Object.hash(type, id, workspace);
 }
 
 /// Row prominence — a declared default the app may style or threshold on.

package/dart_types/lib/src/custody.dart

@@ -0,0 +1,203 @@
+// NOMOS — the CUSTODY-LIFECYCLE types (rebirth_and_custody_lifecycle.md, the client half). Custody
+// incompatibility is a FIRST-CLASS, app-decidable event: a rebirth (rebirthWorkspace) re-genesises a
+// workspace's chain, invalidating every client's local history. The client detects the break, names it
+// truthfully, and hands the app the decision — it NEVER silently adopts foreign truth nor loses local work.
+//
+// Pure data (no bridge/lifecycle/Flutter) so BOTH the layered TYPES package and the runtime `nomos_client`
+// resolve them. The bridge decodes these from the runner's `custody` events + `custodyStatus` reply.
+library;
+
+/// WHY a chain was superseded — the lineage annotation lifted from the workspace status onto a break.
+class NomosCustodySupersession {
+  final String? reason;
+  final String? supersededAt;
+
+  const NomosCustodySupersession({this.reason, this.supersededAt});
+
+  factory NomosCustodySupersession.fromJson(Map<String, dynamic> j) =>
+      NomosCustodySupersession(
+        reason: j['reason'] as String?,
+        supersededAt: j['supersededAt'] as String?,
+      );
+  Map<String, dynamic> toJson() =>
+      {'reason': reason, 'supersededAt': supersededAt};
+}
+
+/// The kind of custody break.
+///  - [superseded]: a LAWFUL rebirth — the remote incarnation differs and the lineage records the
+///    supersession (a reason/attribution rides the break).
+///  - [diverged]: the histories don't reconcile with NO supersession explanation (an unrelated/foreign chain).
+enum NomosCustodyBreakKind {
+  superseded,
+  diverged;
+
+  static NomosCustodyBreakKind fromWire(String? s) =>
+      s == 'diverged' ? NomosCustodyBreakKind.diverged : NomosCustodyBreakKind.superseded;
+  String get wire => this == NomosCustodyBreakKind.diverged ? 'diverged' : 'superseded';
+}
+
+/// A CUSTODY BREAK — the remote incarnation is incompatible with this client's local chain. Carries
+/// everything the app needs to choose adopt vs reject (and to explain WHY to a user).
+class NomosCustodyBreak {
+  final NomosCustodyBreakKind kind;
+
+  /// This client's local chain genesis oid.
+  final String localGenesis;
+
+  /// The remote serving chain's genesis oid (the workspace's current incarnation).
+  final String remoteGenesis;
+  final String remoteIncarnation;
+
+  /// Present for a [NomosCustodyBreakKind.superseded] break — why the old chain was retired.
+  final NomosCustodySupersession? supersession;
+
+  /// How many local-only intents (un-synced authored work) are at stake — never lost by any policy.
+  final int localOnlyIntents;
+
+  /// Epoch-ms of the last successful converge before the break (or null if never synced).
+  final int? lastSyncedAt;
+
+  const NomosCustodyBreak({
+    required this.kind,
+    required this.localGenesis,
+    required this.remoteGenesis,
+    required this.remoteIncarnation,
+    this.supersession,
+    this.localOnlyIntents = 0,
+    this.lastSyncedAt,
+  });
+
+  factory NomosCustodyBreak.fromJson(Map<String, dynamic> j) => NomosCustodyBreak(
+        kind: NomosCustodyBreakKind.fromWire(j['kind'] as String?),
+        localGenesis: (j['localGenesis'] ?? '') as String,
+        remoteGenesis: (j['remoteGenesis'] ?? j['remoteIncarnation'] ?? '') as String,
+        remoteIncarnation: (j['remoteIncarnation'] ?? j['remoteGenesis'] ?? '') as String,
+        supersession: (j['supersession'] is Map)
+            ? NomosCustodySupersession.fromJson(
+                (j['supersession'] as Map).cast<String, dynamic>())
+            : null,
+        localOnlyIntents: (j['localOnlyIntents'] as num?)?.toInt() ?? 0,
+        lastSyncedAt: (j['lastSyncedAt'] as num?)?.toInt(),
+      );
+
+  Map<String, dynamic> toJson() => {
+        'kind': kind.wire,
+        'localGenesis': localGenesis,
+        'remoteGenesis': remoteGenesis,
+        'remoteIncarnation': remoteIncarnation,
+        if (supersession != null) 'supersession': supersession!.toJson(),
+        'localOnlyIntents': localOnlyIntents,
+        'lastSyncedAt': lastSyncedAt,
+      };
+}
+
+/// The app's decision for a custody break (the declared or interactive policy outcome).
+enum CustodyBreakPolicy {
+  /// Salvage local-only work, re-clone the new incarnation, park the salvage re-offerable, resume.
+  adopt,
+
+  /// Stay on local truth, go offline-only (the local holon keeps serving; sync suspends).
+  reject,
+
+  /// Surface the break on [custodyEvents] and await `resolveCustodyBreak(...)` (async UX — a dialog).
+  ask;
+
+  String get wire => name;
+}
+
+/// A supersession entry from the workspace lineage (custody introspection history).
+class NomosSupersededChain {
+  final String? ref;
+  final String? supersededAt;
+  final String? reason;
+
+  const NomosSupersededChain({this.ref, this.supersededAt, this.reason});
+
+  factory NomosSupersededChain.fromJson(Map<String, dynamic> j) => NomosSupersededChain(
+        ref: j['ref'] as String?,
+        supersededAt: j['supersededAt'] as String?,
+        reason: j['reason'] as String?,
+      );
+  Map<String, dynamic> toJson() =>
+      {'ref': ref, 'supersededAt': supersededAt, 'reason': reason};
+}
+
+/// A custody lifecycle event pushed over the bridge (mirrors syncEvents). `kind` is one of
+/// "detected" | "rejected" | "adopting" | "adopted" | "ask"; "ask" awaits `resolveCustodyBreak`.
+class NomosCustodyEvent {
+  final String kind;
+  final String? session;
+  final NomosCustodyBreak? break_;
+  final bool? recloned;
+  final int? parkedIntents;
+
+  const NomosCustodyEvent({
+    required this.kind,
+    this.session,
+    this.break_,
+    this.recloned,
+    this.parkedIntents,
+  });
+
+  /// True when this event is an interactive prompt awaiting a decision.
+  bool get isAsk => kind == 'ask';
+
+  static NomosCustodyEvent? fromMessage(Map<String, dynamic> m) {
+    final c = (m['custody'] as Map?)?.cast<String, dynamic>();
+    if (c == null) return null;
+    final b = (c['break'] as Map?)?.cast<String, dynamic>();
+    return NomosCustodyEvent(
+      kind: (c['kind'] ?? '') as String,
+      session: m['session'] as String?,
+      break_: b != null ? NomosCustodyBreak.fromJson(b) : null,
+      recloned: c['recloned'] as bool?,
+      parkedIntents: (c['parkedIntents'] as num?)?.toInt(),
+    );
+  }
+}
+
+/// Where a holon sits on the custody spectrum ([custodyStatus]).
+class NomosCustodyStatus {
+  /// The chain THIS holon serves (its own genesis oid).
+  final String? incarnation;
+  final String? localGenesis;
+
+  /// The remote serving chain's genesis (or null when unknown / pre-rebirth cloud).
+  final String? remoteIncarnation;
+
+  /// One of: synced | custody-break | custody-break-rejected | adopting.
+  final String syncPosture;
+  final int pendingLocalIntents;
+  final int salvagedIntents;
+  final List<NomosSupersededChain> supersessionHistory;
+
+  /// The unresolved break, when the holon is sitting in a break posture.
+  final NomosCustodyBreak? pendingBreak;
+
+  const NomosCustodyStatus({
+    this.incarnation,
+    this.localGenesis,
+    this.remoteIncarnation,
+    this.syncPosture = 'synced',
+    this.pendingLocalIntents = 0,
+    this.salvagedIntents = 0,
+    this.supersessionHistory = const [],
+    this.pendingBreak,
+  });
+
+  factory NomosCustodyStatus.fromJson(Map<String, dynamic> j) => NomosCustodyStatus(
+        incarnation: j['incarnation'] as String?,
+        localGenesis: j['localGenesis'] as String?,
+        remoteIncarnation: j['remoteIncarnation'] as String?,
+        syncPosture: (j['syncPosture'] ?? 'synced') as String,
+        pendingLocalIntents: (j['pendingLocalIntents'] as num?)?.toInt() ?? 0,
+        salvagedIntents: (j['salvagedIntents'] as num?)?.toInt() ?? 0,
+        supersessionHistory: ((j['supersessionHistory'] as List?) ?? const [])
+            .whereType<Map>()
+            .map((m) => NomosSupersededChain.fromJson(m.cast<String, dynamic>()))
+            .toList(),
+        pendingBreak: (j['pendingBreak'] is Map)
+            ? NomosCustodyBreak.fromJson((j['pendingBreak'] as Map).cast<String, dynamic>())
+            : null,
+      );
+}

package/dart_types/lib/src/foreign_ref.dart

@@ -14,6 +14,8 @@
 // this barrel, and its `NomosBridge` implements [NomosForeignReader] over the device's multi-workspace plane.
 library;
 
+import 'nomos_ref.dart';
+
 /// 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
@@ -111,6 +113,10 @@ class ForeignRef<T> {
   /// The foreign aggregate type this locator points at.
   final String type;
 
+  /// 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);
+
   /// 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;
 

package/dart_types/lib/src/nomos_ref.dart

@@ -0,0 +1,75 @@
+// NOMOS — THE ONE REFERENCE (architecture/nomos_ref.md). A [NomosRef] is the canonical, globally-unique,
+// workspace-qualified identity of an aggregate instance: `{ workspace, type, id }`, with the stable string
+// form `nomos://<workspace>/<type>/<id>`. It travels WITH the data by default — every generated read row,
+// write outcome, and activity ref carries (or views as) one — so a dev holding a thing can always point at
+// it: no client-side UUID pre-minting, no loose {workspaceId, id} string pairs, no re-query-and-diff.
+//
+// A NomosRef is a LOCATOR (like ForeignRef, which remains the TYPED per-field view): `resolve` is an
+// informational read over the device's multi-workspace plane; law-grade attestation stays on the declared
+// attested-read lane. Pure nomos_types — no bridge/lifecycle imports.
+library;
+
+import 'foreign_ref.dart';
+
+/// The canonical typed reference to an aggregate instance: workspace + aggregate type + instance id.
+/// Value semantics; `uri` is the stable interop string (`nomos://<workspace>/<type>/<id>`).
+class NomosRef {
+  /// The workspace holding the instance.
+  final String workspace;
+
+  /// The aggregate TYPE (the read-projection type tag, e.g. `estate.EstateSite` or `EstateSite`).
+  final String type;
+
+  /// The instance id (law-minted or law-defined).
+  final String id;
+
+  const NomosRef({required this.workspace, required this.type, required this.id});
+
+  /// The stable string form — survives URLs, nav params, JSON, logs. Segments are URI-encoded so a
+  /// workspace/type/id containing `/` or spaces round-trips.
+  String get uri =>
+      'nomos://${Uri.encodeComponent(workspace)}/${Uri.encodeComponent(type)}/${Uri.encodeComponent(id)}';
+
+  /// Parse a `nomos://<workspace>/<type>/<id>` string (the inverse of [uri]). Throws [FormatException]
+  /// on anything else.
+  factory NomosRef.parse(String uri) {
+    final u = Uri.tryParse(uri);
+    if (u == null || u.scheme != 'nomos') {
+      throw FormatException('NomosRef.parse: not a nomos:// uri', uri);
+    }
+    // nomos://<ws>/<type>/<id> — the workspace lands as the authority (host), type/id as path segments.
+    final ws = Uri.decodeComponent(u.host);
+    final segs = u.pathSegments.map(Uri.decodeComponent).toList();
+    if (ws.isEmpty || segs.length != 2 || segs[0].isEmpty || segs[1].isEmpty) {
+      throw FormatException('NomosRef.parse: expected nomos://<workspace>/<type>/<id>', uri);
+    }
+    return NomosRef(workspace: ws, type: segs[0], id: segs[1]);
+  }
+
+  /// Accepts the `{workspace,type,id}` object OR the `nomos://` uri string.
+  factory NomosRef.fromJson(Object? j) {
+    if (j is String) return NomosRef.parse(j);
+    final m = (j as Map).cast<String, dynamic>();
+    return NomosRef(
+      workspace: (m['workspace'] ?? '') as String,
+      type: (m['type'] ?? '') as String,
+      id: (m['id'] ?? '') as String,
+    );
+  }
+
+  Map<String, dynamic> toJson() => {'workspace': workspace, 'type': type, 'id': id};
+
+  /// Informational lookup of the referenced instance over the device's multi-workspace plane (the same
+  /// reader `ForeignRef.resolve` uses — `bridge.foreignReader()` in nomos_client). Returns the raw
+  /// `{type,id,data}` rows for the id in the ref's workspace (empty ⇒ not found / not visible).
+  Future<List<Map<String, dynamic>>> resolve(NomosForeignReader nomos) =>
+      nomos.foreignWorkspace(workspace).queryById(id);
+
+  @override
+  bool operator ==(Object other) =>
+      other is NomosRef && other.workspace == workspace && other.type == type && other.id == id;
+  @override
+  int get hashCode => Object.hash(workspace, type, id);
+  @override
+  String toString() => uri;
+}

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.2
+version: 0.1.4
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.67.0",
+  "version": "0.69.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",