@githolon/dsl 0.70.2 → 0.72.0

package/dart/lib/src/webview_bridge.dart

@@ -31,6 +31,15 @@ import 'package:nomos_types/nomos_types.dart'
         NomosCustodyEvent,
         NomosCustodyStatus;
 
+import 'session_bound.dart' show DomainNotInstalledForSession;
+
+/// THE ENGINE (architecture/session_bound_clients.md): the multi-workspace RUNTIME — mount/connect,
+/// the session registry, sync, custody + recovery, the home ceremony, and [NomosBridge.follow]
+/// (ref → mounted session). NOT the surface for domain writes: those live on the generated
+/// `<Domain>Client` bound to a [NomosSession]. `NomosEngine` is the doctrine-named alias of the
+/// bridge root so app code reads as the four-layer split (engine → session → client → values).
+typedef NomosEngine = NomosBridge;
+
 /// The protocol version the runner and the bridge agree on (`webview-runner.mjs` `WEBVIEW_BRIDGE_VERSION`).
 const int kWebviewBridgeVersion = 1;
 
@@ -523,7 +532,7 @@ class NomosEncryption {
       });
     }
     final epoch = (await _currentEpoch(scope)) + 1; // forward-only: strictly increments
-    final head = await bridge.offerDirective(
+    final head = (await bridge.offerOutcome(
       domain: domain,
       directiveId: 'advanceKeyEpoch',
       payload: {
@@ -534,7 +543,8 @@ class NomosEncryption {
       },
       actor: actor,
       domainHash: domainHash,
-    );
+    ))
+        .head;
     return NomosEpochResult(head: head, epoch: epoch, roster: members);
   }
 
