@githolon/dsl 0.101.5 → 0.102.0

package/dart/lib/src/test_harness.dart

@@ -1,6 +1,7 @@
 // NOMOS TEST HARNESS — an EPHEMERAL, FULLY-OFFLINE real-law fixture for headless app tests. One call
-// installs a tenant's compiled law into a FRESH LOCAL workspace (no cloud contact, ever), boots the REAL
-// githolon (the byte-identical wasm, the real ledger, the real gate) over [NodeRunnerTransport], and hands
+// installs a tenant's compiled law into a FRESH LOCAL application parent (no cloud contact, ever), performs
+// the same receiving-group birth a production application performs, boots the REAL githolon (the
+// byte-identical wasm, the real ledger, the real gate) over [NodeRunnerTransport], and hands
 // out a [NomosBridge] the generated Dart clients drive — the SAME surface the app UI uses — under
 // `flutter test` / `dart test` / CI.
 //
@@ -16,29 +17,69 @@
 // ```
 //
 // HOW IT STAYS OFFLINE. Two node children, both talking only to the local disk:
-//   1. `offline-install.ts` runs the PROVEN offline install lane (`githolon proof`'s adapter engine) —
-//      genesis → framework controller → each tenant package's `installDomain`, folded through the ONE gate —
-//      and serializes the workspace tree to a snapshot in a fresh temp dir.
+//   1. `offline-install.ts` runs the PROVEN offline install lane (`githolon proof`'s adapter engine) on a
+//      throwaway application parent — genesis → framework controller → each tenant package's
+//      `installDomain`, folded through the ONE gate — and serializes its tree to a fresh temp dir. Generated
+//      scenarios then birth their deterministic receiving group locally through the real declared birth.
 //   2. the node runner (`node-entry.ts`) boots in `NOMOS_OFFLINE=1` mode: it serves the runtime wasm from the
 //      local cache (`~/.holon/runtime`, filled by any warm `githolon` run) and boots the holon from that
 //      snapshot (`restoreFrom`). Every other URL is REFUSED — a stray fetch fails loudly, never reaches the net.
 //
-// PREREQUISITES (documented so a failure is legible): `node` on PATH; a resolvable
-// `@githolon/client/runner/node-entry.ts`; and a warm `~/.holon/runtime` cache (holon-testmint.wasm + packages.json —
-// one `githolon` run fills it). All local; no network at test time.
+// PREREQUISITES (documented so a failure is legible): `node` on PATH and the release-pinned runtime cache.
+// The self-contained runner + installer ship inside nomos_client; the kernel executable does not. A cold
+// runtime is acquired and content-addressed by the release tooling, then tests remain fully offline.
 //
 // PACKAGING NOTE: `offline-install.ts` imports the adapter engine, which today lives beside the in-repo
 // runner. For a PUBLISHED harness this install belongs behind a `githolon` subcommand (the CLI already
 // bundles the engine + this exact sequence in `proof_offline`); [installHelper] is the one seam to repoint.
+@internal
+library;
+
+import 'package:meta/meta.dart' show internal;
+
 import 'dart:convert';
 import 'dart:io';
 
 import 'package:crypto/crypto.dart' show sha256;
+import 'package:package_config/package_config.dart' show loadPackageConfigUri;
 
 import 'dev_cloud.dart';
 import 'node_runner_transport.dart';
+import 'session_bound.dart' show DomainNotInstalledForSession;
 import 'webview_bridge.dart' show NomosBridge, NomosSession;
 
+/// Framework-internal classifier for a sync result that can never become converged by retrying. Generated
+/// scenarios use it through [NomosTestHarness.converge]; it is public only inside `package:nomos_client/src`
+/// so the false-green contract has a cheap regression test without booting a cloud.
+String? nmsPermanentConvergenceFailure(Map<String, Object?> result) {
+  final admission = result['admission'];
+  final sessions = admission is Map && admission['sessions'] is List
+      ? admission['sessions'] as List
+      : const [];
+  final rejected = sessions
+      .whereType<Map>()
+      .expand((session) =>
+          session['rejected'] is List ? session['rejected'] as List : const [])
+      .toList();
+  final deadLetters = admission is Map && admission['deadLetters'] is List
+      ? admission['deadLetters'] as List
+      : const [];
+  final converged = result['converged'];
+  final replayDeadLetters =
+      converged is Map && converged['deadLettered'] is List
+          ? converged['deadLettered'] as List
+          : const [];
+  final pushError = result['pushError'];
+  final refused = pushError is Map && pushError['refused'] == true;
+  if (rejected.isEmpty &&
+      deadLetters.isEmpty &&
+      replayDeadLetters.isEmpty &&
+      !refused) {
+    return null;
+  }
+  return jsonEncode(result);
+}
+
 /// The offline-install lane configuration a harness keeps so the CUSTODY DIAGNOSTIC helpers
 /// (ask 9 of architecture/session_bound_clients.md) can re-run installs after construction:
 /// [seedWorkspaceFromDeployJson] / [resetWorkspaceCustody].
