@githolon/dsl 0.101.5 → 0.102.0

package/dart/lib/src/webview_bridge.dart

@@ -12,8 +12,11 @@
 /// The generated per-domain Dart client wraps a [NomosBridge]; the bridge owns request/reply correlation +
 /// reactive `watch` streams. The platform TRANSPORT ([BridgeTransport]) is injected — `dart:js_util` on web,
 /// a WebView JS-channel on mobile — so this protocol logic is pure Dart + fully unit-testable.
+@internal
 library;
 
+import 'package:meta/meta.dart' show internal;
+
 import 'dart:async';
 import 'dart:convert';
 import 'dart:math';
@@ -24,12 +27,12 @@ import 'package:nomos_types/nomos_types.dart'
         NomosTraceContext,
         NomosErrorInfo,
         NomosRef,
-        NomosForeignReader,
-        NomosForeignWorkspaceReader,
-        ForeignAttestation,
         CustodyBreakPolicy,
         NomosCustodyEvent,
         NomosCustodyStatus;
+import 'package:nomos_types/src/nomos_ref.dart' show NmsInternalNomosRefs;
+import 'package:nomos_types/src/foreign_ref.dart'
+    show NomosForeignReader, NomosForeignWorkspaceReader;
 
 import 'session_bound.dart' show DomainNotInstalledForSession;
 