@@ -553,7 +563,7 @@ class NomosEncryption {
     String? openedAt,
   }) async {
     final s = _defScope(scope);
-    await bridge.offerDirective(
+    await bridge.offerOutcome(
         domain: domain,
         directiveId: grantDirective,
         payload: grantPayload,
@@ -581,7 +591,7 @@ class NomosEncryption {
     String? openedAt,
   }) async {
     final s = _defScope(scope);
-    await bridge.offerDirective(
+    await bridge.offerOutcome(
         domain: domain,
         directiveId: revokeDirective,
         payload: revokePayload,
@@ -629,13 +639,26 @@ class NomosOfferOutcome {
   /// The raw per-child birth outcomes the holon reported (`{ workspace, genesisHead, … }`), when present.
   final List<Map<String, Object?>> birthOutcomes;
 
+  /// LEGACY GATEWAY LANE ONLY: the parent gateway's verdict, when this outcome wraps a deprecated
+  /// cross-workspace `createWorkspace` relay (the old generated-birth shape). Null on the one
+  /// local offer lane.
+  final Map<String, Object?>? gatewayVerdict;
+
   const NomosOfferOutcome({
     required this.head,
     required this.created,
     this.workspace = '',
     this.born = const [],
     this.birthOutcomes = const [],
+    this.gatewayVerdict,
   });
+
+  /// 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))
+      .toList();
 }
 
 /// THE BRIDGE. Construct over a [BridgeTransport], `await ready`, then `connect(...)` and drive the holon.
@@ -985,6 +1008,9 @@ class NomosBridge {
   Map<String, Object?>? _lastRecovery;
 
   /// LOCAL-FIRST offer: carry opaque intent bytes into the GitHolon. Returns the new local head; durable on [sync].
+  @Deprecated('Engine-level generic writes are the footgun (session_bound_clients.md ask 1/7): '
+      'dispatch through a generated <Domain>Client bound to a NomosSession '
+      '(XClient.bind(session)). Retained for CLIs/admin tooling/generated internals only.')
   Future<String> offer({required String intentBytes}) async {
     final r = _asMap(await _call('offer', {'intentBytes': intentBytes}));
     return r['head'].toString();
@@ -1000,6 +1026,10 @@ class NomosBridge {
   /// its trust policy); [force] carries the deploy/evolve force flag through. Both are OMITTED from the wire
   /// when absent, so a plain offer is byte-identical to before. [session] pins the colocated workspace in a
   /// cluster harness (absent ⇒ the runner's sole-session default).
+  @Deprecated('Engine-level string-y writes are the footgun (session_bound_clients.md ask 1/7): '
+      'dispatch through a generated <Domain>Client bound to a NomosSession '
+      '(XClient.bind(session) — no domain/directive strings at call sites). '
+      'Retained for CLIs/admin tooling/generated internals only.')
   Future<String> offerDirective({
     required String domain,
     required String directiveId,
@@ -1027,6 +1057,9 @@ class NomosBridge {
   /// inside the sealed intent (callers never supply one); the runner hands back what was minted, so a
   /// generated create method returns the typed id with NO query-after round-trip. [created] is empty for
   /// pure mutations.
+  @Deprecated('Engine-level string-y writes are the footgun (session_bound_clients.md ask 1/7): '
+      'dispatch through a generated <Domain>Client bound to a NomosSession. '
+      'Retained for CLIs/admin tooling/generated internals only.')
   Future<NomosOfferOutcome> offerCreates({
     required String domain,
     required String directiveId,
@@ -1063,16 +1096,22 @@ class NomosBridge {
     bool? force,
     String? session,
   }) async {
-    final r = _asMap(await _call('offerDirective', {
-      'domain': domain,
-      'directiveId': directiveId,
-      'payload': payload,
-      if (actor != null) 'actor': actor,
-      if (domainHash != null) 'domainHash': domainHash,
-      if (attestations != null) 'attestations': attestations,
-      if (force != null) 'force': force,
-      if (session != null) 'session': session,
-    }));
+    final Map<String, Object?> r;
+    try {
+      r = _asMap(await _call('offerDirective', {
+        'domain': domain,
+        'directiveId': directiveId,
+        'payload': payload,
+        if (actor != null) 'actor': actor,
+        if (domainHash != null) 'domainHash': domainHash,
+        if (attestations != null) 'attestations': attestations,
+        if (force != null) 'force': force,
+        if (session != null) 'session': session,
+      }));
+    } catch (e) {
+      throw await _wrapDomainNotInstalled(e,
+          domain: domain, domainHash: domainHash, requestedWorkspace: session);
+    }
     final births = ((r['birthOutcomes'] as List?) ?? const [])
         .whereType<Map>()
         .map((m) => m.cast<String, Object?>())
@@ -1106,6 +1145,66 @@ class NomosBridge {
     );
   }
 
+  /// CONTEXT-RICH "domain not installed" (session_bound_clients.md ask 6): the kernel's generic
+  /// `no active installed law declares domain 'x'` refusal is WRAPPED here with the session
+  /// context (which session, what it actually runs, the likely causes) — the string itself
+  /// originates in the sealed kernel, so the bridge (not the kernel) owns the ergonomics.
+  /// Anything that isn't that refusal passes through unchanged.
+  Future<Object> _wrapDomainNotInstalled(Object e,
+      {required String domain, String? domainHash, String? requestedWorkspace}) async {
+    if (!RegExp(r"no active installed law declares domain '").hasMatch(e.toString())) return e;
+    final self = this;
+    final sessionWs = self is NomosSession ? self.workspace : null;
+    var activeKeys = const <String>[];
+    try {
+      final offer = await interfaceOffer();
+      if (offer != null) activeKeys = offer.keys.toList()..sort();
+    } catch (_) {/* best-effort enrichment — the typed error still carries the context we have */}
+    return DomainNotInstalledForSession(
+      expectedDomainKey: domain,
+      expectedDomainHash: domainHash,
+      sessionId: requestedWorkspace ?? sessionWs,
+      sessionWorkspace: sessionWs,
+      requestedWorkspace: requestedWorkspace ?? sessionWs,
+      activeDomainKeys: activeKeys,
+      activeDomainHashes: compat?.workspaceRuns ?? const [],
+      underlying: e,
+    );
+  }
+
+  /// THE WORKSPACE'S ON-LEDGER STRUCTURAL OFFER (#72): the per-domain interface embedded in each
+  /// installed package, read off the LOCAL projection (offline). Keys = the ACTIVE domain keys the
+  /// workspace serves. Null when no on-ledger interface is observed yet (pre-#72e law).
+  Future<Map<String, Object?>?> interfaceOffer({String? session}) async {
+    final r = _asMap(await _call('interfaceOffer', {if (session != null) 'session': session}));
+    return (r['offer'] as Map?)?.cast<String, Object?>();
+  }
+
+  /// FOLLOW A [NomosRef] — THE cross-workspace primitive (session_bound_clients.md ask 8): mount
+  /// the referenced workspace on this device's plane (idempotent — an already-open workspace is
+  /// just returned) and hand back its [NomosSession]. Typed client construction is then one line:
+  /// `final estate = await engine.follow(outcome.bornRefs.single); final app = await EstateClient.bind(estate);`
+  /// No loose `{workspaceId, aggregateId}` string pairs in app code. [cloud] binds the mount to a
+  /// cloud (omit for the local plane — a locally-born child mounts in place, no re-clone).
+  Future<NomosSession> follow(NomosRef ref,
+      {String? cloud, String? clientId, String? authToken, bool allowUnborn = false}) async {
+    final ws = ref.workspace;
+    if (ws.isEmpty) {
+      throw ArgumentError.value(ref, 'ref',
+          'follow: the NomosRef carries no workspace — only a workspace-complete ref is followable');
+    }
+    if (!_sessionNames.contains(ws)) {
+      await connect(
+          cloud: cloud,
+          workspace: ws,
+          session: ws,
+          clientId: clientId,
+          authToken: authToken,
+          allowUnborn: allowUnborn);
+    }
+    return session(ws);
+  }
+
   /// Reserve a KERNEL-MINTED typed id (`<TypeTag>_<uuidv7>`) via the holon's front-door mint — for app-side
   /// references (routing keys, optimistic UI). `.creates` payloads still carry NO id: the LAW mints those
   /// (see [offerCreates], which returns them).
@@ -1121,6 +1220,9 @@ class NomosBridge {
   /// OFFER AN INTENT — the write verb. Plan a directive (domain/directiveId/payload) as the verified [actor];
   /// the holon encodes the v2 offer envelope via the single codec and admits it. Returns the new local head.
   /// (This is the canonical name; [offerDirective] is the legacy alias the generated clients still call.)
+  @Deprecated('Engine-level string-y writes are the footgun (session_bound_clients.md ask 1/7): '
+      'dispatch through a generated <Domain>Client bound to a NomosSession. '
+      'Retained for CLIs/admin tooling/generated internals only.')
   Future<String> offerIntent({
     required String domain,
     required String directiveId,
@@ -1169,10 +1271,22 @@ class NomosBridge {
       }));
 
   /// MAKE A WORKSPACE — the one-call tenant path. A child workspace under a platform/[parent] is a SIGNED
-  /// control-plane offer; the holon seals `createWorkspace` (or [directiveId] `birthChild`) with the
-  /// requester's device key ([authorSecret], as [actor], e.g. `user:<uid>`) and relays it to the parent's
-  /// gateway. Returns the worker verdict (`{ok, status, body}`). The tenant move is one line:
+  /// control-plane offer; the holon seals `createWorkspace` (or [directiveId] `birthChild`, or ANY
+  /// tenant-defined `.births()` directive — see [domain]) with the requester's device key ([authorSecret],
+  /// as [actor], e.g. `user:<uid>`) and relays it to the parent's gateway. Returns the worker verdict
+  /// (`{ok, status, body}`). The tenant move is one line:
   /// `await bridge.createWorkspace(name: 'foo', parent: 'my-platform', actor: 'user:$uid', authorSecret: key)`.
+  ///
+  /// [domain] defaults to `'workspaces'` (the generic root-style governance law every platform's
+  /// createWorkspace/birthChild rides). To birth through the PARENT'S OWN custom platform law instead (e.g.
+  /// a tenant `birthEstateWorkspace` under a `co2_platform` domain), pass that domain's key + [domainHash]:
+  /// `bridge.createWorkspace(domain: 'co2_platform', directiveId: 'birthEstateWorkspace', domainHash: ...)`.
+  /// The kernel looks up `(domain, directiveId)` in the ACTIVE installed law — [domain] must name the law
+  /// that actually declares [directiveId], never assume `'workspaces'`.
+  @Deprecated('Engine-level generic writes with a loose parent string are the footgun '
+      '(session_bound_clients.md asks 1/4/7): births go through the generated <Domain>Client '
+      'bound to the PARENT NomosSession (its birth method infers parent = the session workspace). '
+      'Retained for CLIs/admin tooling/generated compatibility shims only.')
   Future<Map<String, Object?>> createWorkspace({
     required String parent,
     required String actor,
@@ -1180,21 +1294,29 @@ class NomosBridge {
     String? name,
     Object? payload,
     String directiveId = 'createWorkspace',
+    String domain = 'workspaces',
     String? domainHash,
     String? authToken,
   }) async {
     // [authorSecret] defaults to the connection's signing key (the home key NomosScope.home loaded) —
     // a frontend dev never threads a key through.
-    final r = _asMap(await _call('createWorkspace', {
-      'parent': parent,
-      'actor': actor,
-      if (authorSecret != null) 'authorSecret': authorSecret,
-      if (name != null) 'name': name,
-      if (payload != null) 'payload': payload,
-      'directiveId': directiveId,
-      if (domainHash != null) 'domainHash': domainHash,
-      if (authToken != null) 'authToken': authToken,
-    }));
+    final Map<String, Object?> r;
+    try {
+      r = _asMap(await _call('createWorkspace', {
+        'parent': parent,
+        'actor': actor,
+        if (authorSecret != null) 'authorSecret': authorSecret,
+        if (name != null) 'name': name,
+        if (payload != null) 'payload': payload,
+        'directiveId': directiveId,
+        'domain': domain,
+        if (domainHash != null) 'domainHash': domainHash,
+        if (authToken != null) 'authToken': authToken,
+      }));
+    } catch (e) {
+      throw await _wrapDomainNotInstalled(e,
+          domain: domain, domainHash: domainHash, requestedWorkspace: parent);
+    }
     return (r['verdict'] as Map?)?.cast<String, Object?>() ?? r;
   }
 
@@ -1459,6 +1581,18 @@ class NomosBridge {
       }))['sum']) as num)
           .toInt();
 
+  /// THE PENDING-CONFLICTS READ (Surfaced merge conflicts — the DX layer): the MAINTAINED,
+  /// workspace-wide "decisions needed" index (reserved id `nomosPendingConflicts`). One row per
+  /// (aggregate, field) whose folded state carries a Surfaced pending set of 2+ observations —
+  /// `{aggregateType, aggregateId, field, observations: [{value, author, occurredAt}]}`.
+  /// DERIVED, NOT DRAINED: a resolution write folding in removes its row by derivation.
+  /// Empty for a Surfaced-free workspace. (The generated typed client wraps these rows as
+  /// `PendingConflictRow` and pairs them with the designated `resolve…` helpers.)
+  Future<List<Map<String, dynamic>>> pendingConflicts([String? session]) async =>
+      _asRows(await _call('pendingConflicts', {
+        if (session != null) 'session': session,
+      }));
+
   /// Push local writes → the session branch → cloud admission, and pull canonical main back.
   Future<Map<String, Object?>> sync({bool admit = true, String? session}) async =>
       _asMap(await _call('sync', {
@@ -1612,6 +1746,11 @@ class NomosBridge {
           [String? session]) =>
       _watchStream(kind: 'spatial', spatialId: spatialId, bbox: bbox, session: session);
 
+  /// Reactive PENDING-CONFLICTS read: re-emits the maintained Surfaced "decisions needed"
+  /// rows whenever the index changes (derived, not drained — a resolution write clears its row).
+  Stream<List<dynamic>> watchPendingConflicts([String? session]) =>
+      _watchStream(kind: 'pendingConflicts', session: session);
+
   /// SHAPE COMPATIBILITY (#72): one-shot verdict for this client's structural [requirement]
   /// (its baked `…InterfaceJson`, decoded) against the workspace's ON-LEDGER offer (auto-sourced).
   /// `{ ok, missing[], incompatible[] }` — names the exact directive/aggregate/field, not a hash.
@@ -1808,6 +1947,13 @@ class NomosSession extends NomosBridge {
   @override
   NomosSession session(String workspace) => parent.session(workspace);
 
+  /// A followed ref mounts on the SHARED plane — delegate to the parent (a session never owns mounts).
+  @override
+  Future<NomosSession> follow(NomosRef ref,
+          {String? cloud, String? clientId, String? authToken, bool allowUnborn = false}) =>
+      parent.follow(ref,
+          cloud: cloud, clientId: clientId, authToken: authToken, allowUnborn: allowUnborn);
+
   @override
   Future<Object?> _call(String op, [Map<String, Object?> args = const {}]) =>
       parent._call(op,

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

package/dart/test/cluster_attested_test.dart

@@ -18,7 +18,6 @@ import 'dart:convert';
 import 'dart:io';
 
 import 'package:crypto/crypto.dart';
-import 'package:nomos_client/nomos_client.dart' show NomosOfferOutcome;
 import 'package:nomos_client/nomos_headless.dart';
 import 'package:test/test.dart';
 

package/dart/test/session_bound_test.dart

@@ -0,0 +1,255 @@
+// SESSION-BOUND CLIENTS — THE ACCEPTANCE (architecture/session_bound_clients.md). The blessed app
+// shape end-to-end, against the REAL wasm on a local plane, with ZERO workspace/domain/directive
+// strings in the app-side code:
+//
+//   engine → mount → Client.bind(session) (preflight) → a PARENTLESS birth landing in the session
+//   workspace → engine.follow(ref) → a second client → a directive on it.
+//
+// Plus the typed failure modes: bind on a deliberately WRONG session throws
+// DomainClientSessionMismatch with every spec field; a dispatch naming an uninstalled domain
+// surfaces as DomainNotInstalledForSession (the context-rich replacement of the kernel's generic
+// "no active installed law declares domain 'x'"); and the deprecated engine-level shims still
+// function (compatibility is deprecation, not breakage).
+@TestOn('vm')
+library;
+
+import 'dart:io';
+
+// ignore: deprecated_member_use
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+// home.client.dart re-exports home.dart + the nomos_client surface (NomosSession, the typed errors,
+// NomosOfferOutcome, …); estate.client.dart adds the child-law client. One import each = the whole
+// typed surface. ZERO raw strings needed below.
+import '../../../bench/scale/fixtures/estate-birth/build/dart/src/generated/home.client.dart';
+import '../../../bench/scale/fixtures/estate-birth/build/dart/src/generated/estate.client.dart'
+    show EstateClient, SeedEstateWorkspacePayload;
+
+String get _root => '${Directory.current.path}/../..';
+String get _repoEntry => '$_root/cloud/web-client/runner/node-entry.mjs';
+String get _deployJson =>
+    '$_root/bench/scale/fixtures/estate-birth/build/estate-birth.deploy.json';
+String get _otherDeployJson =>
+    '$_root/bench/scale/fixtures/surfaced/build/surfaced.deploy.json';
+String get _runtimeDir =>
+    Platform.environment['NOMOS_DART_RUNTIME'] ??
+    '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+
+const _workspace = 'estate-birth';
+const _owner = 'user:session-bound-owner';
+
+String? _missingPrereq() {
+  if (!File(_repoEntry).existsSync()) return 'in-repo runner not found at $_repoEntry';
+  if (!File(_deployJson).existsSync() || !File(_otherDeployJson).existsSync()) {
+    return 'compile the fixtures: (cd bench/scale/fixtures/estate-birth && node ../../../../dsl/compile_package.mjs); '
+        '(cd bench/scale/fixtures/surfaced && node ../../../../dsl/compile_package.mjs)';
+  }
+  if (!File('$_runtimeDir/holon.wasm').existsSync() ||
+      !File('$_runtimeDir/packages.json').existsSync()) {
+    return 'warm ~/.holon/runtime first (run any `githolon` command once)';
+  }
+  return null;
+}
+
+Future<NomosTestHarness> _harness() => NomosTestHarness.ephemeral(
+      deployJsonPaths: [_deployJson],
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      workspace: _workspace,
+    );
+
+void main() {
+  test(
+      'THE BLESSED SHAPE: mount → bind (preflight) → parentless birth in the session workspace → '
+      'follow(ref) → second client → directive — zero routing strings in app code', () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final harness = await _harness();
+    try {
+      // ENGINE + SESSION: the harness bridge IS the session handle pinned to the fixture workspace.
+      final home = harness.session(harness.workspace);
+
+      // BIND (ask 2/5): the async preflight — reachable, domain installed, shape-compatible.
+      final homeClient = await HomeClient.bind(home, actor: _owner);
+      expect(homeClient.session, isNotNull);
+      expect(homeClient.session!.workspace, harness.workspace,
+          reason: 'inspectable session context (ask 3)');
+
+      // PARENTLESS BIRTH (ask 4): no parent parameter — the parent IS the session workspace.
+      final birth = await homeClient.birthEstateWorkspace(
+        payload: BirthEstateWorkspacePayload(
+          owner: _owner,
+          frameworkHash: harness.frameworkHash!,
+          lawHash: harness.lawHashes(harness.workspace).first,
+          bornAt: DateTime.now().toUtc().toIso8601String(),
+        ),
+      );
+      expect(birth.workspace, harness.workspace,
+          reason: 'the birth offer landed in the SESSION workspace, no loose parent');
+      expect(birth.gatewayVerdict, isNull, reason: 'the local offer lane, not the legacy relay');
+      expect(birth.born, hasLength(1));
+      expect(birth.birthOutcomes.first['status'], 'born');
+
+      // FOLLOW THE REF (ask 8): NomosRef in, mounted session out — never a string pair.
+      final estate = await harness.bridge.follow(birth.bornRefs.single);
+      expect(estate.workspace, birth.born.single);
+
+      // SECOND CLIENT + a typed read AND a directive on it.
+      final estateClient = await EstateClient.bind(estate, actor: _owner);
+      final rows = await estateClient.estatesByOwner(owner: _owner);
+      expect(rows, hasLength(1), reason: 'the child genesis seed reads back typed');
+      final seeded = rows.single;
+      // A directive on the second client: re-ensure the singleton with the SAME seeded values
+      // (`.ensures` — idempotent; the squat invariant re-accepts its own binding).
+      final reseed = await estateClient.seedEstateWorkspace(SeedEstateWorkspacePayload(
+        owner: seeded.owner!,
+        estateName: seeded.estateName!,
+        bornAt: seeded.bornAt!,
+      ));
+      expect(reseed.head, isNotEmpty);
+
+      // ask 9: the harness diagnostic names the installed domains.
+      await harness.assertDomainInstalled(
+          workspace: estate.workspace, domain: EstateClient.interface.domain);
+    } finally {
+      await harness.dispose();
+    }
+  }, timeout: const Timeout(Duration(minutes: 4)));
+
+  test('bind on a deliberately WRONG session throws DomainClientSessionMismatch with every field',
+      () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    // TWO workspaces, TWO different laws, ONE plane — binding HomeClient to the docs
+    // workspace is the deliberate wrong-session case (wrong-package-mounted).
+    final harness = await NomosTestHarness.cluster(
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      workspaces: {
+        _workspace: [_deployJson],
+        'docs-ws': [_otherDeployJson],
+      },
+    );
+    try {
+      final wrong = harness.session('docs-ws');
+      Object? thrown;
+      try {
+        await HomeClient.bind(wrong);
+      } catch (e) {
+        thrown = e;
+      }
+      expect(thrown, isA<DomainClientSessionMismatch>(),
+          reason: 'the mismatch fires at CONSTRUCTION, not two clicks into the app');
+      final m = thrown! as DomainClientSessionMismatch;
+      expect(m.sessionId, 'docs-ws');
+      expect(m.sessionWorkspace, 'docs-ws');
+      expect(m.expectedDomainKey, HomeClient.interface.domain);
+      expect(m.expectedDomainHash, HomeClient.interface.expectedDomainHash);
+      expect(m.expectedInterfaceHash, HomeClient.interface.expectedInterfaceHash);
+      expect(m.activeDomainKeys, isNot(contains(m.expectedDomainKey)));
+      expect(m.cause, SessionMismatchCause.wrongPackageMounted,
+          reason: 'the docs workspace RUNS law — just not this domain');
+      expect(m.hint, isNotEmpty);
+      expect(m.toString(), contains(m.expectedDomainKey));
+
+      // The RIGHT session still binds (the plane is unharmed).
+      await HomeClient.bind(harness.session(harness.workspace));
+
+      // session.assertCompatible is directly usable from tests (ask 9), same typed refusal.
+      await expectLater(wrong.assertCompatible(EstateClient.interface),
+          throwsA(isA<DomainClientSessionMismatch>()));
+    } finally {
+      await harness.dispose();
+    }
+  }, timeout: const Timeout(Duration(minutes: 4)));
+
+  test(
+      'a dispatch naming an UNINSTALLED domain surfaces as DomainNotInstalledForSession '
+      '(context-rich, ask 6) — and the deprecated engine shims still function (ask 1/7)', () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final harness = await _harness();
+    try {
+      final session = harness.session(harness.workspace);
+      Object? thrown;
+      try {
+        await session.offerOutcome(
+            domain: 'not_installed_domain', directiveId: 'doIt', payload: const {});
+      } catch (e) {
+        thrown = e;
+      }
+      expect(thrown, isA<DomainNotInstalledForSession>());
+      final err = thrown! as DomainNotInstalledForSession;
+      expect(err.expectedDomainKey, 'not_installed_domain');
+      expect(err.sessionWorkspace, harness.workspace);
+      expect(err.requestedWorkspace, harness.workspace);
+      expect(err.activeDomainKeys, contains(HomeClient.interface.domain),
+          reason: 'the error NAMES what the workspace actually runs');
+      expect(err.possibleCauses, DomainNotInstalledForSession.defaultPossibleCauses);
+      expect(err.underlying.toString(), contains('no active installed law declares domain'));
+      expect(err.toString(), contains('Possible causes'));
+
+      // THE DEPRECATED SHIM still functions: the engine-level generic write authors fine.
+      // ignore: deprecated_member_use
+      final head = await session.offerDirective(
+        domain: HomeClient.interface.domain,
+        directiveId: 'birthEstateWorkspace',
+        payload: {
+          'owner': 'user:legacy-lane-owner',
+          'frameworkHash': harness.frameworkHash,
+          'lawHash': harness.lawHashes(harness.workspace).first,
+          'bornAt': DateTime.now().toUtc().toIso8601String(),
+        },
+        actor: 'user:legacy-lane-owner',
+      );
+      expect(head, isNotEmpty, reason: 'deprecation, not breakage — the old lane still writes');
+    } finally {
+      await harness.dispose();
+    }
+  }, timeout: const Timeout(Duration(minutes: 4)));
+
+  test('the SYNC constructor lazily preflights on first dispatch (the can\'t-await path)',
+      () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final harness = await NomosTestHarness.cluster(
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      workspaces: {
+        _workspace: [_deployJson],
+        'docs-ws': [_otherDeployJson],
+      },
+    );
+    try {
+      // Constructing synchronously on the wrong session succeeds (no await possible here)…
+      final client = HomeClient(harness.session('docs-ws'), actor: _owner);
+      // …but the FIRST dispatch runs the same preflight and throws the same typed mismatch.
+      await expectLater(
+        client.birthEstateWorkspace(
+          payload: BirthEstateWorkspacePayload(
+            owner: _owner,
+            frameworkHash: harness.frameworkHash!,
+            lawHash: harness.lawHashes(harness.workspace).first,
+            bornAt: DateTime.now().toUtc().toIso8601String(),
+          ),
+        ),
+        throwsA(isA<DomainClientSessionMismatch>()),
+      );
+    } finally {
+      await harness.dispose();
+    }
+  }, timeout: const Timeout(Duration(minutes: 4)));
+}

package/dart_types/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.2.0
+
+- `NomosPrincipal` / `NomosDeviceSecret` — branded identity types for the generated cross-workspace birth
+  methods (`.births()` directives). `actor`/`authorSecret` were previously bare, adjacent, same-shaped
+  strings — a transposition footgun with no compiler check. `NomosPrincipal.user(uid)`/`.parse('user:<uid>')`
+  and the opaque `NomosDeviceSecret` (redacts in `toString()`) make swapping them a type error. Purely
+  additive.
+
 ## 0.1.4
 
 - Custody-lifecycle types: `NomosCustodyBreak`, `NomosCustodyStatus`, `NomosCustodyEvent`,

package/dart_types/lib/nomos_types.dart

@@ -33,6 +33,12 @@ export 'src/errors.dart';
 export 'src/foreign_ref.dart';
 export 'src/activity.dart';
 export 'src/nomos_ref.dart';
+// 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';
 // 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';
+// SURFACED MERGE CONFLICTS (architecture/surfaced_merge_conflict.md): the read-collapse types for a
+// `.merge(Surfaced(...))` field — SurfacedValue<T> (resolved scalar | pending observations). Pure data.
+export 'src/surfaced.dart';