@githolon/dsl 0.103.3 → 0.103.5

package/dart/lib/src/session_bound.dart

@@ -134,6 +134,11 @@ class DomainClientSessionMismatch implements Exception {
     required this.hint,
   });
 
+  /// True only for the one bind failure a staged generated successor can
+  /// lawfully resolve by proving itself against this workspace's history.
+  bool get canAttemptGeneratedModelAdoption =>
+      cause == SessionMismatchCause.clientExpectsNewerInterface;
+
   @override
   String toString() =>
       'DomainClientSessionMismatch: session "${sessionId ?? '(unbound)'}" (workspace '
@@ -145,6 +150,93 @@ class DomainClientSessionMismatch implements Exception {
       'active law: ${activeDomainHashes.isEmpty ? '(unknown)' : activeDomainHashes.join(', ')})';
 }
 
+/// A generated candidate reached the lawful model-adoption boundary while
+/// binding, but exact-history proof requires a deliberate business decision or
+/// could not complete. The old model remains active and no compatibility
+/// fallback is used.
+enum DomainModelDifferenceKind { rules, outcome, evidence }
+
+final class DomainModelDifference {
+  final DomainModelDifferenceKind kind;
+  final String? area;
+  final String? action;
+  final String summary;
+
+  const DomainModelDifference({
+    required this.kind,
+    this.area,
+    this.action,
+    required this.summary,
+  });
+}
+
+final class DomainModelReview {
+  final int checkedActions;
+  final int candidateActions;
+  final bool? sameOutcome;
+  final List<DomainModelDifference> differences;
+
+  const DomainModelReview({
+    required this.checkedActions,
+    required this.candidateActions,
+    required this.sameOutcome,
+    required this.differences,
+  });
+}
+
+class DomainClientModelAdoptionRequired implements Exception {
+  final String expectedDomainKey;
+  final String expectedDomainHash;
+  final String status;
+  final String summary;
+  final DomainModelReview review;
+  final Future<void> Function()? _stage;
+  final Future<void> Function(String reason)? _accept;
+
+  const DomainClientModelAdoptionRequired({
+    required this.expectedDomainKey,
+    required this.expectedDomainHash,
+    required this.status,
+    required this.summary,
+    required this.review,
+    Future<void> Function()? stage,
+    Future<void> Function(String reason)? accept,
+  })  : _stage = stage,
+        _accept = accept;
+
+  bool get canStage => _stage != null;
+
+  Future<void> stage() {
+    final stage = _stage;
+    if (stage == null) {
+      throw StateError('This generated model is not waiting to be staged.');
+    }
+    return stage();
+  }
+
+  bool get canAccept => _accept != null;
+
+  Future<void> accept(String reason) {
+    final value = reason.trim();
+    if (value.isEmpty) {
+      throw ArgumentError.value(
+        reason,
+        'reason',
+        'must explain why changing prior business outcomes is intended',
+      );
+    }
+    final accept = _accept;
+    if (accept == null) {
+      throw StateError('This generated model change cannot be accepted.');
+    }
+    return accept(value);
+  }
+
+  @override
+  String toString() => 'DomainClientModelAdoptionRequired: generated model for '
+      '"$expectedDomainKey" ($expectedDomainHash) is $status. $summary';
+}
+
 /// The context-rich replacement for the kernel's generic
 /// `no active installed law declares domain 'x' … deploy the domain package first` refusal —
 /// thrown wherever that error used to surface (bridge dispatch, birth lanes) so an app dev sees
