@githolon/dsl 0.105.5 → 0.105.7

package/dart/lib/src/webview_bridge.dart

@@ -1254,6 +1254,14 @@ class NomosBridge {
   final Map<String, SyncStatus> _statusBySession = {};
   final Map<String, StreamController<SyncStatus>> _syncStatusBySession = {};
   Timer? _metricsTimer;
+  // The zone this bridge was CONSTRUCTED in. The metrics poll belongs to the
+  // bridge (a long-lived, often file-shared object in tests), yet it used to be
+  // created in whichever zone the first status LISTENER attached from — in
+  // widget tests that is a per-test FakeAsync zone, so a file-shared bridge's
+  // periodic poll became a fake timer owned by ONE test and tripped
+  // flutter_test's '!timersPending' invariant at that test's teardown. Timers
+  // run in their owner's zone, not their caller's.
+  final Zone _creationZone = Zone.current;
   Future<void>? _metricsPoll;
   bool _metricsPollAgain = false;
   final Completer<void> _ready = Completer<void>();
@@ -1602,13 +1610,27 @@ class NomosBridge {
       sampled: true,
     );
     _pendingTraces[id] = trace;
-    _transport.send({
-      'v': kWebviewBridgeVersion,
-      'id': id,
-      'op': op,
-      'args': args,
-      'trace': trace.toJson(),
-    });
+    try {
+      _transport.send({
+        'v': kWebviewBridgeVersion,
+        'id': id,
+        'op': op,
+        'args': args,
+        'trace': trace.toJson(),
+      });
+    } catch (error, stackTrace) {
+      // A transport that refuses (disposed at teardown, closed pipe) must fail
+      // THE FUTURE, not throw synchronously: a sync throw bypasses every
+      // `.catchError`/`onError` guard callers attach for exactly this case
+      // (watch re-registration and unwatch during dispose), leaks the pending
+      // completer, and lands as an unhandled error in whatever zone happened to
+      // be current — the "thrown after the test had completed" noise that buried
+      // ~100 real test results. Same loud error, delivered where errors go.
+      _pending.remove(id);
+      _pendingOps.remove(id);
+      _pendingTraces.remove(id);
+      completer.completeError(error, stackTrace);
+    }
     return completer.future;
   }
 
@@ -1791,6 +1813,23 @@ class NomosBridge {
     }).toList();
   }
 
+  /// Framework-private plane persistence primitive. It snapshots exact local custody even when [workspace]
+  /// was born in the kernel but no Dart runner session has ever acquired it. This does not connect, mount a
+  /// tenant session, fetch from cloud, or grant authority; the serving realm exports its resident plane view.
+  Future<({String workspace, String head, String? snapshot, bool unchanged})>
+      nomosInternalSnapshotWorkspace(String workspace, {String? ifHead}) async {
+    final r = _asMap(await _call('snapshotWorkspace', {
+      'workspace': workspace,
+      if (ifHead != null && ifHead.isNotEmpty) 'ifHead': ifHead,
+    }));
+    return (
+      workspace: (r['workspace'] ?? workspace).toString(),
+      head: (r['head'] ?? '').toString(),
+      snapshot: r['snapshot']?.toString(),
+      unchanged: r['unchanged'] == true,
+    );
+  }
+
   /// Open a workspace on this plane: boot its LOCAL githolon under the installed law (from [restoreFrom]
   /// custody, or a cloud pull when [cloud] is given). This is the sugar the single-workspace path uses; a
   /// multi-workspace app names a [session] per workspace and holds their [session] handles.
