@githolon/dsl 0.101.1 → 0.101.3

package/dart/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.63.1
+
+- Make automatic sync a truthful client-owned lifecycle: local acceptance is durable, offline/restored
+  sessions remain usable, reconnect converges parent before child, and failed/offline sync never reports a
+  successful timestamp.
+- Make home bootstrap and designated recovery resumable across interruption, exposing one typed next action
+  while keeping identity proofs, signers, custody wrapping and retry state private.
+- Expand the generated CO2 gauntlet through application, home, Estate, Site and Asset with two offline
+  devices, process restart, conflict merge, automatic convergence and cold replay.
+
 ## 0.63.0
 
 - Generated clients now expose business-first conflict policy, schema-aware merge continuation and recursive

package/dart/lib/src/test_harness.dart

@@ -107,17 +107,39 @@ class HarnessPhaseTimeout extends NomosTestHarnessException {
 /// so the plane is ALWAYS multi-session in tests (sole-session inference never silently passes).
 const String _decoyWorkspace = '__nomos-decoy';
 
+class _CloudRestartLane {
+  const _CloudRestartLane({
+    required this.entry,
+    required this.node,
+    required this.cloud,
+    required this.authToken,
+    required this.authorSecret,
+    required this.clientId,
+    this.resolveFrom,
+    this.environment,
+  });
+
+  final String entry;
+  final String node;
+  final String cloud;
+  final String authToken;
+  final String authorSecret;
+  final String clientId;
+  final String? resolveFrom;
+  final Map<String, String>? environment;
+}
+
 class NomosTestHarness {
   /// The connected bridge — hand it to the generated typed clients (the same surface the app UI uses).
   /// For [ephemeral] this is a [NomosSession] HANDLE pinned to [workspace] (the plane underneath also
   /// holds a decoy session, so unpinned plane-level calls refuse the way they would in a real
   /// multi-workspace app); for [cluster] it is the shared plane — name sessions via [session].
-  final NomosBridge bridge;
+  NomosBridge bridge;
 
   /// The local workspace name the law was installed into.
   final String workspace;
 
-  final NodeRunnerTransport _transport;
+  NodeRunnerTransport _transport;
   final Directory _workdir;
   final void Function(String line)? _onDiagnostic;
   bool _disposed = false;
@@ -154,6 +176,10 @@ class NomosTestHarness {
   /// When set, overrides EVERY phase's default deadline (see [HarnessPhaseTimeout]).
   final Duration? _phaseTimeout;
 
+  /// Private process-restart inputs for a cloud-bound test device. Tests use [restart]; credentials,
+  /// snapshots, runner setup and parent-first session reopening remain framework-owned.
+  final _CloudRestartLane? _cloudRestartLane;
+
   /// The test cloud a [cloudBound] harness runs against (null for the offline constructors). Partition it
   /// with [NomosTestCloud.setOnline]; assert remote custody with [NomosTestCloud.remoteHead].
   final NomosTestCloud? testCloud;
@@ -182,6 +208,7 @@ class NomosTestHarness {
       Map<String, String> snapshots = const {},
       _InstallLane? installLane,
       Duration? phaseTimeout,
+      _CloudRestartLane? cloudRestartLane,
       this.testCloud,
       this.homeWorkspace})
       : _sessionNames = List.of(
@@ -191,7 +218,8 @@ class NomosTestHarness {
         _lawHashes = Map.of(lawHashes),
         _snapshots = Map.of(snapshots),
         _installLane = installLane,
-        _phaseTimeout = phaseTimeout;
+        _phaseTimeout = phaseTimeout,
+        _cloudRestartLane = cloudRestartLane;
 
   // ── THE "NO SILENT HANGS" MACHINERY — every lifecycle await runs as a named, deadlined PHASE ──
 
@@ -875,6 +903,43 @@ class NomosTestHarness {
       final enrollFirstDevicePath = enrollmentRoutes.single.path;
       // 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.
+      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';
+        await _phased(
+          phase: '2/6: pin the client kernel for offline restart',
+          awaiting: 'GET /v1/runtime/holon.wasm',
+          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)');
+            }
+            await File(localWasm).writeAsBytes(bytes, flush: true);
+          },
+        );
+      }
+      final runnerEnvironment = <String, String>{
+        ...Platform.environment,
+        if (cloud.testKRootPublic != null)
+          'NOMOS_TEST_K_ROOT_PUBLIC': cloud.testKRootPublic!,
+        'NOMOS_LOCAL_WASM': localWasm,
+      };
       transport = await _phased(
           phase: '2/6: spawn the node runner (cloud-bound)',
           awaiting: 'Process.start($node)',
@@ -884,12 +949,7 @@ class NomosTestHarness {
               entry: entry,
               resolveFrom: resolveFrom,
               node: node,
-              environment: cloud.testKRootPublic == null
-                  ? null
-                  : {
-                      ...Platform.environment,
-                      'NOMOS_TEST_K_ROOT_PUBLIC': cloud.testKRootPublic!,
-                    },
+              environment: runnerEnvironment,
               onDiagnostic: onDiagnostic));
       final plane = NomosBridge(transport!);
       await _phased(
@@ -1064,6 +1124,16 @@ class NomosTestHarness {
         frameworkHash: frameworkHash,
         lawHashes: {home!: lawHashes},
         phaseTimeout: phaseTimeout,
+        cloudRestartLane: _CloudRestartLane(
+          entry: entry,
+          resolveFrom: resolveFrom,
+          node: node,
+          environment: runnerEnvironment,
+          cloud: cloud.origin,
+          authToken: authToken ?? device.idpToken,
+          authorSecret: device.secret,
+          clientId: clientId,
+        ),
         testCloud: cloud,
         homeWorkspace: home,
       );
@@ -1250,8 +1320,12 @@ class NomosTestHarness {
   /// un-synced writes + the DLQ), with its head + law hashes + capture time. The bytes are the SAME
   /// base64 `connect(restoreFrom:)` consumes — [restoreWorkspace] round-trips it. O(1)-ish (a tree serialize).
   Future<WorkspaceSnapshot> snapshotWorkspace(String workspace) async {
-    final s = session(
-        workspace); // throws NomosTestHarnessException if not a connected session
+    final connected = _plane.connectedSessions;
+    if (!connected.contains(workspace)) {
+      throw NomosTestHarnessException(
+          'snapshotWorkspace("$workspace"): no connected session; connected workspaces: $connected');
+    }
+    final s = _plane.session(workspace);
     return _phased(
       phase: 'snapshotWorkspace',
       workspace: workspace,
@@ -1276,7 +1350,9 @@ class NomosTestHarness {
   /// carried per entry). The plane-level twin of [snapshotWorkspace] — migrate a whole staged AppSim plane.
   Future<PlaneSnapshot> snapshotPlane() async {
     final out = <String, WorkspaceSnapshot>{};
-    for (final ws in _sessionNames) {
+    final connected = _plane.connectedSessions.where(
+        (ws) => ws != _decoyWorkspace && !ws.endsWith('-onboard-scratch'));
+    for (final ws in connected) {
       out[ws] = await snapshotWorkspace(ws);
     }
     return PlaneSnapshot(
@@ -1315,6 +1391,105 @@ class NomosTestHarness {
     }
   }
 
+  /// Simulate an app process restart from its durably persisted local custody. This is deliberately one
+  /// harness verb: snapshots, runner replacement, credentials, workspace ordering and auto-sync registration
+  /// remain Nomos concerns. The caller reacquires generated clients from [homeSession]/[bridge] afterward.
+  Future<void> restart() async {
+    if (_disposed) {
+      throw NomosTestHarnessException(
+          'restart(): this test device has already been disposed');
+    }
+    final lane = _cloudRestartLane;
+    final home = homeWorkspace;
+    if (lane == null || home == null) {
+      throw NomosTestHarnessException(
+          'restart() is available on a cloudBound harness');
+    }
+
+    final oldPlane = _plane;
+    final targets = oldPlane.connectedSessions
+        .where(
+            (ws) => ws != _decoyWorkspace && !ws.endsWith('-onboard-scratch'))
+        .toList();
+    if (targets.remove(home)) targets.insert(0, home);
+    final snapshots = <String, String>{};
+    for (final ws in targets) {
+      final session = oldPlane.session(ws);
+      await _phased(
+        phase: 'restart: stop automatic sync',
+        workspace: ws,
+        awaiting: 'stopAutoSync',
+        timeout: _phaseTimeout ?? _kOtherDeadline,
+        onDiagnostic: _onDiagnostic,
+        run: session.stopAutoSync,
+      );
+      snapshots[ws] = await _phased(
+        phase: 'restart: persist local custody',
+        workspace: ws,
+        awaiting: 'export',
+        timeout: _phaseTimeout ?? _kOtherDeadline,
+        onDiagnostic: _onDiagnostic,
+        run: session.export,
+      );
+    }
+
+    await _phased(
+      phase: 'restart: terminate old runner',
+      awaiting: 'NodeRunnerTransport.dispose',
+      timeout: _phaseTimeout ?? _kOtherDeadline,
+      onDiagnostic: _onDiagnostic,
+      run: _transport.dispose,
+    );
+    _transport = await _phased(
+      phase: 'restart: spawn runner',
+      awaiting: 'Process.start(${lane.node})',
+      timeout: _phaseTimeout ?? _kSpawnDeadline,
+      onDiagnostic: _onDiagnostic,
+      run: () => NodeRunnerTransport.start(
+        entry: lane.entry,
+        resolveFrom: lane.resolveFrom,
+        node: lane.node,
+        environment: lane.environment,
+        onDiagnostic: _onDiagnostic,
+      ),
+    );
+    final restarted = NomosBridge(_transport);
+    await _phased(
+      phase: 'restart: runner ready',
+      awaiting: "event:'ready'",
+      timeout: _phaseTimeout ?? _kOtherDeadline,
+      onDiagnostic: _onDiagnostic,
+      run: () => restarted.ready,
+    );
+    for (final ws in targets) {
+      await _phased(
+        phase: 'restart: reopen local custody',
+        workspace: ws,
+        awaiting: 'connect(restoreFrom:)',
+        timeout: _phaseTimeout ?? const Duration(seconds: 60),
+        onDiagnostic: _onDiagnostic,
+        run: () => restarted.connect(
+          cloud: lane.cloud,
+          workspace: ws,
+          session: ws,
+          clientId: '${lane.clientId}-$ws',
+          authToken: lane.authToken,
+          authorSecret: lane.authorSecret,
+          restoreFrom: snapshots[ws],
+          allowUnborn: true,
+        ),
+      );
+    }
+    bridge = restarted.session(home);
+    _sessionNames
+      ..clear()
+      ..addAll(targets);
+    _snapshots.addAll(snapshots);
+    for (final ws in targets) {
+      await restarted.session(ws).autoSync(fallbackMs: 60000);
+    }
+  }
+
   /// 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.

package/dart/lib/src/webview_bridge.dart

@@ -399,7 +399,7 @@ class NomosDevices {
   }
 }
 
-/// The one business-level recovery policy surface. Escrow wraps, Orders, Receipts and retries stay inside Nomos.
+/// The one business-level recovery policy surface. The handoff protocol stays inside Nomos.
 class NomosRecovery {
   final NomosBridge bridge;
   final String domain;
@@ -1127,11 +1127,28 @@ class NomosBridge {
       // autoSync telemetry: each round { event:'sync', reason, result } and socket state { event:'link', status }.
       if (!_syncEvents.isClosed) _syncEvents.add(m);
       if (event == 'sync') {
-        // a completed round → idle (the next metrics poll folds in residual ahead/behind), stamp the time.
-        _pushStatus(_status.copyWith(
-            phase: SyncPhase.idle,
-            clearTransfer: true,
-            lastSyncedAt: DateTime.now()));
+        final result = (m['result'] as Map?)?.cast<String, Object?>();
+        if (m['ok'] == false) {
+          // A rejected/failed round is not a successful sync timestamp. Keep the stable typed envelope on
+          // telemetry; the app-ready status needs only one legible error and an honest error phase.
+          final detail = m['error']?.toString() ?? 'automatic sync failed';
+          _pushStatus(_status.copyWith(
+              phase: SyncPhase.error, clearTransfer: true, lastError: detail));
+        } else if (result?['offline'] == true) {
+          // Offline is expected transport debt. The durable local branch remains ahead and autoSync owns the
+          // retry; do not claim a completed sync or overwrite the previous successful timestamp.
+          _pushStatus(_status.copyWith(
+              phase: SyncPhase.offline,
+              clearTransfer: true,
+              lastError: (result?['pushError'] as Map?)?['error']?.toString()));
+        } else {
+          // A completed round → idle (the next metrics poll folds in residual ahead/behind), stamp the time.
+          _pushStatus(_status.copyWith(
+              phase: SyncPhase.idle,
+              clearTransfer: true,
+              clearError: true,
+              lastSyncedAt: DateTime.now()));
+        }
       } else if (m['status'] == 'closed' || m['status'] == 'offline') {
         _pushStatus(_status.copyWith(phase: SyncPhase.offline));
       }

package/dart/pubspec.lock

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

package/dart/pubspec.yaml

@@ -1,9 +1,6 @@
 # NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
-# remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
-# wasm32-wasip1 artifact {kernel · projection · embedded
-# QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
-# wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
-# If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+# remotes are replaceable custody/transport, not truth. Supported kernel releases remain deterministic and
+# capability-checked while old and new clients coexist during gradual rollout.
 
 name: nomos_client
 repository: https://github.com/Captain-App/nomos2
@@ -11,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.0
+version: 0.63.1
 
 environment:
   sdk: ^3.5.0
@@ -20,7 +17,7 @@ dependencies:
   # The pure-data core (wire types, offer codec, NomosReads, schema validation, error
   # info). nomos_client depends on and re-exports it, so existing imports are unchanged.
   # For local monorepo dev, pubspec_overrides.yaml points this at ../dart_types.
-  nomos_types: ^0.7.0
+  nomos_types: ^0.7.1
   json_schema: ^5.2.2
   crypto: ^3.0.0
 

package/dart/test/co2_product_gauntlet_test.dart

@@ -105,7 +105,7 @@ void main() {
         onDiagnostic: diagnostic,
         phaseTimeout: const Duration(seconds: 180),
       );
-      final home = harness.homeSession;
+      var home = harness.homeSession;
       expect((await cloud.remoteHead(home.workspace)).initialized, isTrue,
           reason:
               'the application born the identity home before business code ran');
@@ -126,7 +126,7 @@ void main() {
         country: 'GB',
         baselineTonnesCo2e: 4200,
       ));
-      final estate = await harness.bridge.follow(
+      var estate = await harness.bridge.follow(
         estateRef,
         authorSecret: harness.deviceSecret(home.workspace),
       );
@@ -149,6 +149,22 @@ void main() {
           reason:
               'the Estate remained fully usable without remote custody during the partition');
 
+      // Kill the device process while both parent and child still carry unsynchronised local custody.
+      // Restart is one framework verb: the product test supplies no snapshots, credentials, routes, retry
+      // loop or topology ordering. Generated business reads must work before connectivity returns.
+      await harness.restart();
+      home = harness.homeSession;
+      estate = harness.session(estateRef.workspace);
+      final restartedClient = await Co2Client.bind(estate, actor: _subject);
+      final restartedAssets =
+          await restartedClient.assetsBySite(siteId: siteId);
+      expect(restartedAssets.single.name, 'Main electricity meter');
+      expect(restartedAssets.single.operationalStatus?.valueOrNull,
+          'commissioned');
+      expect((await estate.verifyChain())['valid'], isTrue,
+          reason:
+              'the unsynchronised Estate must replay locally before any network recovery');
+
       cloud.setOnline(true);
       // No tenant sync(), no harness.converge(), no topology ordering. The two stateful client sessions must
       // retain their local branches, retry after reconnect, establish the parent birth first as required by

package/dart/test/errors_test.dart

@@ -24,7 +24,6 @@ void main() {
       workspace: 'home-ada',
       attrs: {
         'nomos.owned.stage': 'awaitingRecoveryPrincipal',
-        'nomos.owned.orderId': 'NomosOwnedRecoveryOrder_1',
         'nomos.owned.recoveryPrincipal': 'user:bob',
         'nomos.owned.recommendedAction':
             NomosRecommendedAction.openRecoveryPrincipalDevice,
@@ -34,7 +33,6 @@ void main() {
     final recovery = e as OwnedRecoveryPending;
     expect(recovery.workspace, 'home-ada');
     expect(recovery.stage, 'awaitingRecoveryPrincipal');
-    expect(recovery.orderId, 'NomosOwnedRecoveryOrder_1');
     expect(recovery.recoveryPrincipal, 'user:bob');
     expect(recovery.recommendedAction,
         NomosRecommendedAction.openRecoveryPrincipalDevice);

package/dart/test/webview_bridge_test.dart

@@ -19,8 +19,11 @@ class FakeRunner implements BridgeTransport {
 
   FakeRunner() {
     // the runner announces readiness at construction.
-    scheduleMicrotask(
-        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready', 'bundleVersion': 'unbundled-dev'}));
+    scheduleMicrotask(() => _incoming.add({
+          'v': kWebviewBridgeVersion,
+          'event': 'ready',
+          'bundleVersion': 'unbundled-dev'
+        }));
   }
 
   @override
@@ -255,6 +258,10 @@ class FakeRunner implements BridgeTransport {
   /// Simulate the runner forwarding a signal holon projection.
   void pushSignal(Map<String, Object?> signal) => _incoming
       .add({'v': kWebviewBridgeVersion, 'event': 'signal', 'signal': signal});
+
+  /// Simulate one background-sync event from the runner.
+  void pushSync(Map<String, Object?> event) =>
+      _incoming.add({'v': kWebviewBridgeVersion, 'event': 'sync', ...event});
 }
 
 /// A transport that answers EVERY request with one canned `result` (the golden corpus's reply) and records
@@ -264,8 +271,11 @@ class ReplayTransport implements BridgeTransport {
   final _incoming = StreamController<Map<String, Object?>>.broadcast();
   Map<String, Object?>? lastRequest;
   ReplayTransport(this.result) {
-    scheduleMicrotask(
-        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready', 'bundleVersion': 'unbundled-dev'}));
+    scheduleMicrotask(() => _incoming.add({
+          'v': kWebviewBridgeVersion,
+          'event': 'ready',
+          'bundleVersion': 'unbundled-dev'
+        }));
   }
   @override
   Stream<Map<String, Object?>> get messages => _incoming.stream;
@@ -404,7 +414,9 @@ void main() {
       final bridge = NomosBridge(transport);
       await bridge.ready;
       await bridge.offerOutcome(
-          domain: 'guestbook', directiveId: 'signGuestbook', payload: {'author': 'ada'});
+          domain: 'guestbook',
+          directiveId: 'signGuestbook',
+          payload: {'author': 'ada'});
       final kinds = bridge.recentSpans
           .map((m) => ((m['span'] as Map?)?['kind'] ?? '').toString())
           .toSet();
@@ -415,13 +427,17 @@ void main() {
       await bridge.dispose();
     });
 
-    test('a runner without timing (older bundle) emits no bridge-leg spans and still answers', () async {
-      final transport =
-          ReplayTransport({'head': 'H1', 'created': <Object?>[], 'workspace': 'ws'});
+    test(
+        'a runner without timing (older bundle) emits no bridge-leg spans and still answers',
+        () async {
+      final transport = ReplayTransport(
+          {'head': 'H1', 'created': <Object?>[], 'workspace': 'ws'});
       final bridge = NomosBridge(transport);
       await bridge.ready;
       final out = await bridge.offerOutcome(
-          domain: 'guestbook', directiveId: 'signGuestbook', payload: {'author': 'ada'});
+          domain: 'guestbook',
+          directiveId: 'signGuestbook',
+          payload: {'author': 'ada'});
       expect(out.head, 'H1');
       final kinds = bridge.recentSpans
           .map((m) => ((m['span'] as Map?)?['kind'] ?? '').toString())
@@ -435,8 +451,8 @@ void main() {
   // author path signs THIS offer with the intended enrolled key, not the connect-time one). Both offer lanes. ──
   group('per-offer authorSecret threads to the runner op (#9)', () {
     test('offerOutcome carries authorSecret to the runner op args', () async {
-      final transport =
-          ReplayTransport({'head': 'H1', 'created': <Object?>[], 'workspace': 'ws'});
+      final transport = ReplayTransport(
+          {'head': 'H1', 'created': <Object?>[], 'workspace': 'ws'});
       final bridge = NomosBridge(transport);
       await bridge.ready;
       await bridge.offerOutcome(
@@ -444,10 +460,12 @@ void main() {
           directiveId: 'writeNote',
           payload: {'author': 'ada'},
           authorSecret: 'ENROLLED-KEY-B64');
-      final args = (transport.lastRequest!['args'] as Map).cast<String, Object?>();
+      final args =
+          (transport.lastRequest!['args'] as Map).cast<String, Object?>();
       expect(transport.lastRequest!['op'], 'offerDirective');
       expect(args['authorSecret'], 'ENROLLED-KEY-B64',
-          reason: 'the per-offer signing key must reach the runner op (→ opts.signWith)');
+          reason:
+              'the per-offer signing key must reach the runner op (→ opts.signWith)');
       await bridge.dispose();
     });
 
@@ -460,18 +478,23 @@ void main() {
           directiveId: 'writeNote',
           payload: {'author': 'ada'},
           authorSecret: 'ENROLLED-KEY-B64');
-      final args = (transport.lastRequest!['args'] as Map).cast<String, Object?>();
+      final args =
+          (transport.lastRequest!['args'] as Map).cast<String, Object?>();
       expect(args['authorSecret'], 'ENROLLED-KEY-B64');
       await bridge.dispose();
     });
 
-    test('no authorSecret ⇒ the op omits it (byte-identical to the pre-#9 contract)', () async {
-      final transport = ReplayTransport({'head': 'H1', 'created': <Object?>[], 'workspace': 'ws'});
+    test(
+        'no authorSecret ⇒ the op omits it (byte-identical to the pre-#9 contract)',
+        () async {
+      final transport = ReplayTransport(
+          {'head': 'H1', 'created': <Object?>[], 'workspace': 'ws'});
       final bridge = NomosBridge(transport);
       await bridge.ready;
       await bridge.offerOutcome(
           domain: 'home', directiveId: 'writeNote', payload: {'author': 'ada'});
-      final args = (transport.lastRequest!['args'] as Map).cast<String, Object?>();
+      final args =
+          (transport.lastRequest!['args'] as Map).cast<String, Object?>();
       expect(args.containsKey('authorSecret'), isFalse);
       await bridge.dispose();
     });
@@ -534,7 +557,9 @@ void main() {
     expect((req['args'] as Map)['allowUnborn'], isTrue);
   });
 
-  test('a session retains the authenticated token subject as its default principal', () async {
+  test(
+      'a session retains the authenticated token subject as its default principal',
+      () async {
     await bridge.ready;
     final payload = base64Url
         .encode(utf8.encode(jsonEncode({'sub': 'ada'})))
@@ -553,8 +578,7 @@ void main() {
       'generated model restoration crosses one framework-private bridge operation',
       () async {
     await bridge.ready;
-    final verdict =
-        await bridge.nomosFrameworkRestorePreviousGeneratedModel(
+    final verdict = await bridge.nomosFrameworkRestorePreviousGeneratedModel(
       domain: 'evo',
       currentHash: 'current-law-hash',
       because: 'the previous operating policy is required',
@@ -562,8 +586,7 @@ void main() {
 
     expect(verdict['ok'], isFalse);
     expect(verdict['stage'], 'acceptance');
-    expect(
-        ((verdict['report'] as Map)['divergences'] as List).single,
+    expect(((verdict['report'] as Map)['divergences'] as List).single,
         containsPair('directiveId', 'setMood'));
     final request = runner.sent.firstWhere(
       (message) => message['op'] == 'restorePreviousGeneratedModel',
@@ -589,7 +612,8 @@ void main() {
         await bridge.lawStatus('abc'), {'installed': true, 'drifted': false});
   });
 
-  test('moments and historic reads keep commit plumbing behind an opaque handle',
+  test(
+      'moments and historic reads keep commit plumbing behind an opaque handle',
       () async {
     final momentsTransport = ReplayTransport({
       'commits': [
@@ -663,8 +687,8 @@ void main() {
     );
     final offerArgs = (offerCall['args'] as Map).cast<String, Object?>();
     expect(offerArgs['domain'], 'notes');
-    expect(offerArgs['directiveId'],
-        'nomos_internal_approve_owned_device_7c1f5e');
+    expect(
+        offerArgs['directiveId'], 'nomos_internal_approve_owned_device_7c1f5e');
     expect(offerArgs['actor'], 'user:alice');
     expect(offerArgs['domainHash'], 'a' * 64);
     expect(offerArgs['payload'], {
@@ -676,7 +700,8 @@ void main() {
     });
   });
 
-  test('record sharing keeps keys, identity and action payloads behind the bridge',
+  test(
+      'record sharing keeps keys, identity and action payloads behind the bridge',
       () async {
     await bridge.ready;
     final keys = await bridge.nomosOwnedScopeKeys(
@@ -742,8 +767,7 @@ void main() {
 
     expect(verdict['ok'], isFalse);
     expect(verdict['stage'], 'acceptance');
-    expect(
-        ((verdict['report'] as Map)['divergences'] as List).single,
+    expect(((verdict['report'] as Map)['divergences'] as List).single,
         containsPair('directiveId', 'registerSite'));
     final request = runner.sent.firstWhere(
       (message) => message['op'] == 'adoptGeneratedModel',
@@ -808,6 +832,43 @@ void main() {
     expect((req['args'] as Map)['signalId'], 'signal:ws:list:main');
   });
 
+  test(
+      'background sync status never calls an offline or failed round successful',
+      () async {
+    await bridge.ready;
+
+    runner.pushSync({
+      'reason': 'reconnect',
+      'result': {
+        'offline': true,
+        'pushError': {'error': 'network unavailable'}
+      }
+    });
+    await Future<void>.delayed(Duration.zero);
+    expect(bridge.currentStatus.phase, SyncPhase.offline);
+    expect(bridge.currentStatus.lastSyncedAt, isNull);
+    expect(bridge.currentStatus.lastError, 'network unavailable');
+
+    runner.pushSync({
+      'reason': 'reconnect',
+      'ok': false,
+      'error': 'kernel capability skew',
+    });
+    await Future<void>.delayed(Duration.zero);
+    expect(bridge.currentStatus.phase, SyncPhase.error);
+    expect(bridge.currentStatus.lastSyncedAt, isNull);
+    expect(bridge.currentStatus.lastError, 'kernel capability skew');
+
+    runner.pushSync({
+      'reason': 'reconnect',
+      'result': {'stillAhead': false}
+    });
+    await Future<void>.delayed(Duration.zero);
+    expect(bridge.currentStatus.phase, SyncPhase.idle);
+    expect(bridge.currentStatus.lastSyncedAt, isNotNull);
+    expect(bridge.currentStatus.lastError, isNull);
+  });
+
   test('a law refusal throws NomosBridgeError with the verbatim message',
       () async {
     await bridge.ready;
@@ -871,7 +932,8 @@ void main() {
     expect(e.recoverable, isTrue);
     expect(e.recommendedAction, 'quarantineLocalSnapshotAndReclone');
     expect(e.shouldEvictLocalCustody, isTrue);
-    expect(e.info.trace.traceId, isNotEmpty); // trace IDs ride as on every bridge error
+    expect(e.info.trace.traceId,
+        isNotEmpty); // trace IDs ride as on every bridge error
     expect(e.message, contains('shallow-insufficient'));
   });
 

package/dart_types/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.7.1
+
+- Add typed framework recovery actions and lifecycle failure shapes without leaking signer, certificate,
+  escrow or retry protocol into generated business clients.
+
 ## 0.7.0
 
 - Add the public conflict and description shapes used by generated aggregate clients: merge observations,

package/dart_types/lib/src/errors.dart

@@ -128,12 +128,11 @@ class NomosRecommendedAction {
 }
 
 /// All-device-loss recovery is a normal, resumable lifecycle state. The app may render the one concrete
-/// [recommendedAction]; it never needs to inspect escrow wraps, Orders, Receipts, or key material.
+/// [recommendedAction]; the private recovery protocol stays inside Nomos.
 class OwnedRecoveryPending extends NomosBridgeError {
   final String code;
   final String? workspace;
   final String stage;
-  final String? orderId;
   final String? recoveryPrincipal;
   final String recommendedAction;
 
@@ -142,7 +141,6 @@ class OwnedRecoveryPending extends NomosBridgeError {
     required String message,
     this.workspace,
     this.stage = 'request',
-    this.orderId,
     this.recoveryPrincipal,
     this.recommendedAction = NomosRecommendedAction.waitForRecoveryPrincipal,
     NomosErrorInfo? info,
@@ -160,7 +158,6 @@ class OwnedRecoveryPending extends NomosBridgeError {
       message: info.message,
       workspace: info.workspace,
       stage: attr('stage') ?? 'request',
-      orderId: attr('orderId') ?? attr('order_id'),
       recoveryPrincipal:
           attr('recoveryPrincipal') ?? attr('recovery_principal'),
       recommendedAction: attr('recommendedAction') ??
@@ -171,8 +168,7 @@ class OwnedRecoveryPending extends NomosBridgeError {
   }
 
   @override
-  String toString() =>
-      'OwnedRecoveryPending(stage: $stage${orderId != null ? ', order: $orderId' : ''}'
+  String toString() => 'OwnedRecoveryPending(stage: $stage'
       '${recoveryPrincipal != null ? ', recoveryPrincipal: $recoveryPrincipal' : ''}, '
       'recommendedAction: $recommendedAction): $message';
 }
@@ -700,6 +696,8 @@ class CustodyError extends NomosBridgeError {
 /// cloud answered 401 / "invalid token" on a lane that requires a verified principal (every birth does).
 /// REMEDY: re-acquire a fresh token from the auth provider and reconnect.
 class AuthTokenInvalid extends NomosBridgeError {
+  final String code = 'nomos.auth.token_invalid';
+  final String recommendedAction = NomosRecommendedAction.reauth;
   AuthTokenInvalid([String? message])
       : super(message ??
             'the auth-provider token was missing or rejected (the cloud refused 401) — a birth needs a verified principal');
@@ -709,6 +707,9 @@ class AuthTokenInvalid extends NomosBridgeError {
 /// own law commits to `home-<sha256(subject)>` (the squat invariant), so a mismatch means the cloud routed to
 /// the wrong slot — a fail-closed safety stop, never silently mount the wrong holon.
 class HomeNameMismatch extends NomosBridgeError {
+  final String code = 'nomos.home.name_mismatch';
+  final String recommendedAction = NomosRecommendedAction.reopen;
+
   /// What `homeNameOf(subject)` derived locally.
   final String expected;
 
@@ -725,6 +726,9 @@ class HomeNameMismatch extends NomosBridgeError {
 /// run the home law FAILS here rather than silently mounting a lawless workspace. REMEDY: the tenant's
 /// governance must install the home law (the birth offer should author it; if it didn't, the deploy is wrong).
 class HomeLawMissing extends NomosBridgeError {
+  final String code = 'nomos.home.law_missing';
+  final String recommendedAction = NomosRecommendedAction.redeployLaw;
+
   /// The workspace that is missing the home law.
   final String workspace;
   HomeLawMissing({required this.workspace, String? message})
@@ -736,6 +740,9 @@ class HomeLawMissing extends NomosBridgeError {
 /// principal lacks creation authority, the pool is exhausted, or the genesis recipe was rejected). Carries
 /// the cloud's verdict verbatim. REMEDY is tenant-specific (grant creation authority / raise the pool).
 class BirthRejected extends NomosBridgeError {
+  final String code = 'nomos.home.birth_refused';
+  final String recommendedAction = NomosRecommendedAction.redeployLaw;
+
   /// The birth-lane directive id that was offered (e.g. the tenant's `birthHome` / `seedHomeOwner`).
   final String? directiveId;
 
@@ -750,6 +757,9 @@ class BirthRejected extends NomosBridgeError {
 /// a git pack. This is a transport/custody integrity fault, not a law refusal. REMEDY: retry; if persistent,
 /// the custody bytes are corrupt.
 class PackMalformed extends NomosBridgeError {
+  final String code = 'nomos.custody.pack_malformed';
+  final String recommendedAction =
+      NomosRecommendedAction.refetchFullHistoryAndRetry;
   PackMalformed([String? message])
       : super(message ??
             'a returned pack was malformed and could not be applied (custody integrity fault)');
@@ -759,6 +769,9 @@ class PackMalformed extends NomosBridgeError {
 /// domain key, so the app cannot confirm WHICH law the home runs (and thus cannot baked-hash-pin or judge
 /// installed-ness). REMEDY: the home law must be deployed; if it was, retry once the deploy has folded.
 class LawHashUnavailable extends NomosBridgeError {
+  final String code = 'nomos.home.law_hash_unavailable';
+  final String recommendedAction = NomosRecommendedAction.redeployLaw;
+
   /// The workspace whose current law hash could not be resolved.
   final String workspace;
   LawHashUnavailable({required this.workspace, String? message})

package/dart_types/pubspec.yaml

@@ -1,7 +1,5 @@
 # NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
-# remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
-# wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine} —
-# byte-identical everywhere.  This package is the PURE-DATA core: wire/data types
+# remotes are replaceable custody/transport, not truth. This package is the PURE-DATA core: wire/data types
 # with no transport, no bridge, no runtime, so generated per-domain TYPES files
 # resolve against it alone.
 
@@ -11,7 +9,7 @@ description: >-
   Pure kernel wire/data types for Nomos Dart frontends — no transport, no bridge,
   no runtime. The hand-written serde-JSON-compatible types plus the offer codec,
   reactive read engine, schema validation, and data-only error/trace types.
-version: 0.7.0
+version: 0.7.1
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.101.1",
+  "version": "0.101.3",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/codegen_ts.ts

@@ -1431,7 +1431,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           `  __nomosOwnedScopeKeys?(args: { scope: string; record: { type: string; id: string } }): Promise<NomosScopeKey[]>;`,
           `  /** FRAMEWORK-INTERNAL: make this principal ready to receive generated record shares. */`,
           `  __nomosEnsureOwnedIdentity?(args: { scope: string; domain: string; domainHash?: string }): Promise<void>;`,
-          `  /** FRAMEWORK-INTERNAL: atomically record the opt-in recovery policy and escrow wrap. */`,
+          `  /** FRAMEWORK-INTERNAL: atomically enable the opt-in recovery policy. */`,
           `  __nomosProtectOwnedIdentity?(args: { scope: string; domain: string; domainHash?: string; recoveryPrincipal: string }): Promise<{ status: "protected"; recoveryPrincipal: string; unchanged?: boolean }>;`,
           `  /** FRAMEWORK-INTERNAL: prepare the atomic law payload behind share/unshare/transfer. */`,
           `  __nomosPrepareOwnedRecordAction?(args: { action: "share" | "unshare" | "transfer"; scope: string; record: NomosRef; peer: string }): Promise<Record<string, unknown>>;`,
@@ -2996,7 +2996,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         : []),
       ...(ownedScope !== undefined
         ? [
-            `    /** Opt into all-device-loss recovery with one explicitly designated person. Nomos owns the escrow and audit protocol. */`,
+            `    /** Opt into all-device-loss recovery with one explicitly designated person. Nomos owns the handoff. */`,
             `    recovery: {`,
             `      protectWith: async (person: string): Promise<{ status: "protected"; recoveryPrincipal: string; unchanged?: boolean }> => {`,
             `        if (!person.trim()) throw new Error("recovery.protectWith() needs the person who will recover you");`,
@@ -3004,7 +3004,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
             `        return holon.__nomosProtectOwnedIdentity({ scope: ${JSON.stringify(ownedScope)}, domain: ${JSON.stringify(domain)}, domainHash, recoveryPrincipal: person });`,
             `      },`,
             `    },`,
-            `    /** Add another of this person's devices without exposing keys, certificates or signer law. */`,
+            `    /** Add another of this person's devices through one opaque request and approval. */`,
             `    devices: {`,
             `      request: async (): Promise<NomosDeviceRequest> => {`,
             `        if (!holon.__nomosOwnedDeviceRequest) throw new Error("devices.request() needs the current @githolon/client");`,

package/src/compile_package_main.ts

@@ -1062,7 +1062,7 @@ const NOMOS_TYPES_DEP = "^0.7.0";
 // 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
-const NOMOS_CLIENT_DEP = "^0.63.0";
+const NOMOS_CLIENT_DEP = "^0.63.1";
 // DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in dsl/dart/pubspec.yaml
 // and dsl/dart_types/pubspec.yaml — a Dart release without this bump fails the suite, so tenants never
 // land back in dependency_overrides (the exact co2 report this closes, third occurrence).

package/src/directive.ts

@@ -64,6 +64,12 @@ export interface PreconditionDescriptor {
   readonly predicate: (row: Record<string, unknown> | undefined) => boolean;
   /** The typed refusal code emitted when the predicate is false. */
   readonly rejectCode: string;
+  /**
+   * Why this precondition may intentionally make a fact about private state observable through its
+   * public refusal. Set by chaining `.declassify(reason)` directly after the precondition marker;
+   * carried onto the synthesized workspace invariant and into the replay-verified flow-gate law.
+   */
+  readonly declassify?: string;
 }
 
 /**
@@ -662,6 +668,43 @@ class DirectivePlanStep<Id extends string, P> {
     });
   }
 
+  /**
+   * Acknowledge that the MOST RECENT write-path precondition may intentionally reveal one fact about
+   * private state through its typed refusal. This is business policy, so it stays beside the condition
+   * it explains; the compiler carries it onto the generated invariant without exposing that internal
+   * invariant to tenant code.
+   */
+  declassify(reason: string): DirectivePlanStep<Id, P> {
+    const trimmed = reason.trim();
+    if (trimmed.length === 0) {
+      throw new Error(
+        `directive('${this.id}').declassify(reason) needs a non-empty human reason — it is the audit record for an intended private-state refusal.`,
+      );
+    }
+    if (this.preconditions.length === 0) {
+      throw new Error(
+        `directive('${this.id}').declassify(reason) must follow .requiresExisting(...), .where(...), or .withId(...).`,
+      );
+    }
+    const last = this.preconditions[this.preconditions.length - 1]!;
+    if (last.declassify !== undefined) {
+      throw new Error(
+        `directive('${this.id}') already declassifies its most recent precondition — declare each policy once, beside its condition.`,
+      );
+    }
+    return new DirectivePlanStep(
+      this.id,
+      this.marker,
+      this.aggregate,
+      this.payloadSchema,
+      this.createOnceIdField,
+      [
+        ...this.preconditions.slice(0, -1),
+        { ...last, declassify: trimmed },
+      ],
+    );
+  }
+
   plan(fn: (payload: P, ctx: Ports) => PlannedOp[]): RequirableDirective<P> {
     return makeRequirable({
       id: this.id,

package/src/flow_gate.ts

@@ -50,6 +50,7 @@ type FlowModule = {
     readonly id: string;
     readonly on: string;
     readonly declassify?: string;
+    readonly __nomosGenerated?: "directive-precondition";
     readonly reads: (ctx: { intent: Record<string, unknown>; principal?: string }) => readonly { readonly aggregate: string }[];
   }[];
   readonly impureCapabilities?: readonly {
@@ -190,6 +191,14 @@ export function assertFlowGate(m: CanonicalManifest, mod?: FlowModule): void {
       for (const r of refs) {
         const short = r.aggregate.includes(".") ? r.aggregate.slice(r.aggregate.lastIndexOf(".") + 1) : r.aggregate;
         if (privateTypes.has(short)) {
+          if (wi.__nomosGenerated === "directive-precondition") {
+            throw new FlowGateError(
+              `[nomosFlowGate rule 4 — no secret-correlated refusal] directive '${wi.on}' checks the PRIVATE aggregate ` +
+                `'${r.aggregate}' before committing. Its refusal can reveal a fact about that record. If that is intended, ` +
+                `keep the policy beside the condition: chain .declassify("<why this refusal may reveal private state>") ` +
+                `immediately after .requiresExisting(...), .where(...), or .withId(...).`,
+            );
+          }
           throw new FlowGateError(
             `[nomosFlowGate rule 4 — no secret-correlated refusal] workspaceInvariant '${wi.id}' (on '${wi.on}') reads the ` +
               `PRIVATE aggregate '${r.aggregate}' — its refusal is a public ref transition that can correlate with that secret. ` +

package/src/framework/workspace_invariant.ts

@@ -150,6 +150,8 @@ export interface WorkspaceInvariantDecl {
    * a secret-correlated refusal.
    */
   readonly declassify?: string;
+  /** Framework-only provenance used to keep compiler errors on the tenant-authored surface. */
+  readonly __nomosGenerated?: "directive-precondition";
   /** Brand so a plain object is never mistaken for a declaration. */
   readonly __isWorkspaceInvariant: true;
 }

package/src/law_check.ts

@@ -907,6 +907,12 @@ function invariantFindings(mod: DomainModule, aggById: ReadonlyMap<string, Aggre
     let intent: Record<string, unknown> = {};
     if (dir !== undefined) {
       const probe = probeDirective(dir, `${domain}/${wi.id}#intent`);
+      // A generated precondition's id selector is fully typed and only runs after payload validation.
+      // If Nomos cannot synthesize this directive's otherwise-valid exotic payload (for example a
+      // branded value object), invoking that selector with our invented `{}` would manufacture a
+      // framework false positive. Hand-authored invariants still get the empty-intent probe because
+      // their reads function may genuinely need to be total independently of a directive schema.
+      if (probe === undefined && wi.__nomosGenerated === "directive-precondition") continue;
       if (probe !== undefined) intent = probe.probePayload;
     }
     const ctx = { intent, principal: "principal:probe", principalVerified: true } as const;
@@ -935,12 +941,17 @@ function invariantFindings(mod: DomainModule, aggById: ReadonlyMap<string, Aggre
       }
     });
     if (threwAt !== undefined) {
+      const generatedPrecondition = wi.__nomosGenerated === "directive-precondition";
       out.push({
         domain,
         directiveId: wi.on,
         level: "warn",
-        what: `workspace invariant '${wi.id}' ${threwAt === "reads" ? "reads()" : "assert()"} THREW on the synthesized sample (${(err as Error)?.message ?? String(err)}) — a predicate bug, or a payload-dependent path the sample hit`,
-        fix: `run it on intent=${samplePayloadText(intent)} snapshots=${samplePayloadText(snapshots)} — if the throw is real, the gate refuses on '${wi.on}'; if the sample's shape never occurs, guard the predicate`,
+        what: generatedPrecondition
+          ? `directive '${wi.on}' precondition THREW on the synthesized payload (${(err as Error)?.message ?? String(err)}) — its id selector or predicate may not handle every valid payload`
+          : `workspace invariant '${wi.id}' ${threwAt === "reads" ? "reads()" : "assert()"} THREW on the synthesized sample (${(err as Error)?.message ?? String(err)}) — a predicate bug, or a payload-dependent path the sample hit`,
+        fix: generatedPrecondition
+          ? `run the directive's .requiresExisting(...), .where(...), or .withId(...) condition on ${samplePayloadText(intent)} — if that payload is valid, make the condition total for it`
+          : `run it on intent=${samplePayloadText(intent)} snapshots=${samplePayloadText(snapshots)} — if the throw is real, the gate refuses on '${wi.on}'; if the sample's shape never occurs, guard the predicate`,
       });
     }
   }

package/src/precondition.ts

@@ -86,6 +86,8 @@ export function synthesizePreconditionInvariants<P>(directive: Directive<P>): Wo
         const row = snapshots[REF_NAME] as Record<string, unknown> | undefined;
         return desc.predicate(row) ? { accept: true } : { reject: desc.rejectCode };
       },
+      ...(desc.declassify !== undefined ? { declassify: desc.declassify } : {}),
+      __nomosGenerated: "directive-precondition" as const,
       __isWorkspaceInvariant: true as const,
     };
   });