@@ -287,11 +379,17 @@ extension NomosSessionCompat on NomosSession {
     // 4. CLASSIFY the four causes (ask 9).
     SessionMismatchCause cause;
     String hint;
-    if (incompatible.isNotEmpty) {
+    if (nmsInternalClientExpectsNewerInterface(
+      domain: iface.domain,
+      activeDomainKeys: activeKeys,
+      missing: missing,
+      incompatible: incompatible,
+    )) {
       cause = SessionMismatchCause.clientExpectsNewerInterface;
+      final differences = [...incompatible, ...missing];
       hint =
           'the domain is installed but type-divergent from what this client requires '
-          '(${incompatible.join('; ')}) — recompile the client against the deployed law, or evolve the law';
+          '(${differences.join('; ')}) — recompile the client against the deployed law, or evolve the law';
     } else if (activeKeys.isNotEmpty && !activeKeys.contains(iface.domain)) {
       cause = SessionMismatchCause.wrongPackageMounted;
       hint =
@@ -334,3 +432,14 @@ extension NomosSessionCompat on NomosSession {
     );
   }
 }
+
+/// Generator/runtime classification seam. A required member missing from an
+/// already installed domain is a newer-client shape, not an absent deployment.
+bool nmsInternalClientExpectsNewerInterface({
+  required String domain,
+  required List<String> activeDomainKeys,
+  required List<String> missing,
+  required List<String> incompatible,
+}) =>
+    incompatible.isNotEmpty ||
+    (missing.isNotEmpty && activeDomainKeys.contains(domain));

package/dart/lib/src/test_harness.dart

@@ -46,7 +46,25 @@ 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;
+import 'webview_bridge.dart'
+    show NomosBirthCertificateSpec, NomosBridge, NomosSession;
+
+enum _KernelRuntimeArtifact {
+  executable('holon.wasm'),
+  stageZeroLaw('bootstrap.law.usdz'),
+  controllerLaw('nomos.law.usdz');
+
+  const _KernelRuntimeArtifact(this.fileName);
+  final String fileName;
+}
+
+enum _CandidateKernelBinary {
+  production('holon.wasm'),
+  testMint('holon-testmint.wasm');
+
+  const _CandidateKernelBinary(this.fileName);
+  final String fileName;
+}
 
 /// A source checkout is itself a coordinated release candidate: compiler, framework packages and kernels
 /// move together. Generated scenarios must not combine those source-generated laws with a recently-written
@@ -697,7 +715,6 @@ class NomosTestHarness {
             '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 bornAt = DateTime.now().toUtc().toIso8601String();
         await _phased(
           phase: 'application: establish the parent birth policy',
@@ -734,7 +751,6 @@ class NomosTestHarness {
             authorSecret: deviceSecret,
             payload: <String, Object?>{
               'owner': owner,
-              'ownerKeyHash': keyHash,
               'frameworkHash': framework,
               // Ordered application deployment is reference packages first, deferred child payload last.
               // The parent serves the references; the receiving group is born with only its payload law.
@@ -845,14 +861,16 @@ class NomosTestHarness {
               );
             },
           );
-          final parentCert = await plane.signBirthCert(<String, Object?>{
-            'child': workspace,
-            'founder': owner,
-            'verified': true,
-            'parentKey': devicePublic,
-            'parentId': 'root',
-            'epoch': 0,
-          }, deviceSecret);
+          final parentCert = await plane.signBirthCert(
+              NomosBirthCertificateSpec(
+                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,
@@ -873,7 +891,7 @@ class NomosTestHarness {
                   'parentKey': devicePublic,
                   'epoch': 0,
                   'certChain': jsonEncode(<String, Object?>{
-                    'links': <Object?>[parentCert],
+                    'links': <Object?>[parentCert.toWire()],
                   }),
                 },
               );
@@ -1512,38 +1530,62 @@ class NomosTestHarness {
       }
       // 2/6 — the LOCAL engine plane, CLOUD-BOUND, spawned BEFORE the birth: the runner's local kernel is
       //       what mints the device key + signs the birth cert (era-0: a birth is ATTESTED or not at all).
-      // The executable is device custody too. A process restart while offline must not fetch the kernel
-      // before it can replay the persisted ledger. Release CI supplies the exact candidate runtime. An
-      // ordinary local test pins the exact kernel advertised by its ephemeral cloud while still online;
-      // never fall back to a possibly stale global cache.
+      // The executable AND its framework-law packages are one runtime bundle in device custody. A process
+      // restart while offline must not fetch any member before it can replay the persisted ledger. Release CI
+      // supplies the exact candidate bundle. An ordinary local test pins all three artifacts advertised by its
+      // ephemeral cloud while still online; never combine a candidate kernel with stale framework law.
       final candidateRuntimeDir = Platform.environment['NOMOS_DART_RUNTIME'] ??
           Platform.environment['NOMOS_OFFLINE_RUNTIME'];
-      var localWasm = candidateRuntimeDir == null
-          ? ''
-          : '$candidateRuntimeDir/${cloud.testKRootPublic == null ? 'holon.wasm' : 'holon-testmint.wasm'}';
-      if (localWasm.isEmpty || !File(localWasm).existsSync()) {
-        localWasm = '${workdir.path}/client-kernel.wasm';
+      final localRuntime = await Directory('${workdir.path}/client-runtime')
+          .create(recursive: true);
+      final selectedKernel = cloud.testKRootPublic == null
+          ? _CandidateKernelBinary.production
+          : _CandidateKernelBinary.testMint;
+      final candidateArtifacts = candidateRuntimeDir == null
+          ? const <_KernelRuntimeArtifact, String>{}
+          : <_KernelRuntimeArtifact, String>{
+              _KernelRuntimeArtifact.executable:
+                  '$candidateRuntimeDir/${selectedKernel.fileName}',
+              _KernelRuntimeArtifact.stageZeroLaw:
+                  '$candidateRuntimeDir/${_KernelRuntimeArtifact.stageZeroLaw.fileName}',
+              _KernelRuntimeArtifact.controllerLaw:
+                  '$candidateRuntimeDir/${_KernelRuntimeArtifact.controllerLaw.fileName}',
+            };
+      final hasCandidateBundle = candidateArtifacts.length ==
+              _KernelRuntimeArtifact.values.length &&
+          candidateArtifacts.values.every((path) => File(path).existsSync());
+      if (hasCandidateBundle) {
+        for (final artifact in candidateArtifacts.entries) {
+          await File(artifact.value)
+              .copy('${localRuntime.path}/${artifact.key.fileName}');
+        }
+      } else {
         await _phased(
-          phase: '2/6: pin the client kernel for offline restart',
-          awaiting: 'GET /v1/runtime/holon.wasm',
+          phase: '2/6: pin the client runtime bundle for offline restart',
+          awaiting: 'GET kernel + framework USDA packages',
           timeout: phaseTimeout ?? _kInstallDeadline,
           onDiagnostic: onDiagnostic,
           run: () async {
-            final request = await http.getUrl(
-              Uri.parse('${cloud.origin}/v1/runtime/holon.wasm'),
-            );
-            final response = await request.close();
-            final bytes = await response.fold<List<int>>(
-              <int>[],
-              (all, chunk) => all..addAll(chunk),
-            );
-            if (response.statusCode != HttpStatus.ok || bytes.length < 1024) {
-              throw NomosTestHarnessException(
-                'cloudBound: could not pin the client kernel before going offline '
-                '(status ${response.statusCode}, ${bytes.length} bytes)',
+            for (final artifact in _KernelRuntimeArtifact.values) {
+              final request = await http.getUrl(
+                Uri.parse(
+                  '${cloud.origin}/v1/runtime/${artifact.fileName}',
+                ),
               );
+              final response = await request.close();
+              final bytes = await response.fold<List<int>>(
+                <int>[],
+                (all, chunk) => all..addAll(chunk),
+              );
+              if (response.statusCode != HttpStatus.ok || bytes.isEmpty) {
+                throw NomosTestHarnessException(
+                  'cloudBound: could not pin runtime artifact ${artifact.name} before going offline '
+                  '(status ${response.statusCode}, ${bytes.length} bytes)',
+                );
+              }
+              await File('${localRuntime.path}/${artifact.fileName}')
+                  .writeAsBytes(bytes, flush: true);
             }
-            await File(localWasm).writeAsBytes(bytes, flush: true);
           },
         );
       }
@@ -1551,7 +1593,7 @@ class NomosTestHarness {
         ...Platform.environment,
         if (cloud.testKRootPublic != null)
           'NOMOS_TEST_K_ROOT_PUBLIC': cloud.testKRootPublic!,
-        'NOMOS_LOCAL_WASM': localWasm,
+        'NOMOS_LOCAL_RUNTIME_DIR': localRuntime.path,
       };
       transport = await _phased(
         phase: '2/6: spawn the node runner (cloud-bound)',
@@ -1684,8 +1726,7 @@ class NomosTestHarness {
       // 5/6 — THE HOME CEREMONY. Author the birth in the already-mounted PARENT kernel, then sync its sealed
       //       intent to the remote parent where the same offer gate replays it. The HTTP host never receives
       //       business fields or a signing secret and has no birth-authoring lane. The offer carries the
-      //       device-signed homeCert + the owner's device keyHash (the home's genesis ENROLS it, so the born
-      //       home is SIGNER-READY — it can birth its own estates/catalogues from intent 0).
+      //       typed device-signed certificate. The kernel derives and enrolls the founding signer from it.
       String? home;
       await _phased(
         phase: '5/6: remote home-birth ceremony (attested)',
@@ -1700,31 +1741,33 @@ class NomosTestHarness {
           // platform session explicitly; relying on the single-session convenience API becomes
           // ambiguous as soon as the ceremony correctly opens the target workspace in-kernel.
           final homeCert =
-              await plane.session('$clientId-platform-author').signBirthCert({
-            'child': homeName,
-            'founder': subject,
-            // The cert's `verified` must MATCH the gate verdict (CAS-as-law): the offer carries the
-            // dev-IdP token, so the gate resolves a VERIFIED founder.
-            'verified': true,
-            'parentKey': device.publicB64,
-            'parentId': platformWorkspace,
-            'epoch': 0,
-          }, device.secret);
+              await plane.session('$clientId-platform-author').signBirthCert(
+                    NomosBirthCertificateSpec(
+                      child: homeName,
+                      founder: subject,
+                      // The cert's `verified` must MATCH the gate verdict (CAS-as-law): the offer carries
+                      // the dev-IdP token, so the gate resolves a VERIFIED founder.
+                      verified: true,
+                      parentKey: device.publicB64,
+                      parentId: platformWorkspace,
+                      epoch: 0,
+                    ),
+                    device.secret,
+                  );
           final localBirth =
               await plane.session('$clientId-platform-author').offerOutcome(
-            domain: applicationHomeDomain,
-            directiveId: 'nomosInternalBirthReceivingGroup7c1f5e',
-            actor: subject,
-            authorSecret: device.secret,
-            payload: <String, Object?>{
-              'owner': subject,
-              'ownerKeyHash': device.keyHash,
-              'frameworkHash': frameworkHash,
-              'lawHash': applicationHomeLawHash,
-              'bornAt': DateTime.now().toUtc().toIso8601String(),
-              'homeCert': jsonEncode(homeCert),
-            },
-          );
+                    domain: applicationHomeDomain,
+                    directiveId: 'nomosInternalBirthReceivingGroup7c1f5e',
+                    actor: subject,
+                    authorSecret: device.secret,
+                    payload: <String, Object?>{
+                      'owner': subject,
+                      'frameworkHash': frameworkHash,
+                      'lawHash': applicationHomeLawHash,
+                      'bornAt': DateTime.now().toUtc().toIso8601String(),
+                    },
+                    birthCertificate: homeCert,
+                  );
           if (!localBirth.born.contains(homeName)) {
             throw NomosTestHarnessException(
               'cloudBound: the local parent kernel admitted the receiving-group offer but did not birth '
@@ -1774,12 +1817,22 @@ class NomosTestHarness {
           // A PRIVATE home (declared read caps — co2's shape) serves its ledger only to a VERIFIED
           // principal: ride the caller's token when given, else the dev-IdP token the ceremony minted.
           authToken: authToken ?? device.idpToken,
-          // The home was born WARRANTED with THIS device enrolled in its genesis (ownerKeyHash) —
+          // The home was born WARRANTED with THIS device enrolled by the kernel-owned attestation step —
           // connect with the same key so every write is signed and the home's own `.births()` offers
           // (estates/catalogues) are device-attested (the client signs the birth cert automatically).
           authorSecret: device.secret,
         ),
       );
+      // A cloud-bound generated application owns continuous convergence from the moment its home is
+      // mounted. Starting it here makes the harness exercise the product lifecycle: local writes flush,
+      // transport debt survives a partition, and reconnect settles exact operation receipts without tenant
+      // code calling sync(). Child sessions take the same path in acquireSession().
+      final applicationSession = plane.session(home!);
+      applicationSession.nomosInternalRetainCloudAccess(
+        cloud: cloud.origin,
+        signIn: () async => authToken ?? device.idpToken,
+      );
+      await applicationSession.autoSync(fallbackMs: 60000);
       // NO DECOY on a cloudBound harness: the app is genuinely multi-workspace (the home plus every
       // locally-born child), so the plane is never sole-session — the decoy the offline  harness
       // needs (to break single-session inference) would just be a spurious local-only workspace here.
@@ -1792,9 +1845,7 @@ class NomosTestHarness {
         workdir,
         onDiagnostic,
         [home!],
-        // The owner's device (enrolled in the home's genesis via ownerKeyHash) — the app derives the
-        // keyHash for its own `.births()` payloads from [devicePublicKey] and signs locally-born-child
-        // sessions with [deviceSecret].
+        // The owner's device (enrolled by the typed birth attestation) signs later child births locally.
         devicePublics: {home!: device.publicB64},
         deviceSecrets: {home!: device.secret},
         frameworkHash: frameworkHash,