@@ -2351,7 +2390,52 @@ class NomosBridge {
     }
     // SINGLE-FLIGHT: one in-flight open per workspace per plane; concurrent callers join it.
     return plane._acquiring.putIfAbsent(workspace, () async {
-      try {
+      // RESIDENCY IS THE KERNEL'S TO DEMAND AND OURS TO SATISFY. Replaying a chain can reach a
+      // colocated read whose source workspace is not mounted; the kernel refuses TYPED, naming it.
+      // Mount the named sibling — which consults local custody first and only then clones — and
+      // retry. Bounded, and each name is satisfied at most once, so a genuinely missing workspace
+      // fails with the kernel's own refusal instead of spinning.
+      final satisfied = <String>{};
+      for (var round = 0;; round++) {
+        try {
+          return await _acquireSessionOnce(
+            workspace,
+            ready: ready,
+            inheritPrincipal: inheritPrincipal,
+            ifAbsentCredentials: ifAbsentCredentials,
+            authorSecret: authorSecret,
+          );
+        } catch (error) {
+          final required = nomosInternalResidencyRequiredWorkspace(error);
+          if (required == null ||
+              required == workspace ||
+              !satisfied.add(required) ||
+              round >= 8) {
+            rethrow;
+          }
+          await acquireSession(
+            required,
+            ifAbsentCredentials: ifAbsentCredentials,
+            authorSecret: authorSecret,
+            inheritedPrincipal: sourcePrincipal,
+          );
+        }
+      }
+    }).whenComplete(() {
+      plane._acquiring.remove(workspace);
+    });
+  }
+
+  Future<NomosSession> _acquireSessionOnce(
+    String workspace, {
+    required Future<NomosSession> Function(NomosSession) ready,
+    required void Function() inheritPrincipal,
+    Future<NomosSessionCredentials> Function()? ifAbsentCredentials,
+    String? authorSecret,
+  }) async {
+    final plane = _eventPlane;
+    {
+      {
         if (plane._sessionNames.contains(workspace)) {
           return ready(session(workspace));
         }
@@ -2427,11 +2511,8 @@ class NomosBridge {
           allowUnborn: c.allowUnborn,
         );
         return ready(session(workspace));
-      } finally {
-        // completed (either way) — the next acquire re-evaluates fresh (a live session hits the fast path).
-        plane._acquiring.remove(workspace);
       }
-    });
+    }
   }
 
   /// @internal Attach the generated application's opaque local-custody store
@@ -3506,8 +3587,12 @@ class NomosBridge {
     // metrics snapshot.
     if (!_syncStatusCtrl.isClosed) _syncStatusCtrl.add(_status);
     _pollMetricsOnce();
-    _metricsTimer ??=
-        Timer.periodic(const Duration(seconds: 4), (_) => _pollMetricsOnce());
+    _metricsTimer ??= _creationZone.run(
+      () => Timer.periodic(
+        const Duration(seconds: 4),
+        (_) => _creationZone.run(_pollMetricsOnce),
+      ),
+    );
   }
 
   void _startSessionStatusPoll(String session) {
@@ -3516,8 +3601,12 @@ class NomosBridge {
       controller.add(_currentSessionStatus(session));
     }
     _pollMetricsOnce();
-    _metricsTimer ??=
-        Timer.periodic(const Duration(seconds: 4), (_) => _pollMetricsOnce());
+    _metricsTimer ??= _creationZone.run(
+      () => Timer.periodic(
+        const Duration(seconds: 4),
+        (_) => _creationZone.run(_pollMetricsOnce),
+      ),
+    );
   }
 
   void _stopStatusPollIfUnused() {
@@ -3654,24 +3743,34 @@ class NomosBridge {
     required int t0,
     required int t1,
     String? id,
+    String? session,
+    String? head,
   }) {
     final plane = _eventPlane;
     final sid = id ?? 'local-${plane._localSpanSeq++}';
     for (final m in <Map<String, Object?>>[
       {
         'event': 'span',
+        if (session != null && session.isNotEmpty) 'session': session,
         'span': {
           'phase': 'begin',
           'id': sid,
           'track': track,
           'name': name,
           'kind': kind,
-          't0': t0
+          't0': t0,
+          if (head != null && head.isNotEmpty) 'head': head,
         }
       },
       {
         'event': 'span',
-        'span': {'phase': 'end', 'id': sid, 't1': t1}
+        if (session != null && session.isNotEmpty) 'session': session,
+        'span': {
+          'phase': 'end',
+          'id': sid,
+          't1': t1,
+          if (head != null && head.isNotEmpty) 'head': head,
+        }
       },
     ]) {
       plane._spanBuffer.add(m);
@@ -4270,3 +4369,21 @@ class _BridgeForeignWorkspaceReader implements NomosForeignWorkspaceReader {
     return ctrl.stream;
   }
 }
+
+/// THE KERNEL NAMES WHAT IT NEEDS. When a chain replay reaches a colocated foreign read whose
+/// source workspace is not mounted, the kernel refuses with a typed, machine-readable message
+/// naming that workspace. The cloud has satisfied this since the requirement was introduced; the
+/// client never learned to, so an estate whose history reads a catalogue simply could not open on a
+/// device — the same kernel, the same rule, only one implementer.
+///
+/// Parses the workspace name out of the refusal, or null when this is some other failure. Matching
+/// on the message is deliberate and narrow: the refusal is kernel-authored and stable, and the
+/// alternative — treating every open failure as a residency miss — would retry real errors forever.
+String? nomosInternalResidencyRequiredWorkspace(Object error) {
+  final text = error.toString();
+  if (!text.contains('foreign-read-not-ready')) return null;
+  final match = RegExp(r"source workspace '([^']+)' is not resident")
+      .firstMatch(text);
+  final workspace = match?.group(1)?.trim();
+  return (workspace == null || workspace.isEmpty) ? null : workspace;
+}

package/dart/pubspec.lock

@@ -191,7 +191,7 @@ packages:
       path: "../dart_types"
       relative: true
     source: path
-    version: "0.8.5"
+    version: "0.8.7"
   package_config:
     dependency: "direct main"
     description:

package/dart/pubspec.yaml

@@ -7,7 +7,7 @@ repository: https://github.com/Captain-App/nomos2
 description: >-
   Nomos 2 Dart client — generated domain values, intent payloads and application
   lifecycle types over the typed Nomos kernel protocol and USDA custody model.
-version: 0.64.20
+version: 0.64.24
 
 environment:
   sdk: ^3.5.0
@@ -16,7 +16,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.8.6
+  nomos_types: ^0.8.7
   json_schema: ^5.2.2
   crypto: ^3.0.0
   package_config: ^2.1.0

package/dart/test/acquire_session_test.dart

@@ -70,6 +70,17 @@ class FakeRunner implements BridgeTransport {
             ]
           };
           break;