@@ -184,17 +225,16 @@ class NomosTestHarness {
   /// with [NomosTestCloud.setOnline]; assert remote custody with [NomosTestCloud.remoteHead].
   final NomosTestCloud? testCloud;
 
-  /// The HOME workspace a [cloudBound] harness mounted (born remotely by the platform ceremony). Null for
-  /// the offline constructors.
+  /// The primary application workspace. For [cloudBound] this is the identity home; for [ephemeral] it is
+  /// the one local application workspace. Internal restart logic uses it to reopen custody first.
   final String? homeWorkspace;
 
-  /// The mounted home as a [NomosSession] (the [cloudBound] app-shaped entry point — bind the generated
-  /// `HomeClient` to it). Throws for an offline harness (no home ceremony ran).
+  /// The primary mounted application session.
   NomosSession get homeSession {
     final ws = homeWorkspace;
     if (ws == null) {
       throw NomosTestHarnessException(
-          'homeSession is only available on a cloudBound harness (this one was built by ephemeral/cluster)');
+          'this harness has no primary application session');
     }
     return session(ws);
   }
@@ -266,6 +306,64 @@ class NomosTestHarness {
   /// `bridge.acquireSession(childWs, authorSecret: harness.deviceSecret(home))`.
   String? deviceSecret(String workspace) => _deviceSecrets[workspace];
 
+  /// Framework-private scenario setup for a business intent guarded by a delegated role.
+  /// Generated `scenario.given(person).mayX()` methods are the only caller: they name the
+  /// business permission while this harness mints and admits the real parent-rooted delegation.
+  /// Tenant tests never handle relation names, certificate bytes, signer secrets, or raw offers.
+  Future<void> nomosInternalAllowDelegatedScenarioAction({
+    required String domain,
+    required String acceptanceIntent,
+    required String relation,
+    required String subject,
+    required String subjectField,
+    required String certificateField,
+    Map<String, Object?> facts = const {},
+  }) async {
+    final secret = _deviceSecrets[workspace];
+    if (secret == null || secret.isEmpty) {
+      throw NomosTestHarnessException(
+          'the generated scenario cannot establish its business permission because the test device secret is unavailable');
+    }
+    final rows = await session(workspace)
+        .queryById('birth-attestation:self', null, subject);
+    if (rows.length != 1) {
+      throw NomosTestHarnessException(
+          'the generated scenario expected one verified birth attestation before establishing business permission; found ${rows.length}');
+    }
+    final row = rows.single;
+    final data = row['data'] is Map
+        ? (row['data'] as Map).cast<String, Object?>()
+        : row.cast<String, Object?>();
+    final rawChain = data['certChain'];
+    final decodedChain = rawChain is String ? jsonDecode(rawChain) : rawChain;
+    final links = decodedChain is Map && decodedChain['links'] is List
+        ? List<Object?>.from(decodedChain['links'] as List)
+        : const <Object?>[];
+    final issued = await session(workspace).issueDelegationCert(
+      signerSecret: secret,
+      grantorId: (data['parentId'] ?? workspace).toString(),
+      relation: relation,
+      subject: subject,
+      certChain: links,
+    );
+    final certificate = issued['certString']?.toString();
+    if (certificate == null || certificate.isEmpty) {
+      throw NomosTestHarnessException(
+          'the generated scenario could not mint the parent-rooted business delegation');
+    }
+    await session(workspace).offerOutcome(
+      domain: domain,
+      directiveId: acceptanceIntent,
+      actor: subject,
+      authorSecret: secret,
+      payload: <String, Object?>{
+        ...facts,
+        subjectField: subject,
+        certificateField: certificate,
+      },
+    );
+  }
+
   /// The workspace names on this device's local plane (one for [ephemeral], N for [cluster]).
   List<String> get sessions => List.unmodifiable(_sessionNames);
 
@@ -299,6 +397,7 @@ class NomosTestHarness {
   /// [autoTearDown] — when true (default) and [registerTearDown] is given, registers [dispose] as a teardown.
   static Future<NomosTestHarness> ephemeral({
     required List<String> deployJsonPaths,
+    String? ownerSubject,
     String workspace = 'test-ws',
     String clientId = 'test-runner',
     String? runtimeDir,
@@ -320,6 +419,9 @@ class NomosTestHarness {
     }
     final entry = nodeEntry ??
         await _resolveEntry(node, resolveFrom ?? Directory.current.path);
+    final effectiveRuntimeDir = runtimeDir ??
+        Platform.environment['NOMOS_DART_RUNTIME'] ??
+        Platform.environment['NOMOS_OFFLINE_RUNTIME'];
     // THE INSTALL LANE. [installHelper] is the one seam (PACKAGING NOTE above): either the in-repo
     // `offline-install.mjs` node script, OR the published `githolon harness-install` subcommand (the CLI
     // bundles the engine + this exact install sequence, so a published tenant needs nothing but `githolon`).
@@ -337,6 +439,18 @@ class NomosTestHarness {
             File(resolvedHelper).existsSync();
     final githolonCmd = installHelper == null ? 'npx githolon' : resolvedHelper;
 
+    final owner = ownerSubject?.trim();
+    final birthsApplicationHome = owner != null &&
+        owner.isNotEmpty &&
+        workspace == _receivingGroupNameOf(owner);
+    // A receiving-group address is not an arbitrary law-install target. It is valid only when a parent
+    // births it with the attestation, signer seating and warrant ordered into genesis. Generated scenarios
+    // therefore install their package on a private throwaway application parent and exercise the same local
+    // birth machinery production uses. Raw/law-focused harness callers keep their explicitly named workspace.
+    final installWorkspace = birthsApplicationHome
+        ? 'nms-app-${DateTime.now().microsecondsSinceEpoch.toRadixString(36)}'
+        : workspace;
+
     // A FRESH temp dir per harness — the snapshot + any transient runner state live here and nowhere else,
     // so dispose() leaves nothing behind.
     final workdir = await Directory.systemTemp.createTemp('nomos-harness-');
@@ -350,7 +464,7 @@ class NomosTestHarness {
       final info = await _phased(
           phase:
               '1/4: offline law install (${deployJsonPaths.length} package(s))',
-          workspace: workspace,
+          workspace: installWorkspace,
           awaiting: useInRepoScript
               ? 'offline-install.ts'
               : 'githolon harness-install',
@@ -366,11 +480,22 @@ class NomosTestHarness {
               inRepoScript: resolvedHelper,
               githolonCmd: githolonCmd,
               deployJsonPaths: deployJsonPaths,
-              workspace: workspace,
+              workspace: installWorkspace,
               snapshot: snapshot,
-              runtimeDir: runtimeDir,
+              runtimeDir: effectiveRuntimeDir,
               onDiagnostic: onDiagnostic));
 
+      final runnerEnvironment = <String, String>{
+        'NOMOS_OFFLINE': '1',
+        'NOMOS_OFFLINE_RESTORE': snapshot,
+        'NOMOS_OFFLINE_WASM': 'holon-testmint.wasm',
+        if (info['devicePublic'] != null)
+          'NOMOS_TEST_K_ROOT_PUBLIC': info['devicePublic'].toString(),
+        if (info['deviceSecret'] != null)
+          'NOMOS_TEST_ROOT_SECRET': info['deviceSecret'].toString(),
+        if (effectiveRuntimeDir != null)
+          'NOMOS_OFFLINE_RUNTIME': effectiveRuntimeDir,
+      };
       transport = await _phased(
           phase: '2/4: spawn the node runner',
           awaiting: 'Process.start($node)',
@@ -380,16 +505,7 @@ class NomosTestHarness {
                 entry: entry,
                 resolveFrom: resolveFrom,
                 node: node,
-                environment: {
-                  'NOMOS_OFFLINE': '1',
-                  'NOMOS_OFFLINE_RESTORE': snapshot,
-                  'NOMOS_OFFLINE_WASM': 'holon-testmint.wasm',
-                  if (info['devicePublic'] != null)
-                    'NOMOS_TEST_K_ROOT_PUBLIC': info['devicePublic'].toString(),
-                  if (info['deviceSecret'] != null)
-                    'NOMOS_TEST_ROOT_SECRET': info['deviceSecret'].toString(),
-                  if (runtimeDir != null) 'NOMOS_OFFLINE_RUNTIME': runtimeDir,
-                },
+                environment: runnerEnvironment,
                 onDiagnostic: onDiagnostic,
               ));
       final plane = NomosBridge(transport!);
@@ -405,7 +521,7 @@ class NomosTestHarness {
           run: () => plane.ready);
       await _phased(
           phase: '4/4: connect session',
-          workspace: workspace,
+          workspace: installWorkspace,
           awaiting: 'connect',
           timeout: phaseTimeout ?? connectTimeout,
           onDiagnostic: onDiagnostic,
@@ -416,7 +532,8 @@ class NomosTestHarness {
           run: () => plane.connect(
                 cloud:
                     'https://offline.invalid', // ignored: the offline runner serves everything locally
-                workspace: workspace,
+                workspace: installWorkspace,
+                session: installWorkspace,
                 clientId: clientId,
                 allowUnborn: true,
                 // THE HARNESS DEVICE (era-0): the install lane mints one device key per plane — sessions
@@ -424,6 +541,197 @@ class NomosTestHarness {
                 // with the SAME key, so offline `.births()` offers Just Work.
                 authorSecret: info['deviceSecret']?.toString(),
               ));
+      if (birthsApplicationHome) {
+        final devicePublic = info['devicePublic']?.toString();
+        final deviceSecret = info['deviceSecret']?.toString();
+        final framework = info['frameworkHash']?.toString();
+        final laws = ((info['lawHashes'] as List?) ?? const [])
+            .map((value) => value.toString())
+            .where((value) => value.isNotEmpty)
+            .toList();
+        if (devicePublic == null ||
+            devicePublic.isEmpty ||
+            deviceSecret == null ||
+            deviceSecret.isEmpty ||
+            framework == null ||
+            framework.isEmpty ||
+            laws.isEmpty) {
+          throw NomosTestHarnessException(
+              'the offline application parent did not return the framework law, application law and test device needed to birth the signed-in application');
+        }
+        final keyHash = sha256.convert(base64Decode(devicePublic)).toString();
+        final outcome = await _phased(
+          phase: 'application: birth the signed-in application',
+          workspace: workspace,
+          awaiting: 'attested receiving-group birth',
+          timeout: phaseTimeout ?? _kOtherDeadline,
+          onDiagnostic: onDiagnostic,
+          run: () => plane.session(installWorkspace).offerOutcome(
+            domain: '__nomos_application_home_v1',
+            directiveId: 'nomosInternalBirthReceivingGroup7c1f5e',
+            actor: owner,
+            authorSecret: deviceSecret,
+            payload: <String, Object?>{
+              'owner': owner,
+              'ownerKeyHash': keyHash,
+              'frameworkHash': framework,
+              'lawHash': laws.first,
+              'bornAt': DateTime.now().toUtc().toIso8601String(),
+            },
+          ),
+        );
+        String? bornStatus;
+        for (final entry in outcome.birthOutcomes) {
+          if (entry['workspace']?.toString() == workspace) {
+            bornStatus = entry['status']?.toString();
+            break;
+          }
+        }
+        if (outcome.born.length != 1 ||
+            outcome.born.single != workspace ||
+            bornStatus != 'born') {
+          throw NomosTestHarnessException(
+              'the offline application parent did not birth "$workspace" cleanly '
+              '(born=${outcome.born}, birthOutcomes=${outcome.birthOutcomes})');
+        }
+        await _phased(
+          phase: 'application: mount the signed-in application',
+          workspace: workspace,
+          awaiting: 'connect born receiving group',
+          timeout: phaseTimeout ?? connectTimeout,
+          onDiagnostic: onDiagnostic,
+          run: () => plane.connect(
+            cloud: 'https://offline.invalid',
+            workspace: workspace,
+            session: workspace,
+            clientId: '$clientId-home',
+            authorSecret: deviceSecret,
+          ),
+        );
+      } else if (owner != null && owner.isNotEmpty) {
+        final devicePublic = info['devicePublic']?.toString();
+        final deviceSecret = info['deviceSecret']?.toString();
+        if (devicePublic == null ||
+            devicePublic.isEmpty ||
+            deviceSecret == null ||
+            deviceSecret.isEmpty) {
+          throw NomosTestHarnessException(
+              'the offline install did not return the test device key needed to make "$owner" an application-ready signer');
+        }
+        try {
+          final keyHash = sha256.convert(base64Decode(devicePublic)).toString();
+          await _phased(
+            phase: 'owner: seat the test device signer',
+            workspace: workspace,
+            awaiting: 'verified test-root signer enrollment',
+            timeout: phaseTimeout ?? _kOtherDeadline,
+            onDiagnostic: onDiagnostic,
+            // A generated TestPerson stands in for a real signed-in person. Seat the throwaway
+            // harness device through the installed framework law with the same verified provenance
+            // that the private test root later attests. Production clients never manufacture this
+            // marker; it exists only inside the offline test-mint ceremony.
+            run: () => plane.session(workspace).offerOutcome(
+              domain: '__nomos_application_home_v1',
+              directiveId: 'enrollSigner',
+              actor: owner,
+              authorSecret: deviceSecret,
+              payload: <String, Object?>{
+                'keyHash': keyHash,
+                'grantedBy': owner,
+                'grantedAt': 1,
+                'verifiedVia': 'nomos:test-mint',
+              },
+            ),
+          );
+        } catch (error) {
+          // Pre-application-home packages neither expose nor enforce this
+          // signer route. Preserve their old harness behaviour, while keeping
+          // every refusal from a current package fatal.
+          if (!error.toString().contains(
+              "no active installed law declares domain '__nomos_application_home_v1'")) {
+            rethrow;
+          }
+        }
+        try {
+          final bornAt = DateTime.now().toUtc().toIso8601String();
+          await _phased(
+            phase: 'owner: make the test application ready',
+            workspace: workspace,
+            awaiting: 'framework owner birth',
+            timeout: phaseTimeout ?? _kOtherDeadline,
+            onDiagnostic: onDiagnostic,
+            run: () async {
+              await plane.session(workspace).offerOutcome(
+                domain: '__nomos_application_home_v1',
+                directiveId: 'nomosInternalSeedReceivingGroupPolicy7c1f5e',
+                actor: 'host-birth',
+                payload: <String, Object?>{'setAt': bornAt},
+              );
+              await plane.session(workspace).offerOutcome(
+                domain: '__nomos_application_home_v1',
+                directiveId: 'nomosInternalSeedReceivingGroup7c1f5e',
+                actor: 'host-birth',
+                payload: <String, Object?>{
+                  'principal': owner,
+                  'workspaceName': _receivingGroupNameOf(owner),
+                  'bornAt': bornAt,
+                },
+              );
+            },
+          );
+          final parentCert = await plane.signBirthCert(<String, Object?>{
+            'child': workspace,
+            'founder': owner,
+            'verified': true,
+            'parentKey': devicePublic,
+            'parentId': 'root',
+            'epoch': 0,
+          }, deviceSecret);
+          await _phased(
+            phase: 'owner: establish the verified test application root',
+            workspace: workspace,
+            awaiting: 'birth attestation then genesis warrant',
+            timeout: phaseTimeout ?? _kOtherDeadline,
+            onDiagnostic: onDiagnostic,
+            run: () async {
+              await plane.session(workspace).offerOutcome(
+                domain: '__nomos_application_home_v1',
+                directiveId: 'seedBirthAttestation',
+                actor: owner,
+                authorSecret: deviceSecret,
+                payload: <String, Object?>{
+                  'child': workspace,
+                  'founder': owner,
+                  'verified': 'true',
+                  'parentId': 'root',
+                  'parentKey': devicePublic,
+                  'epoch': 0,
+                  'certChain': jsonEncode(<String, Object?>{
+                    'links': <Object?>[parentCert],
+                  }),
+                },
+              );
+              await plane.session(workspace).offerOutcome(
+                domain: '__nomos_application_home_v1',
+                directiveId: 'seedGenesis',
+                actor: owner,
+                authorSecret: deviceSecret,
+                payload: <String, Object?>{
+                  'principal': owner,
+                  'workspaceId': workspace,
+                  'bornAt': '2000-01-01T00:00:00.000Z',
+                },
+              );
+            },
+          );
+        } on DomainNotInstalledForSession {
+          // Applications that do not declare the compiler-owned home domain do
+          // not have an owner seat to prepare. Only that precise absence is
+          // optional: a refusal from an installed home law must still fail the
+          // scenario, because hiding it would make an invalid fixture appear
+          // application-ready.
+        }
+      }
       phase(
           'ready — session "$workspace" connected (law ${(info['lawHashes'] as List?)?.isNotEmpty == true ? (info['lawHashes'] as List).first.toString().substring(0, 12) : "installed"})');
       // THE DECOY SESSION (multi-workspace by default in tests): sole-session inference is how
@@ -433,7 +741,7 @@ class NomosTestHarness {
       // dev's first test. [bridge] is a SESSION HANDLE pinned to [workspace], so tenant code written
       // against the harness keeps working unchanged; only code that grabs the raw plane and assumes
       // single-session trips. Opt out with `decoySession: false` (please don't).
-      if (decoySession) {
+      if (decoySession && !birthsApplicationHome) {
         await _phased(
             phase: 'decoy: connect the decoy session',
             workspace: _decoyWorkspace,
@@ -473,9 +781,20 @@ class NomosTestHarness {
               useInRepoScript: useInRepoScript,
               inRepoScript: resolvedHelper,
               githolonCmd: githolonCmd,
-              runtimeDir: runtimeDir,
+              runtimeDir: effectiveRuntimeDir,
               clientId: clientId),
-          phaseTimeout: phaseTimeout);
+          phaseTimeout: phaseTimeout,
+          cloudRestartLane: _CloudRestartLane(
+            entry: entry,
+            node: node,
+            cloud: 'https://offline.invalid',
+            authToken: '',
+            authorSecret: info['deviceSecret']?.toString() ?? '',
+            clientId: clientId,
+            resolveFrom: resolveFrom,
+            environment: runnerEnvironment,
+          ),
+          homeWorkspace: workspace);
       if (autoTearDown && registerTearDown != null) {
         registerTearDown(harness.dispose);
       }
@@ -535,6 +854,9 @@ class NomosTestHarness {
     }
     final entry = nodeEntry ??
         await _resolveEntry(node, resolveFrom ?? Directory.current.path);
+    final effectiveRuntimeDir = runtimeDir ??
+        Platform.environment['NOMOS_DART_RUNTIME'] ??
+        Platform.environment['NOMOS_OFFLINE_RUNTIME'];
     final adjacentInstaller = '${File(entry).parent.path}/offline-install.mjs';
     final resolvedHelper = installHelper ??
         (File(adjacentInstaller).existsSync()
@@ -579,7 +901,7 @@ class NomosTestHarness {
                 deployJsonPaths: e.value,
                 workspace: e.key,
                 snapshot: snap,
-                runtimeDir: runtimeDir,
+                runtimeDir: effectiveRuntimeDir,
                 onDiagnostic: onDiagnostic));
         snapshots[e.key] = snap;
         lawHashesByWs[e.key] = ((info['lawHashes'] as List?) ?? const [])
@@ -616,7 +938,8 @@ class NomosTestHarness {
                     'NOMOS_TEST_K_ROOT_PUBLIC': planeTestRootPublic,
                   if (planeTestRootSecret != null)
                     'NOMOS_TEST_ROOT_SECRET': planeTestRootSecret,
-                  if (runtimeDir != null) 'NOMOS_OFFLINE_RUNTIME': runtimeDir,
+                  if (effectiveRuntimeDir != null)
+                    'NOMOS_OFFLINE_RUNTIME': effectiveRuntimeDir,
                 },
                 onDiagnostic: onDiagnostic,
               ));
@@ -721,7 +1044,7 @@ class NomosTestHarness {
               useInRepoScript: useInRepoScript,
               inRepoScript: resolvedHelper,
               githolonCmd: githolonCmd,
-              runtimeDir: runtimeDir,
+              runtimeDir: effectiveRuntimeDir,
               clientId: clientId),
           phaseTimeout: phaseTimeout);
       if (autoTearDown && registerTearDown != null) {
@@ -881,15 +1204,16 @@ class NomosTestHarness {
             'cloudBound: no deploy.json carried a summary.domainHash — cannot run the birth ceremony (lawHash unknown)');
       }
       final birthRoutes = frameworkPostRoutes
-          .where((route) => route.directive == 'birthHome')
+          .where((route) =>
+              route.directive == 'nomosInternalBirthReceivingGroup7c1f5e')
           .toSet()
           .toList();
       if (birthRoutes.length != 1) {
         throw NomosTestHarnessException(
-            'cloudBound: the deployed package must expose exactly one semantic birthHome route; found ${birthRoutes.length}');
+            'cloudBound: the deployed package must expose exactly one framework receiving-group route; found ${birthRoutes.length}');
       }
       final applicationHomeDomain = birthRoutes.single.domain;
-      final birthHomePath = birthRoutes.single.path;
+      final birthReceivingGroupPath = birthRoutes.single.path;
       final enrollmentRoutes = frameworkPostRoutes
           .where((route) =>
               route.directive == 'enrollFirstDevice' &&
@@ -1008,7 +1332,7 @@ class NomosTestHarness {
             final delegationCert = await plane.mintKeylessDelegation({
               'user': subject,
               'deviceKey': publicB64,
-              'childName': _homeNameOf(subject),
+              'childName': _receivingGroupNameOf(subject),
               'parentId': platformWorkspace,
               'verifiedVia': issuer,
               'idpToken': idpToken,
@@ -1044,11 +1368,12 @@ class NomosTestHarness {
       await _phased(
           phase: '5/6: remote home-birth ceremony (attested)',
           workspace: platformWorkspace,
-          awaiting: 'POST /v2/workspaces/$platformWorkspace$birthHomePath',
+          awaiting:
+              'POST /v2/workspaces/$platformWorkspace$birthReceivingGroupPath',
           timeout: phaseTimeout ?? _kInstallDeadline,
           onDiagnostic: onDiagnostic,
           run: () async {
-            final homeName = _homeNameOf(subject);
+            final homeName = _receivingGroupNameOf(subject);
             final homeCert = await plane.signBirthCert({
               'child': homeName,
               'founder': subject,
@@ -1059,8 +1384,8 @@ class NomosTestHarness {
               'parentId': platformWorkspace,
               'epoch': 0,
             }, device.secret);
-            final out =
-                await post('/v2/workspaces/$platformWorkspace$birthHomePath', {
+            final out = await post(
+                '/v2/workspaces/$platformWorkspace$birthReceivingGroupPath', {
               'owner': subject,
               'ownerKeyHash': device.keyHash,
               'frameworkHash': frameworkHash,
@@ -1069,9 +1394,10 @@ class NomosTestHarness {
               'homeCert': jsonEncode(homeCert),
               'actor': subject,
               'authorSecret': device.secret,
-            }, headers: {
-              'x-nomos-auth': device.idpToken
-            });
+            },
+                headers: {
+                  'x-nomos-auth': device.idpToken
+                });
             final born = (out['born'] as List?) ?? const [];
             final bornNames = born
                 .map((b) => (b as Map)['workspace']?.toString())
@@ -1154,10 +1480,9 @@ class NomosTestHarness {
     }
   }
 
-  /// The framework home-slot derivation (`home-<sha256(subject)[0..40]>`) — the fallback when the birth
-  /// offer response carries no `born` surface (an older dev cloud).
-  static String _homeNameOf(String subject) =>
-      'home-${sha256.convert(utf8.encode(subject)).toString().substring(0, 40)}';
+  /// Compiler/runtime-only receiving-group address. The law independently re-derives the same value.
+  static String _receivingGroupNameOf(String principal) =>
+      'nomos-rg-${sha256.convert(utf8.encode(principal)).toString().substring(0, 40)}';
 
   /// CONVERGE local custody with the test cloud (co2 topology step 8): sync every connected session —
   /// PARENT-FIRST by connect order, so the home's chain lands remotely and its birth offer-effects create
@@ -1184,8 +1509,18 @@ class NomosTestHarness {
           final r = (await bridge.session(ws).sync(admit: true))
               .cast<String, Object?>();
           last[ws] = r;
-          if (r['pushFailed'] != true && r['stillAhead'] != true)
-            pending.remove(ws);
+          final permanentFailure = nmsPermanentConvergenceFailure(r);
+          if (permanentFailure != null) {
+            throw NomosTestHarnessException(
+              'converge: $ws rejected or dead-lettered business work — $permanentFailure',
+            );
+          }
+          if (r['pushFailed'] != true &&
+              r['stillAhead'] != true &&
+              r['offline'] != true &&
+              r['deferred'] != true) pending.remove(ws);
+        } on NomosTestHarnessException {
+          rethrow;
         } catch (e) {
           last[ws] = {'error': e.toString()};
         }
@@ -1403,7 +1738,7 @@ class NomosTestHarness {
     final home = homeWorkspace;
     if (lane == null || home == null) {
       throw NomosTestHarnessException(
-          'restart() is available on a cloudBound harness');
+          'restart() requires a harness with one primary application session');
     }
 
     final oldPlane = _plane;
@@ -1490,9 +1825,63 @@ class NomosTestHarness {
     }
   }
 
-  /// Deterministic, idempotent, total-ordered teardown: stop the runner (SIGTERM → 5s deadline → SIGKILL,
-  /// via [NodeRunnerTransport.dispose]), then delete the temp dir. Safe to call twice; safe to call after a
-  /// failed setup. Nothing left running, nothing left on disk.
+  /// Simulate reinstalling the application with no local ledger custody. Every application workspace must
+  /// reopen from remote custody; a successful business read afterward is therefore a replay proof, not a
+  /// read from the old process snapshot.
+  Future<void> reinstall() async {
+    if (_disposed) {
+      throw NomosTestHarnessException(
+          'reinstall(): this test device has already been disposed');
+    }
+    final lane = _cloudRestartLane;
+    final home = homeWorkspace;
+    if (lane == null || home == null || testCloud == null) {
+      throw NomosTestHarnessException(
+          'reinstall() requires a connected scenario with remote custody');
+    }
+
+    final oldPlane = _plane;
+    final targets = oldPlane.connectedSessions
+        .where(
+            (ws) => ws != _decoyWorkspace && !ws.endsWith('-onboard-scratch'))
+        .toList();
+    if (targets.remove(home)) targets.insert(0, home);
+    for (final ws in targets) {
+      await oldPlane.session(ws).stopAutoSync();
+    }
+    await _transport.dispose();
+
+    _transport = await NodeRunnerTransport.start(
+      entry: lane.entry,
+      resolveFrom: lane.resolveFrom,
+      node: lane.node,
+      environment: lane.environment,
+      onDiagnostic: _onDiagnostic,
+    );
+    final reinstalled = NomosBridge(_transport);
+    await reinstalled.ready;
+    for (final ws in targets) {
+      await reinstalled.connect(
+        cloud: lane.cloud,
+        workspace: ws,
+        session: ws,
+        clientId: '${lane.clientId}-reinstall-$ws',
+        authToken: lane.authToken,
+        authorSecret: lane.authorSecret,
+      );
+    }
+    bridge = reinstalled.session(home);
+    _sessionNames
+      ..clear()
+      ..addAll(targets);
+    for (final ws in targets) {
+      await reinstalled.session(ws).autoSync(fallbackMs: 60000);
+    }
+  }
+
+  /// Deterministic, idempotent, total-ordered teardown: close the bridge and all live watches, stop the runner
+  /// (SIGTERM → 5s deadline → SIGKILL, via [NodeRunnerTransport.dispose]), then delete the temp dir. Safe to
+  /// call twice; safe to call after a failed setup. Nothing left running, nothing left on disk.
   /// Disposal must ALWAYS complete (never leave a hung teardown holding the test runner): the transport
   /// dispose is deadlined too, and a breach is LOGGED (not thrown — throwing from teardown would mask the
   /// test's own outcome) before the temp dir is still deleted.
@@ -1502,6 +1891,20 @@ class NomosTestHarness {
     final f = _onDiagnostic;
     if (f != null)
       f('[nomos-test-harness] phase dispose (≤${(_phaseTimeout ?? _kOtherDeadline).inSeconds}s) …');
+    try {
+      // The bridge owns the transport's one message subscription and every watch controller. Closing the
+      // transport first makes its incoming stream wait on consumers that can no longer receive their
+      // unwatch/done messages—a deterministic teardown deadlock in reactive Flutter tests.
+      await _plane.dispose().timeout(_phaseTimeout ?? _kOtherDeadline,
+          onTimeout: () => throw HarnessPhaseTimeout(
+              phase: 'dispose: close bridge watches',
+              workspace: workspace,
+              elapsed: _phaseTimeout ?? _kOtherDeadline,
+              awaiting: 'NomosBridge.dispose'));
+    } catch (e) {
+      _diag(
+          '[nomos-test-harness] bridge dispose error (continuing to runner cleanup): $e');
+    }
     try {
       await _transport.dispose().timeout(_phaseTimeout ?? _kOtherDeadline,
           onTimeout: () => throw HarnessPhaseTimeout(
@@ -1583,7 +1986,7 @@ class NomosTestHarness {
     }
     if (r.exitCode != 0) {
       throw NomosTestHarnessException(
-          'offline law install failed (exit ${r.exitCode}): ${err.isEmpty ? "(no stderr)" : err}');
+          'offline law install for "$workspace" failed (exit ${r.exitCode}): ${err.isEmpty ? "(no stderr)" : err}');
     }
     // The helper prints one JSON line on success; verify it before spawning the runner.
     final out = (r.stdout as String).trim();
@@ -1603,6 +2006,34 @@ class NomosTestHarness {
   }
 
   static Future<String> _resolveEntry(String node, String from) async {
+    String? packageConfigPath = Platform.packageConfig;
+    if (packageConfigPath == null) {
+      var directory = Directory(from).absolute;
+      while (true) {
+        final candidate = File(
+          '${directory.path}${Platform.pathSeparator}.dart_tool${Platform.pathSeparator}package_config.json',
+        );
+        if (candidate.existsSync()) {
+          packageConfigPath = candidate.uri.toString();
+          break;
+        }
+        final parent = directory.parent;
+        if (parent.path == directory.path) break;
+        directory = parent;
+      }
+    }
+    if (packageConfigPath != null) {
+      final packages = await loadPackageConfigUri(
+        Uri.base.resolve(packageConfigPath),
+      );
+      final bundled = packages.resolve(
+        Uri.parse('package:nomos_client/src/runner/node-entry.mjs'),
+      );
+      if (bundled != null && bundled.scheme == 'file') {
+        final path = bundled.toFilePath();
+        if (File(path).existsSync()) return path;
+      }
+    }
     // PREFER the BUILT .mjs (the published-consumer entry): node refuses type-stripping under node_modules
     // (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING — co2 DEFECT P3-002), so the raw .ts entry only boots
     // in-repo. The .mjs ships from @githolon/client ≥0.97.2; the .ts fallback keeps in-repo dev working.
@@ -1619,8 +2050,9 @@ class NomosTestHarness {
       if (r.exitCode == 0 && out.isNotEmpty) return out;
     }
     throw NomosTestHarnessException(
-        'cannot resolve @githolon/client/runner/node-entry.{mjs,ts} from $from — '
-        'is @githolon/client installed (npm install)? Pass nodeEntry: to override.');
+        'the Nomos release contains no bundled node runner and '
+        '@githolon/client/runner/node-entry.{mjs,ts} cannot be resolved from $from. '
+        'Reinstall nomos_client, or pass nodeEntry: only when developing Nomos itself.');
   }
 }