@@ -107,14 +110,14 @@ class TransferProgress {
 class NomosMoment {
   final String id;
   final DateTime? occurredAt;
-  final String? actorSubject;
+  final String? performedBy;
   final String? domain;
   final String? action;
 
   const NomosMoment({
     required this.id,
     this.occurredAt,
-    this.actorSubject,
+    this.performedBy,
     this.domain,
     this.action,
   });
@@ -126,7 +129,7 @@ class NomosMoment {
       occurredAt: at is num
           ? DateTime.fromMillisecondsSinceEpoch(at.toInt(), isUtc: true)
           : null,
-      actorSubject: json['actorSubject']?.toString(),
+      performedBy: json['actorSubject']?.toString(),
       domain: json['domain']?.toString(),
       action: json['directiveId']?.toString(),
     );
@@ -198,7 +201,8 @@ class NomosCreated {
 
   /// 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);
+  NomosRef<Object?> get ref => NmsInternalNomosRefs.create<Object?>(
+      workspace: workspace, type: type, id: id);
   @override
   String toString() => id;
 }
@@ -838,6 +842,10 @@ class NomosOfferOutcome {
   final String head;
   final List<NomosCreated> created;
 
+  /// Every business aggregate touched by the sealed intent, including creates,
+  /// mutations, deterministic ensures and archives.
+  final List<NomosCreated> affected;
+
   /// 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;
@@ -859,6 +867,7 @@ class NomosOfferOutcome {
   const NomosOfferOutcome({
     required this.head,
     required this.created,
+    this.affected = const [],
     this.workspace = '',
     this.born = const [],
     this.birthOutcomes = const [],
@@ -874,8 +883,9 @@ class NomosOfferOutcome {
   /// The born child workspace(s) as followable [NomosRef]s — hand one to [NomosBridge.follow]
   /// (`final estate = await engine.follow(outcome.bornRefs.single);`) so app code never carries a
   /// loose workspace string. The ref's type is the reserved `nomos.Workspace` locator tag.
-  List<NomosRef> get bornRefs => born
-      .map((w) => NomosRef(workspace: w, type: 'nomos.Workspace', id: w))
+  List<NomosRef<Object?>> get bornRefs => born
+      .map((w) => NmsInternalNomosRefs.create<Object?>(
+          workspace: w, type: 'nomos.Workspace', id: w))
       .toList();
 }
 
@@ -885,11 +895,12 @@ class NomosOfferOutcome {
 /// genuinely-absent workspace needs [ifAbsentCredentials] (else a named [StateError]). Returns the live
 /// [NomosSession] — so the failure surfaces HERE (at open), never later on the client's first query. Defined
 /// in nomos_client (NOT on the pure `nomos_types` [NomosRef]) so the types package stays bridge-free.
-extension NomosRefAcquire on NomosRef {
+extension NomosRefAcquire<TAggregate> on NomosRef<TAggregate> {
   Future<NomosSession> acquire(
     NomosBridge bridge, {
     Future<NomosSessionCredentials> Function()? ifAbsentCredentials,
   }) {
+    final workspace = NmsInternalNomosRefs.workspace(this);
     if (workspace.isEmpty) {
       throw ArgumentError.value(this, 'ref',
           'NomosRef.acquire: the ref carries no workspace — only a workspace-complete ref is openable');
@@ -927,6 +938,25 @@ class NomosSessionCredentials {
   });
 }
 
+final class _NomosRetainedCloudAccess {
+  final String cloud;
+  final Future<String?> Function() signIn;
+
+  const _NomosRetainedCloudAccess({
+    required this.cloud,
+    required this.signIn,
+  });
+
+  Future<NomosSessionCredentials> credentials() async {
+    final token = await signIn();
+    if (token == null || token.trim().isEmpty) {
+      throw StateError(
+          'Nomos could not refresh the signed-in identity while opening a referenced business workspace');
+    }
+    return NomosSessionCredentials(cloud: cloud, authToken: token);
+  }
+}
+
 /// THE BRIDGE. Construct over a [BridgeTransport], `await ready`, then `connect(...)` and drive the holon.
 class NomosBridge {
   final BridgeTransport _transport;
@@ -980,6 +1010,14 @@ class NomosBridge {
   // The gate-bound identity retained from each session's auth token. Generated clients consume this so
   // application code never has to thread an actor into ordinary business methods.
   final Map<String, String> _sessionPrincipals = {};
+  // Device signing custody follows the application session internally. A generated application opening a
+  // locally-born child inherits its current session's device key; tenant code never handles authorSecret.
+  final Map<String, String> _sessionAuthorSecrets = {};
+  // Stateful generated applications retain the refreshable cloud access that opened their primary
+  // session. A generated read following a NomosRef can therefore mount a genuinely-absent workspace
+  // without asking tenant code for cloud URLs, tokens, sessions or signing keys. Kept per source
+  // session so one local plane may safely host applications from different clouds/identities.
+  final Map<String, _NomosRetainedCloudAccess> _sessionCloudAccess = {};
   // [acquireSession]'s per-workspace single-flight: workspace → the in-flight open every concurrent
   // acquirer joins (removed when it completes; a live session then hits the fast path instead).
   final Map<String, Future<NomosSession>> _acquiring = {};
@@ -1263,7 +1301,7 @@ class NomosBridge {
       final sub = payload is Map ? payload['sub'] : null;
       if (sub is! String || sub.trim().isEmpty) return null;
       final value = sub.trim();
-      return value.contains(':') ? value : 'user:$value';
+      return 'user:$value';
     } catch (_) {
       return null;
     }
@@ -1280,8 +1318,8 @@ class NomosBridge {
   NomosSession session(String workspace) => _eventPlane._sessionViews
       .putIfAbsent(workspace, () => NomosSession(_eventPlane, 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())`.
+  /// A [NomosForeignReader] backed by this bridge's multi-workspace plane. Generated application methods
+  /// use it privately to follow a declared cross-workspace business reference.
   /// `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
@@ -1380,6 +1418,9 @@ class NomosBridge {
     final boundPrincipal = _principalFromToken(authToken);
     if (boundPrincipal != null)
       _eventPlane._sessionPrincipals[ws] = boundPrincipal;
+    if (authorSecret != null && authorSecret.isNotEmpty) {
+      _eventPlane._sessionAuthorSecrets[ws] = authorSecret;
+    }
     _eventPlane._lastRecovery =
         (r['recovery'] as Map?)?.cast<String, Object?>();
   }
@@ -1670,6 +1711,16 @@ class NomosBridge {
         _eventPlane._sessionPrincipals[born] = birthPrincipal;
       }
     }
+    final sourceSession = session ?? _sessionName;
+    final birthAuthorSecret = authorSecret ??
+        (sourceSession == null
+            ? null
+            : _eventPlane._sessionAuthorSecrets[sourceSession]);
+    if (birthAuthorSecret != null && birthAuthorSecret.isNotEmpty) {
+      for (final born in bornNames) {
+        _eventPlane._sessionAuthorSecrets[born] = birthAuthorSecret;
+      }
+    }
     // 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(
@@ -1682,6 +1733,13 @@ class NomosBridge {
               id: (m['id'] ?? '').toString(),
               workspace: ws))
           .toList(),
+      affected: ((r['affected'] as List?) ?? const [])
+          .whereType<Map>()
+          .map((m) => NomosCreated(
+              type: (m['type'] ?? '').toString(),
+              id: (m['id'] ?? '').toString(),
+              workspace: ws))
+          .toList(),
       born: bornNames,
       birthOutcomes: births,
     );
@@ -1736,13 +1794,13 @@ class NomosBridge {
   /// cloud (omit for the local plane — a locally-born child mounts in place, no re-clone).
   /// [authorSecret] — the device signing key for the followed session's writes (era-0: an attested-born
   /// child is WARRANTED; write access needs its owner's enrolled device key).
-  Future<NomosSession> follow(NomosRef ref,
+  Future<NomosSession> follow<TAggregate>(NomosRef<TAggregate> ref,
       {String? cloud,
       String? clientId,
       String? authToken,
       bool allowUnborn = false,
       String? authorSecret}) async {
-    final ws = ref.workspace;
+    final ws = NmsInternalNomosRefs.workspace(ref);
     if (ws.isEmpty) {
       throw ArgumentError.value(ref, 'ref',
           'follow: the NomosRef carries no workspace — only a workspace-complete ref is followable');
@@ -1776,10 +1834,23 @@ class NomosBridge {
   /// the credentials path takes its own `NomosSessionCredentials.authorSecret` (falling back to this).
   Future<NomosSession> acquireSession(String workspace,
       {Future<NomosSessionCredentials> Function()? ifAbsentCredentials,
-      String? authorSecret}) {
+      String? authorSecret,
+      String? inheritedPrincipal}) {
     // Fast path: a live session needs no runner round-trip (and never asks for credentials).
     final plane = _eventPlane;
+    final sourcePrincipal = inheritedPrincipal ?? principal;
+    void inheritPrincipal() {
+      if (sourcePrincipal == null || sourcePrincipal.isEmpty) return;
+      final existing = plane._sessionPrincipals[workspace];
+      if (existing != null && existing != sourcePrincipal) {
+        throw StateError(
+            'acquireSession("$workspace"): the workspace is already bound to a different signed-in person');
+      }
+      plane._sessionPrincipals[workspace] = sourcePrincipal;
+    }
+
     if (plane._sessionNames.contains(workspace)) {
+      inheritPrincipal();
       return Future.value(session(workspace));
     }
     // SINGLE-FLIGHT: one in-flight open per workspace per plane; concurrent callers join it.
@@ -1801,6 +1872,7 @@ class NomosBridge {
               session: workspace,
               allowUnborn: true,
               authorSecret: authorSecret);
+          inheritPrincipal();
           return session(workspace);
         }
         if (ifAbsentCredentials == null) {
@@ -1818,6 +1890,7 @@ class NomosBridge {
           authorSecret: c.authorSecret ?? authorSecret,
           allowUnborn: c.allowUnborn,
         );
+        inheritPrincipal();
         return session(workspace);
       } finally {
         // completed (either way) — the next acquire re-evaluates fresh (a live session hits the fast path).
@@ -1983,7 +2056,7 @@ class NomosBridge {
     required String subject,
     required String relation,
     required String asserterPrincipal,
-    required String homeLawHash,
+    String? homeLawHash,
     String? authorSecret,
     String object = 'workspace:self',
     String? asserterWorkspace,
@@ -1996,7 +2069,7 @@ class NomosBridge {
       'relation': relation,
       if (authorSecret != null) 'authorSecret': authorSecret,
       'asserterPrincipal': asserterPrincipal,
-      'homeLawHash': homeLawHash,
+      if (homeLawHash != null) 'homeLawHash': homeLawHash,
       'object': object,
       if (asserterWorkspace != null) 'asserterWorkspace': asserterWorkspace,
       if (attestedAt != null) 'attestedAt': attestedAt,
@@ -2269,17 +2342,11 @@ class NomosBridge {
   Future<Map<String, Object?>> verifyChain() async =>
       _asMap(await _call('verifyChain'));
 
-  /// BIRTH A HOME — THE CEREMONY (VA root-of-trust, drift-proof), run end-to-end inside the connected holon:
-  /// derive the deterministic home name, mint + enroll the device key, DEVICE-SIGN the home cert through the
-  /// kernel `cert_sign` op (the single source of the byte layout), OFFER the PARAMETERIZED parent's `birthHome`
-  /// directive carrying the homeCert, poll the parent for the born home, and CONFIRM the born home's own
-  /// `verify_chain` is GREEN (the offline peer-verify — replay IS validation). `spec` MUST carry `parent` (the
-  /// tenant's platform whose governance includes `birthHome`) and `principal`; the client discovers the
-  /// private framework route and active law hashes from that application's live contract. `subject`/
-  /// `authToken`/`directiveId` are optional. OURS is the ceremony; the parent is the TENANT's.
-  /// Returns `{home, device:{secret,public}, homeCert, born, verify:{valid,…}}`.
-  Future<Map<String, Object?>> birthHome(Map<String, Object?> spec) async =>
-      _asMap(await _call('birthHome', spec));
+  /// Framework-private receiving-group setup. Generated application hosts own this ceremony; tenant code
+  /// receives only the resulting business application.
+  Future<Map<String, Object?>> nomosInternalBirthReceivingGroup(
+          Map<String, Object?> spec) async =>
+      _asMap(await _call('nomosInternalBirthReceivingGroup', spec));
 
   /// Sign a cross-custody SHARE attestation `{secret, asserterWorkspace, object, relation, subject,
   /// attestedAt}` → `{publicKey, signature}`. This is what drives `recordShare` into an invitee's home
@@ -2508,15 +2575,18 @@ class NomosBridge {
       }));
 
   /// Prepare the private framework payload behind generated share/unshare/transfer methods.
-  Future<Map<String, Object?>> nomosPrepareOwnedRecordAction(
+  Future<Map<String, Object?>> nomosPrepareOwnedRecordAction<TAggregate>(
           {required String action,
           required String scope,
-          required NomosRef record,
+          required NomosRef<TAggregate> record,
           required String peer}) async =>
       _asMap(await _call('cryptoOwnedPrepareRecordAction', {
         'action': action,
         'scope': scope,
-        'record': {'type': record.type, 'id': record.id},
+        'record': {
+          'type': NmsInternalNomosRefs.type(record),
+          'id': NmsInternalNomosRefs.id(record),
+        },
         'peer': peer,
       }));
 
@@ -2804,11 +2874,19 @@ class NomosBridge {
   /// Reactive local read: a stream of row-sets that re-emits on every local change. Cancelling the
   /// subscription tells the runner to drop the watch.
   Stream<List<dynamic>> watch(String queryId,
-          [Map<String, Object?> params = const {}, String? session]) =>
+          [Map<String, Object?> params = const {},
+          String? session,
+          String? principal]) =>
       _watchStream(
-          kind: 'query', queryId: queryId, params: params, session: session);
-  Stream<List<dynamic>> watchById(String id, [String? session]) =>
-      _watchStream(kind: 'byId', id: id, session: session);
+          kind: 'query',
+          queryId: queryId,
+          params: params,
+          session: session,
+          principal: principal);
+  Stream<List<dynamic>> watchById(String id,
+          [String? session, String? principal]) =>
+      _watchStream(
+          kind: 'byId', id: id, session: session, principal: principal);
 
   /// Reactive SPATIAL read: re-emits the R*Tree probe's rows whenever they change locally.
   Stream<List<dynamic>> watchSpatial(String spatialId, NomosBbox bbox,
@@ -2931,11 +3009,12 @@ class NomosBridge {
         'requirement': requirement,
         if (session != null) 'session': session,
       }),
-      onCancel: () async {
+      onCancel: () {
         _eventPlane._compatWatches.remove(subId);
-        try {
-          await _call('unwatch', {'subId': subId});
-        } catch (_) {}
+        // Cancellation is a local lifecycle boundary and must complete even if the runner is slow,
+        // disconnected, or being disposed. The remote release remains best-effort; bridge/runner disposal
+        // also drops every outstanding watch, so awaiting this acknowledgement only creates teardown hangs.
+        unawaited(_call('unwatch', {'subId': subId}).catchError((_) => null));
       },
     );
     _eventPlane._compatWatches[subId] = ctrl;
@@ -2950,7 +3029,8 @@ class NomosBridge {
       String? spatialId,
       NomosBbox? bbox,
       String? base,
-      String? session}) {
+      String? session,
+      String? principal}) {
     // Controllers live on the EVENT PLANE (where _onMessage dispatches); the registration `_call` stays
     // THIS instance's (a session's override stamps `args.session`) — see [_eventPlane].
     final subId = 'w${++_eventPlane._seq}';
@@ -2965,13 +3045,14 @@ class NomosBridge {
         if (spatialId != null) 'spatialId': spatialId,
         if (bbox != null) 'bbox': bbox.toJson(),
         if (base != null) 'base': base,
+        if (principal != null) 'principal': principal,
         if (session != null) 'session': session,
       }),
-      onCancel: () async {
+      onCancel: () {
         _eventPlane._watches.remove(subId);
-        try {
-          await _call('unwatch', {'subId': subId});
-        } catch (_) {}
+        // A caller owns its local subscription; it must never need a healthy transport in order to release
+        // it. Runner-side cleanup is still requested immediately and is made total by runner disposal.
+        unawaited(_call('unwatch', {'subId': subId}).catchError((_) => null));
       },
     );
     _eventPlane._watches[subId] = ctrl;
@@ -3078,14 +3159,48 @@ class NomosSession extends NomosBridge {
   /// single-flight registry; a session never owns mounts).
   @override
   Future<NomosSession> acquireSession(String workspace,
-          {Future<NomosSessionCredentials> Function()? ifAbsentCredentials,
-          String? authorSecret}) =>
-      parent.acquireSession(workspace,
-          ifAbsentCredentials: ifAbsentCredentials, authorSecret: authorSecret);
+      {Future<NomosSessionCredentials> Function()? ifAbsentCredentials,
+      String? authorSecret,
+      String? inheritedPrincipal}) {
+    final retained = parent._sessionCloudAccess[this.workspace];
+    final opened = parent.acquireSession(
+      workspace,
+      ifAbsentCredentials: ifAbsentCredentials ??
+          (retained == null ? null : retained.credentials),
+      authorSecret:
+          authorSecret ?? parent._sessionAuthorSecrets[this.workspace],
+      inheritedPrincipal:
+          inheritedPrincipal ?? parent._sessionPrincipals[this.workspace],
+    );
+    return opened.then((session) {
+      // Navigation can continue from the newly-opened handle without losing the application's private
+      // credential posture (home -> shared home -> child workspace remains one stateful application).
+      if (retained != null)
+        parent._sessionCloudAccess.putIfAbsent(workspace, () => retained);
+      return session;
+    });
+  }
+
+  /// Generator/runtime-host seam: retain this application's refreshable cloud access privately so
+  /// generated reference reads can mount another authorized workspace after a cold start.
+  ///
+  /// Tenant packages do not export NomosSession; application code reaches this only through generated
+  /// `find`/`watchOne` methods, never through a credential or session callback.
+  void nomosInternalRetainCloudAccess({
+    required String cloud,
+    required Future<String?> Function() signIn,
+  }) {
+    if (cloud.trim().isEmpty) {
+      throw ArgumentError.value(
+          cloud, 'cloud', 'Nomos cloud URL cannot be empty');
+    }
+    parent._sessionCloudAccess[workspace] =
+        _NomosRetainedCloudAccess(cloud: cloud, signIn: signIn);
+  }
 
   /// A followed ref mounts on the SHARED plane — delegate to the parent (a session never owns mounts).
   @override
-  Future<NomosSession> follow(NomosRef ref,
+  Future<NomosSession> follow<TAggregate>(NomosRef<TAggregate> ref,
           {String? cloud,
           String? clientId,
           String? authToken,
@@ -3096,7 +3211,8 @@ class NomosSession extends NomosBridge {
           clientId: clientId,
           authToken: authToken,
           allowUnborn: allowUnborn,
-          authorSecret: authorSecret);
+          authorSecret:
+              authorSecret ?? parent._sessionAuthorSecrets[workspace]);
 
   @override
   Future<Object?> _call(String op, [Map<String, Object?> args = const {}]) =>
@@ -3169,13 +3285,6 @@ class _BridgeForeignReader implements NomosForeignReader {
   @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.

package/dart/lib/src/workspace_name.dart

@@ -1,3 +1,8 @@
+@internal
+library;
+
+import 'package:meta/meta.dart' show internal;
+
 import 'dart:convert';
 
 import 'package:crypto/crypto.dart';
@@ -19,6 +24,7 @@ final String workspaceNameSep = String.fromCharCode(31);
 /// final ws = deriveWorkspaceName('estate', estateId); // open / sync / mount it
 /// ```
 String deriveWorkspaceName(String namespace, String key) {
-  final digest = sha256.convert(utf8.encode('$namespace$workspaceNameSep$key')).toString();
+  final digest =
+      sha256.convert(utf8.encode('$namespace$workspaceNameSep$key')).toString();
   return '$namespace-${digest.substring(0, 40)}';
 }

package/dart/pubspec.lock

@@ -162,7 +162,7 @@ packages:
     source: hosted
     version: "0.12.20"
   meta:
-    dependency: transitive
+    dependency: "direct main"
     description:
       name: meta
       sha256: df0c643f44ad098eb37988027a8e2b2b5a031fd3977f06bbfd3a76637e8df739
@@ -191,9 +191,9 @@ packages:
       path: "../dart_types"
       relative: true
     source: path
-    version: "0.7.1"
+    version: "0.8.0"
   package_config:
-    dependency: transitive
+    dependency: "direct main"
     description:
       name: package_config
       sha256: f096c55ebb7deb7e384101542bfba8c52696c1b56fca2eb62827989ef2353bbc

package/dart/pubspec.yaml

@@ -8,7 +8,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.63.1
+version: 0.64.0
 
 environment:
   sdk: ^3.5.0
@@ -17,9 +17,11 @@ 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.7.1
+  nomos_types: ^0.8.0
   json_schema: ^5.2.2
   crypto: ^3.0.0
+  package_config: ^2.1.0
+  meta: ^1.12.0
 
 dev_dependencies:
   test: ^1.25.0

package/dart/test/acquire_session_credentials_test.dart

@@ -5,7 +5,8 @@
 // returns. Runs hermetically on the offline runner (the "cloud" is the runner's offline shim, so
 // no network is ever contacted; what is under test is the acquire protocol, not the transport).
 //
-// This file also IS the gap-1 regression: it imports ONLY `nomos_headless.dart` and TYPES a
+// This file also IS the internal conformance regression: it imports only the obscured
+// framework conformance runtime and types a
 // `Future<NomosSessionCredentials> Function()` callback — before the barrel fix that did not compile.
 @TestOn('vm')
 library;
@@ -13,18 +14,21 @@ 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}/../..';
 String get _repoEntry => '$_root/cloud/web-client/runner/node-entry.ts';
-String get _docsDeploy => '$_root/bench/scale/fixtures/surfaced/build/surfaced.deploy.json';
+String get _docsDeploy =>
+    '$_root/bench/scale/fixtures/surfaced/build/surfaced.deploy.json';
 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(_docsDeploy).existsSync()) {
     return 'missing fixture $_docsDeploy — compile it: '
         '(cd bench/scale/fixtures/surfaced && node ../../../../dsl/compile_package.mjs)';
@@ -46,12 +50,14 @@ Future<T> _leg<T>(String name, Future<T> Function() body) async {
     print('✔ ACQUIRE $name (${sw.elapsedMilliseconds}ms)');
     return r;
   } catch (e, st) {
-    throw TestFailure('ACQUIRE $name FAILED after ${sw.elapsedMilliseconds}ms:\n$e\n$st');
+    throw TestFailure(
+        'ACQUIRE $name FAILED after ${sw.elapsedMilliseconds}ms:\n$e\n$st');
   }
 }
 
 void main() {
-  test('acquireSession: the absent-workspace lane invokes ifAbsentCredentials exactly once',
+  test(
+      'acquireSession: the absent-workspace lane invokes ifAbsentCredentials exactly once',
       () async {
     final missing = _missingPrereq();
     if (missing != null) {
@@ -70,10 +76,13 @@ void main() {
 
       // ── LEG 1 (gap 1, compile-time + runtime): the callback TYPE is reachable from the headless
       //    barrel alone, and a credentials object constructs with the documented fields. ──
-      await _leg('leg 1: NomosSessionCredentials is exported from nomos_headless', () async {
+      await _leg(
+          'leg 1: internal conformance runtime carries session credentials',
+          () async {
         // ignore: prefer_function_declarations_over_variables
-        final Future<NomosSessionCredentials> Function() typedCallback = () async =>
-            const NomosSessionCredentials(cloud: 'https://offline.invalid', allowUnborn: true);
+        final Future<NomosSessionCredentials> Function() typedCallback =
+            () async => const NomosSessionCredentials(
+                cloud: 'https://offline.invalid', allowUnborn: true);
         final c = await typedCallback();
         expect(c.cloud, 'https://offline.invalid');
         expect(c.allowUnborn, isTrue);
@@ -81,7 +90,9 @@ void main() {
 
       // ── LEG 2: a genuinely-absent workspace WITHOUT a callback is a NAMED StateError, never a
       //    silent cloudless mount. ──
-      await _leg('leg 2: absent workspace without credentials refuses (StateError)', () async {
+      await _leg(
+          'leg 2: absent workspace without credentials refuses (StateError)',
+          () async {
         await expectLater(
             plane.acquireSession('nowhere-at-all'),
             throwsA(isA<StateError>().having((e) => e.toString(), 'message',
@@ -92,26 +103,32 @@ void main() {
       //    callback fires EXACTLY ONCE (single-flight), the connect is made with its credentials,
       //    and both callers get the SAME mounted session. ──
       var invocations = 0;
-      await _leg('leg 3: concurrent double-acquire → one credentials invocation, one handle',
+      await _leg(
+          'leg 3: concurrent double-acquire → one credentials invocation, one handle',
           () async {
         Future<NomosSessionCredentials> creds() async {
           invocations++;
           return const NomosSessionCredentials(
-              cloud: 'https://offline.invalid', clientId: 'acquired-client', allowUnborn: true);
+              cloud: 'https://offline.invalid',
+              clientId: 'acquired-client',
+              allowUnborn: true);
         }
 
         final acquired = await Future.wait([
           plane.acquireSession('cloud-opened-ws', ifAbsentCredentials: creds),
           plane.acquireSession('cloud-opened-ws', ifAbsentCredentials: creds),
         ]).timeout(const Duration(seconds: 60),
-            onTimeout: () => throw StateError('the cloud-open acquire never completed'));
+            onTimeout: () =>
+                throw StateError('the cloud-open acquire never completed'));
         expect(invocations, 1,
-            reason: 'a concurrent double-acquire must invoke the credentials callback ONCE');
+            reason:
+                'a concurrent double-acquire must invoke the credentials callback ONCE');
         expect(identical(acquired[0], acquired[1]), isTrue,
             reason: 'both concurrent acquirers get the SAME session handle');
         expect(acquired[0].workspace, 'cloud-opened-ws');
         final listed = await plane.listWorkspaces();
-        expect(listed.map((w) => w['session'].toString()), contains('cloud-opened-ws'),
+        expect(listed.map((w) => w['session'].toString()),
+            contains('cloud-opened-ws'),
             reason: 'the acquired workspace is mounted on the plane');
       });
 
@@ -119,8 +136,8 @@ void main() {
       //    NEVER invoked again. ──
       await _leg('leg 4: re-acquire is credential-free (fast path)', () async {
         final again = await plane.acquireSession('cloud-opened-ws',
-            ifAbsentCredentials: () async =>
-                fail('the workspace is mounted — credentials must not be requested'));
+            ifAbsentCredentials: () async => fail(
+                'the workspace is mounted — credentials must not be requested'));
         expect(again.workspace, 'cloud-opened-ws');
         expect(invocations, 1);
       });