+        case 'snapshotWorkspace':
+          result = {
+            'workspace': args['workspace'],
+            'head': 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+            if (args['ifHead'] ==
+                'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')
+              'unchanged': true
+            else
+              'snapshot': 'resident-snapshot-b64',
+          };
+          break;
         default:
           result = {};
       }
@@ -392,6 +403,32 @@ void main() {
     await bridge.dispose();
   });
 
+  test(
+      'plane snapshot exports resident custody without manufacturing a Dart session',
+      () async {
+    final runner = FakeRunner(resident: ['born-child']);
+    final bridge = NomosBridge(runner);
+    await bridge.ready;
+
+    final saved =
+        await bridge.nomosInternalSnapshotWorkspace('born-child');
+    expect(saved.workspace, 'born-child');
+    expect(saved.head, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa');
+    expect(saved.snapshot, 'resident-snapshot-b64');
+    expect(saved.unchanged, isFalse);
+    expect(runner.connectCount, 0,
+        reason:
+            'save-all must not acquire an unopened child or invent host authority');
+
+    final unchanged = await bridge.nomosInternalSnapshotWorkspace(
+        'born-child',
+        ifHead: saved.head);
+    expect(unchanged.unchanged, isTrue);
+    expect(unchanged.snapshot, isNull);
+    expect(runner.connectCount, 0);
+    await bridge.dispose();
+  });
+
   test(
       'NomosSession.isConnected + assertConnected: fail at BIND, not on first query',
       () async {

package/dart/test/residency_refusal_test.dart

@@ -0,0 +1,49 @@
+// THE KERNEL NAMES WHAT IT NEEDS; EVERY HOST MUST SATISFY IT.
+//
+// The colocated-read residency rule is enforced by the KERNEL, so it fires identically in the cloud
+// container and on a phone — the whole point of one artifact everywhere. It shipped with only the
+// cloud taught to satisfy it, so an estate whose history reads a catalogue could not open on a
+// device at all. These tests pin the client's half: the exact refusal the kernel emits must be
+// recognised, and nothing else must be mistaken for it.
+import 'package:test/test.dart';
+import 'package:nomos_client/src/webview_bridge.dart'
+    show nomosInternalResidencyRequiredWorkspace;
+
+void main() {
+  test('recognises the kernel refusal and names the workspace to mount', () {
+    // Verbatim from a device, 2026-08-07 (build 1182, opening an estate).
+    const refusal =
+        'NomosBridgeError: NMS-KERNEL-CALL: restore_main: imported custody was refused: '
+        '{"atCommit":"2059537e7c7d1dcaa9b4f6f4ac2ded2ae59b53a5","atIndex":20,'
+        '"check":"colocated-read","error":"foreign-read-not-ready: source workspace '
+        "'catalogue-531e3764f974ff741be62b119a28f0a9dbf396d7' is not resident in this kernel\","
+        '"mode":"verify_chain","ok":true,"valid":false,"walk":"full"}';
+    expect(
+      nomosInternalResidencyRequiredWorkspace(refusal),
+      'catalogue-531e3764f974ff741be62b119a28f0a9dbf396d7',
+    );
+  });
+
+  test('does not mistake other failures for a residency miss', () {
+    // If any of these were read as "mount something and retry", a real error would retry forever.
+    for (final other in <String>[
+      'NomosBridgeError: NMS-KERNEL-CALL: restore_main: verification failed: bad signature',
+      'NomosSeatingPendingFailure: signer enrollment is not yet provably durable',
+      'StateError: the workspace is not on this device\'s plane',
+      '',
+    ]) {
+      expect(nomosInternalResidencyRequiredWorkspace(other), isNull,
+          reason: 'must not treat "$other" as a residency requirement');
+    }
+  });
+
+  test('the sibling refusal that names no workspace is not actionable', () {
+    // The kernel has a second foreign-read-not-ready shape for an unsafe path. There is nothing to
+    // mount, so it must fall through to the caller rather than being retried.
+    expect(
+      nomosInternalResidencyRequiredWorkspace(
+          "foreign-read-not-ready: source workspace '../escape' is not a safe internal custody path"),
+      isNull,
+    );
+  });
+}

package/dart/test/sealing_client_test.dart

@@ -19,7 +19,7 @@ String get _root => '${Directory.current.path}/../..';
 String get _repoEntry => '$_root/cloud/web-client/runner/node-entry.ts';
 String get _fixture => '$_root/cloud/web-client/test/fixtures/encrypted-notes';
 String get _deploy => '$_fixture/build/encrypted-notes.law.usdz';
-String get _lockfile => '$_fixture/nomos.stable-ids.json';
+String get _lockfile => '$_fixture/nomos.identity.usda';
 String get _runtimeDir =>
     Platform.environment['NOMOS_DART_RUNTIME'] ??
     Platform.environment['NOMOS_OFFLINE_RUNTIME'] ??

package/dart/test/webview_bridge_test.dart

@@ -618,6 +618,25 @@ void main() {
     await bridge.ready.timeout(const Duration(seconds: 1));
   });
 
+  test('a local durability span remains workspace/head specific', () async {
+    await bridge.ready;
+    bridge.noteLocalSpan(
+      track: 'submit',
+      name: 'durable save (disk)',
+      kind: 'persist',
+      t0: 100,
+      t1: 120,
+      session: 'born-child',
+      head: '2222222222222222222222222222222222222222',
+    );
+    final saved = bridge.recentSpans
+        .where((event) => event['session'] == 'born-child')
+        .toList();
+    expect(saved, hasLength(2));
+    expect((saved.last['span'] as Map)['head'],
+        '2222222222222222222222222222222222222222');
+  });
+
   test('dispose closes active watches without mutating its iteration',
       () async {
     await bridge.ready;

package/dart_types/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.8.7
+
+- Decode only the kernel's stamped structural map-entry envelope as an envelope. Ordinary domain
+  objects that happen to contain a `value` field now retain all of their fields.
+
 ## 0.8.6
 
 - NEW: `NomosLocalWorkRejectedEvent` / `NomosRejectedIntent` — the typed "the cloud refused work your

package/dart_types/lib/src/subscriptions.dart

@@ -524,13 +524,17 @@ Map<String, Object?> readJsonMapOrEmpty(
 /// container (the flat projection re-parsed it) is returned as-is. A bare scalar (int
 /// from a spike path) is returned unchanged.
 Object? _decodeJsonMapValue(Object? val) {
+  // ONLY the kernel's structural entry shape `{value: {Str|Int: ...}, stamp: ...}`
+  // may be unwrapped. Keying the check on `value` alone ate any legitimate
+  // domain object that happens to carry a `value` field (a custom-field entry
+  // `{fieldId, status, updatedAt, value}` lost everything but its value).
   if (val is Map && val.containsKey('value')) {
     final value = val['value'];
     if (value is Map && value.containsKey('Str')) {
       return _maybeJsonDecode(value['Str']);
     }
     if (value is Map && value.containsKey('Int')) return value['Int'];
-    return value;
+    if (val.containsKey('stamp')) return value;
   }
   return _maybeJsonDecode(val);
 }

package/dart_types/pubspec.yaml

@@ -9,7 +9,7 @@ description: >-
   Pure kernel wire/data types for Nomos Dart frontends — no transport, no bridge,
   no runtime. Typed protobuf and USDA boundary values plus the offer codec,
   reactive read engine, schema validation, and data-only error/trace types.
-version: 0.8.6
+version: 0.8.7
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.105.5",
+  "version": "0.105.7",
   "type": "module",
   "sideEffects": false,
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",