@githolon/dsl 0.103.4 → 0.103.6

package/dart/lib/src/webview_bridge.dart

@@ -41,7 +41,8 @@ import 'package:nomos_types/src/versioned_nomos_ref.dart'
 import 'package:nomos_types/src/foreign_ref.dart'
     show NomosForeignReader, NomosForeignWorkspaceReader;
 
-import 'session_bound.dart' show DomainNotInstalledForSession;
+import 'session_bound.dart'
+    show DomainClientModelAdoptionRequired, DomainNotInstalledForSession;
 
 /// THE ENGINE (architecture/session_bound_clients.md): the multi-workspace RUNTIME — mount/connect,
 /// the session registry, sync, custody + recovery, the home ceremony, and [NomosBridge.follow]
@@ -61,6 +62,143 @@ final class NomosPage<T> {
   final bool done;
 }
 
+/// Typed authority evidence carried by an offer that plans exactly one child birth.
+/// It is offer metadata, never a tenant directive field. The bridge converts it to the
+/// generated protocol's JSON-shaped transport only at the WebView boundary.
+final class NomosBirthCertificate {
+  const NomosBirthCertificate({
+    required this.child,
+    required this.founder,
+    required this.verified,
+    required this.parentKey,
+    required this.parentId,
+    required this.epoch,
+    required this.signature,
+    this.verifiedVia,
+    this.idpToken,
+    this.capturedClock,
+    this.authProviderIssuer,
+    this.authProviderJwks,
+    this.authProviderAudience,
+  });
+
+  final String child;
+  final String founder;
+  final bool verified;
+  final List<int> parentKey;
+  final String parentId;
+  final int epoch;
+  final List<int> signature;
+  final String? verifiedVia;
+  final String? idpToken;
+  final int? capturedClock;
+  final String? authProviderIssuer;
+  final String? authProviderJwks;
+  final String? authProviderAudience;
+
+  static String _string(
+          Map<String, Object?> wire, String camel, String snake) =>
+      (wire[camel] ?? wire[snake] ?? '').toString();
+
+  static List<int> _bytes(
+          Map<String, Object?> wire, String camel, String snake) =>
+      ((wire[camel] ?? wire[snake]) as List? ?? const <Object?>[])
+          .map((value) => (value as num).toInt())
+          .toList(growable: false);
+
+  factory NomosBirthCertificate.fromWire(Map<String, Object?> wire) =>
+      NomosBirthCertificate(
+        child: _string(wire, 'child', 'child'),
+        founder: _string(wire, 'founder', 'founder'),
+        verified: wire['verified'] == true,
+        parentKey: _bytes(wire, 'parentKey', 'parent_key'),
+        parentId: _string(wire, 'parentId', 'parent_id'),
+        epoch: (wire['epoch'] as num?)?.toInt() ?? 0,
+        signature: _bytes(wire, 'signature', 'signature'),
+        verifiedVia: (wire['verifiedVia'] ?? wire['verified_via'])?.toString(),
+        idpToken: (wire['idpToken'] ?? wire['idp_token'])?.toString(),
+        capturedClock:
+            ((wire['capturedClock'] ?? wire['captured_clock']) as num?)
+                ?.toInt(),
+        authProviderIssuer:
+            (wire['authProviderIssuer'] ?? wire['auth_provider_issuer'])
+                ?.toString(),
+        authProviderJwks:
+            (wire['authProviderJwks'] ?? wire['auth_provider_jwks'])
+                ?.toString(),
+        authProviderAudience:
+            (wire['authProviderAudience'] ?? wire['auth_provider_audience'])
+                ?.toString(),
+      );
+
+  Map<String, Object?> toWire() => <String, Object?>{
+        'child': child,
+        'founder': founder,
+        'verified': verified,
+        'parentKey': parentKey,
+        'parentId': parentId,
+        'epoch': epoch,
+        'signature': signature,
+        if (verifiedVia != null) 'verifiedVia': verifiedVia,
+        if (idpToken != null) 'idpToken': idpToken,
+        if (capturedClock != null) 'capturedClock': capturedClock,
+        if (authProviderIssuer != null)
+          'authProviderIssuer': authProviderIssuer,
+        if (authProviderJwks != null) 'authProviderJwks': authProviderJwks,
+        if (authProviderAudience != null)
+          'authProviderAudience': authProviderAudience,
+      };
+}
+
+/// Facts signed by [NomosBridge.signBirthCert]. The secret remains a separate argument and never
+/// enters this value, so callers cannot accidentally serialize private key material with the cert.
+final class NomosBirthCertificateSpec {
+  const NomosBirthCertificateSpec({
+    required this.child,
+    required this.founder,
+    required this.verified,
+    required this.parentKey,
+    required this.parentId,
+    required this.epoch,
+    this.verifiedVia,
+    this.idpToken,
+    this.capturedClock,
+    this.authProviderIssuer,
+    this.authProviderJwks,
+    this.authProviderAudience,
+  });
+
+  final String child;
+  final String founder;
+  final bool verified;
+  final String parentKey;
+  final String parentId;
+  final int epoch;
+  final String? verifiedVia;
+  final String? idpToken;
+  final int? capturedClock;
+  final String? authProviderIssuer;
+  final String? authProviderJwks;
+  final String? authProviderAudience;
+
+  Map<String, Object?> toWire() => <String, Object?>{
+        'child': child,
+        'founder': founder,
+        'verified': verified,
+        'parentKey': parentKey,
+        'parentId': parentId,
+        'epoch': epoch,
+        if (verifiedVia != null) 'verifiedVia': verifiedVia,
+        if (idpToken != null) 'idpToken': idpToken,
+        if (capturedClock != null) 'capturedClock': capturedClock,
+        if (authProviderIssuer != null)
+          'authProviderIssuer': authProviderIssuer,
+        if (authProviderJwks != null) 'authProviderJwks': authProviderJwks,
+        if (authProviderAudience != null)
+          'authProviderAudience': authProviderAudience,
+      };
+}
+
 /// The protocol version the runner and the bridge agree on (`webview-runner.mjs` `WEBVIEW_BRIDGE_VERSION`).
 const int kWebviewBridgeVersion = 1;
 
@@ -116,12 +254,14 @@ class TransferProgress {
   bool get done => total != null && received >= total!;
   factory TransferProgress.fromMessage(Map<String, Object?> m) =>
       TransferProgress(
-        received: (m['received'] as num?)?.toInt() ?? 0,
-        total: (m['total'] as num?)?.toInt(),
+        received: _wireInteger(m['received']) ?? 0,
+        total: _wireInteger(m['total']),
         kind: m['kind']?.toString() ?? 'delta',
       );
 }
 
+int? _wireInteger(Object? value) => value is num ? value.toInt() : null;
+
 /// One opaque point in this workspace's verified history. Applications use it as the handle passed to a
 /// generated client's `past.at(moment)`; [id] is framework identity, not a business field and need never be
 /// parsed. The remaining fields make a timeline useful without exposing commit or event-sourcing ceremony.
@@ -856,8 +996,59 @@ class NomosEncryption {
 
 /// The result of [NomosBridge.offerCreates]: the new local [head], every aggregate the plan minted, and —
 /// for a `.births()` directive — the child workspace(s) the offer brought into being on this local plane.
+enum NomosOperationPhase { locallyAccepted, admittedToRemoteCustody, converged }
+
+/// Product-facing progress for one accepted write. Transport topology and custody identifiers remain private.
+final class NomosOperationStatus {
+  const NomosOperationStatus(this.phase, {this.updatedAt});
+
+  final NomosOperationPhase phase;
+  final DateTime? updatedAt;
+
+  bool get isAdmitted => phase != NomosOperationPhase.locallyAccepted;
+  bool get isConverged => phase == NomosOperationPhase.converged;
+}
+
+/// An awaitable witness for one generated write.
+///
+/// Creation means the write is already accepted into durable local custody. [admitted] completes when the
+/// receiving group accepts it into shared custody; [converged] completes only after this application has
+/// adopted that shared position. Callers never inspect workspaces, URLs, credentials, headers or Git heads.
+final class NomosOperationReceipt {
+  NomosOperationReceipt._()
+      : _status =
+            const NomosOperationStatus(NomosOperationPhase.locallyAccepted),
+        _changes = StreamController<NomosOperationStatus>.broadcast();
+
+  NomosOperationStatus _status;
+  final StreamController<NomosOperationStatus> _changes;
+
+  NomosOperationStatus get current => _status;
+
+  Stream<NomosOperationStatus> watch() async* {
+    yield _status;
+    yield* _changes.stream;
+  }
+
+  Future<void> get admitted => _status.isAdmitted
+      ? Future<void>.value()
+      : watch().firstWhere((status) => status.isAdmitted).then((_) {});
+
+  Future<void> get converged => _status.isConverged
+      ? Future<void>.value()
+      : watch().firstWhere((status) => status.isConverged).then((_) {});
+
+  void _advance(NomosOperationPhase phase) {
+    if (phase.index <= _status.phase.index) return;
+    _status = NomosOperationStatus(phase, updatedAt: DateTime.now());
+    if (!_changes.isClosed) _changes.add(_status);
+    if (phase == NomosOperationPhase.converged) _changes.close();
+  }
+}
+
 class NomosOfferOutcome {
   final String head;
+  final String intentId;
   final List<NomosCreated> created;
 
   /// Every business aggregate touched by the sealed intent, including creates,
@@ -882,15 +1073,25 @@ class NomosOfferOutcome {
   /// local offer lane.
   final Map<String, Object?>? gatewayVerdict;
 
+  final NomosOperationReceipt? _receipt;
+
+  /// Awaitable remote-custody witness for this exact write.
+  NomosOperationReceipt get receipt =>
+      _receipt ??
+      (throw StateError(
+          'This legacy offer outcome has no operation receipt; regenerate the application client.'));
+
   const NomosOfferOutcome({
     required this.head,
+    this.intentId = '',
     required this.created,
     this.affected = const [],
     this.workspace = '',
     this.born = const [],
     this.birthOutcomes = const [],
     this.gatewayVerdict,
-  });
+    NomosOperationReceipt? receipt,
+  }) : _receipt = receipt;
 
   /// TRUE when the offer COMMITTED — it advanced the ledger to a new head (a write landed and/or a child
   /// was born). A REFUSED offer never yields an outcome (it throws / surfaces its typed law error), so a
@@ -1013,12 +1214,14 @@ class NomosBridge {
   late final StreamController<SyncStatus> _syncStatusCtrl =
       StreamController<SyncStatus>.broadcast(
     onListen: _startStatusPoll,
-    onCancel: () {
-      if (!_syncStatusCtrl.hasListener) _stopStatusPoll();
-    },
+    onCancel: _stopStatusPollIfUnused,
   );
   SyncStatus _status = const SyncStatus();
+  final Map<String, SyncStatus> _statusBySession = {};
+  final Map<String, StreamController<SyncStatus>> _syncStatusBySession = {};
   Timer? _metricsTimer;
+  Future<void>? _metricsPoll;
+  bool _metricsPollAgain = false;
   final Completer<void> _ready = Completer<void>();
   // THE LOCAL PLANE'S WORKSPACES. A NomosBridge is a device's local holarchy plane; each connected
   // workspace is a live session on it. [_sessionNames] tracks what [connect] has opened; [_sessionViews]
@@ -1036,6 +1239,11 @@ class NomosBridge {
   // without asking tenant code for cloud URLs, tokens, sessions or signing keys. Kept per source
   // session so one local plane may safely host applications from different clouds/identities.
   final Map<String, _NomosRetainedCloudAccess> _sessionCloudAccess = {};
+  // One model-decision policy follows the generated application through its
+  // child sessions. The callback receives only the typed review object; child
+  // addresses, archives, credentials and lifecycle directives remain private.
+  final Map<String, Future<void> Function(DomainClientModelAdoptionRequired)>
+      _sessionModelChangeHandlers = {};
   // [acquireSession]'s per-workspace single-flight: workspace → the in-flight open every concurrent
   // acquirer joins (removed when it completes; a live session then hits the fast path instead).
   final Map<String, Future<NomosSession>> _acquiring = {};
@@ -1044,6 +1252,11 @@ class NomosBridge {
   // several references, but the runner gets one autoSync registration for that session.
   final Set<String> _autoSyncSessions = {};
   final Map<String, Future<void>> _autoSyncStarting = {};
+  final Map<String, Future<void>> _credentialRefreshStarting = {};
+  // Exact-write custody receipts. The stable intent identity is framework-private; generated application
+  // methods expose only the typed receipt and its product-language lifecycle.
+  final Map<String, Map<String, NomosOperationReceipt>> _operationReceipts = {};
+  final Map<String, NomosOperationReceipt> _birthReceipts = {};
   int _seq = 0;
   final String _traceId = _newTraceId();
   late final StreamSubscription<Map<String, Object?>> _sub;
@@ -1200,29 +1413,59 @@ class NomosBridge {
       if (!_syncEvents.isClosed) _syncEvents.add(m);
       if (event == 'sync') {
         final result = (m['result'] as Map?)?.cast<String, Object?>();
+        final session = m['session']?.toString();
+        if (session != null && result != null) {
+          _advanceOperationReceipts(session, result);
+          if (_syncNeedsCredentialRefresh(m, result)) {
+            unawaited(_refreshSessionCredential(session));
+          }
+        }
         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));
+          _updateScopedStatus(
+              session,
+              (current) => current.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()));
+          _updateScopedStatus(
+              session,
+              (current) => current.copyWith(
+                  phase: SyncPhase.offline,
+                  clearTransfer: true,
+                  lastError:
+                      (result?['pushError'] as Map?)?['error']?.toString()));
+        } else if (result?['pushFailed'] == true) {
+          // The sync round itself completed, but shared custody refused the
+          // push. `stillAhead` is durable debt, not success: surface the
+          // cloud's typed refusal on the owning workspace so generated
+          // `whenCurrent()` calls fail with the real cause instead of timing
+          // out behind a generic saving state.
+          final detail = _syncPushFailureDetail(result!);
+          _updateScopedStatus(
+              session,
+              (current) => current.copyWith(
+                  phase: SyncPhase.error,
+                  clearTransfer: true,
+                  lastError: detail));
         } 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()));
+          _updateScopedStatus(
+              session,
+              (current) => current.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));
+        _updateScopedStatus(m['session']?.toString(),
+            (current) => current.copyWith(phase: SyncPhase.offline));
       }
       return;
     }
@@ -1237,10 +1480,12 @@ class NomosBridge {
       // LIVE pack byte-progress { received, total, kind } — the real loading bar (host Content-Length).
       final tp = TransferProgress.fromMessage(m);
       if (!_transferEvents.isClosed) _transferEvents.add(tp);
-      _pushStatus(_status.copyWith(
-          phase: tp.done ? SyncPhase.syncing : SyncPhase.transferring,
-          transfer: tp,
-          clearTransfer: tp.done));
+      _updateScopedStatus(
+          m['session']?.toString(),
+          (current) => current.copyWith(
+              phase: tp.done ? SyncPhase.syncing : SyncPhase.transferring,
+              transfer: tp,
+              clearTransfer: tp.done));
       return;
     }
     if (event == 'trace') {
@@ -1252,8 +1497,11 @@ class NomosBridge {
       // signal holon projection: ephemeral coordination such as peer frontiers / lag.
       if (!_signalEvents.isClosed) _signalEvents.add(m);
       // the doorbell says canonical main advanced → we're behind until the next pull lands.
-      if (_status.phase == SyncPhase.idle)
-        _pushStatus(_status.copyWith(phase: SyncPhase.behind));
+      _updateScopedStatus(
+          m['session']?.toString(),
+          (current) => current.phase == SyncPhase.idle
+              ? current.copyWith(phase: SyncPhase.behind)
+              : current);
       return;
     }
     if (event == 'span') {
@@ -1341,6 +1589,102 @@ class NomosBridge {
     }
   }
 
+  NomosOperationReceipt _registerOperationReceipt(
+      String workspace, String intentId) {
+    if (intentId.isEmpty) {
+      throw StateError(
+          'Nomos accepted a local write without returning its stable intent identity. '
+          'The runtime and kernel release are incompatible.');
+    }
+    final plane = _eventPlane;
+    // A locally accepted write is not current until custody convergence
+    // advances its receipt. Mark its workspace immediately so a same-tick
+    // `whenCurrent()` cannot return using the previous metrics snapshot.
+    final current = plane._currentSessionStatus(workspace);
+    plane._pushSessionStatus(
+      workspace,
+      current.copyWith(
+        phase: SyncPhase.syncing,
+        ahead: current.ahead + 1,
+        clearError: true,
+      ),
+    );
+    plane._foldApplicationStatusFromSessions();
+    return plane._operationReceipts
+        .putIfAbsent(workspace, () => {})
+        .putIfAbsent(intentId, NomosOperationReceipt._);
+  }
+
+  void _advanceOperationReceipts(
+      String workspace, Map<String, Object?> result) {
+    final pending = _eventPlane._operationReceipts[workspace];
+    if (pending == null || pending.isEmpty) return;
+
+    Iterable<String> ids(String key) => ((result[key] as List?) ?? const [])
+        .whereType<String>()
+        .where((value) => value.isNotEmpty);
+
+    for (final intentId in ids('admittedIntentIds')) {
+      pending[intentId]?._advance(NomosOperationPhase.admittedToRemoteCustody);
+    }
+    for (final intentId in ids('convergedIntentIds')) {
+      final receipt = pending.remove(intentId);
+      receipt?._advance(NomosOperationPhase.converged);
+    }
+    if (pending.isEmpty) _eventPlane._operationReceipts.remove(workspace);
+  }
+
+  bool _syncNeedsCredentialRefresh(
+      Map<String, Object?> message, Map<String, Object?> result) {
+    final push = (result['pushError'] as Map?)?.cast<String, Object?>();
+    final status = push?['status'];
+    if (status == 401 || status == 403) return true;
+    final text =
+        '${message['error'] ?? ''} ${push?['error'] ?? ''}'.toLowerCase();
+    return text.contains('unauthenticated') ||
+        text.contains('token expired') ||
+        text.contains('invalid token');
+  }
+
+  String _syncPushFailureDetail(Map<String, Object?> result) {
+    final push = (result['pushError'] as Map?)?.cast<String, Object?>();
+    final status = push?['status'];
+    final reason = push?['error'] ?? push?['body'];
+    final prefix = status == null
+        ? 'Shared custody refused this workspace change'
+        : 'Shared custody refused this workspace change (HTTP $status)';
+    return reason == null || reason.toString().trim().isEmpty
+        ? prefix
+        : '$prefix: $reason';
+  }
+
+  Future<void> _refreshSessionCredential(String workspace) {
+    final plane = _eventPlane;
+    return plane._credentialRefreshStarting.putIfAbsent(workspace, () async {
+      try {
+        final retained = plane._sessionCloudAccess[workspace];
+        if (retained == null) return;
+        final token = (await retained.signIn())?.trim() ?? '';
+        if (token.isEmpty) {
+          throw StateError(
+              'Nomos could not refresh the signed-in identity for background sync.');
+        }
+        await plane.session(workspace)._call('refreshCredentials', {
+          'authToken': token,
+        });
+      } finally {
+        plane._credentialRefreshStarting.remove(workspace);
+      }
+    });
+  }
+
+  /// The parent-write receipt which brought this child workspace into being, when it was born in this
+  /// mounted application. Ordinary opens of pre-existing workspaces correctly have no creation receipt.
+  NomosOperationReceipt? nomosInternalWorkspaceCreationReceipt() {
+    final workspace = _sessionName;
+    return workspace == null ? null : _eventPlane._birthReceipts[workspace];
+  }
+
   // ── the runtime-aware surface (the boundary the generated Dart client wraps) ──
 
   /// THE PRIMARY MULTI-WORKSPACE ENTRY. Return a [NomosSession] handle pinned to [workspace] — the object a
@@ -1449,6 +1793,15 @@ class NomosBridge {
     }));
     _eventPlane._sessionNames
         .add(ws); // the open succeeded — the session is real now
+    // Opening succeeded, but scoped metrics have not yet proved that this
+    // workspace is current. Unknown readiness must fail closed: otherwise a
+    // generated `whenCurrent()` can observe the default idle value and return
+    // before the first measurement arrives.
+    _eventPlane._statusBySession.putIfAbsent(
+      ws,
+      () => const SyncStatus(phase: SyncPhase.syncing),
+    );
+    _eventPlane._foldApplicationStatusFromSessions();
     final boundPrincipal = _principalFromToken(authToken);
     if (boundPrincipal != null)
       _eventPlane._sessionPrincipals[ws] = boundPrincipal;
@@ -1457,6 +1810,9 @@ class NomosBridge {
     }
     _eventPlane._lastRecovery =
         (r['recovery'] as Map?)?.cast<String, Object?>();
+    if (_eventPlane._syncStatusCtrl.hasListener) {
+      unawaited(_eventPlane._pollMetricsOnce());
+    }
   }
 
   /// The custody lifecycle stream (rebirth_and_custody_lifecycle.md) — a rebirth/divergence surfaces here as a
@@ -1591,6 +1947,7 @@ class NomosBridge {
     // Per-offer signing key (base64 device secret): sign THIS offer with a specific device key instead of
     // the connect-time one (the runner maps it onto `opts.signWith`). Same contract as [offerOutcome].
     String? authorSecret,
+    NomosBirthCertificate? birthCertificate,
   }) async {
     final r = _asMap(await _call('offerDirective', {
       'domain': domain,
@@ -1603,6 +1960,8 @@ class NomosBridge {
       if (force != null) 'force': force,
       if (session != null) 'session': session,
       if (authorSecret != null) 'authorSecret': authorSecret,
+      if (birthCertificate != null)
+        'birthCertificate': birthCertificate.toWire(),
     }));
     return r['head'].toString();
   }
@@ -1625,6 +1984,7 @@ class NomosBridge {
     bool? force,
     String? session,
     String? authorSecret,
+    NomosBirthCertificate? birthCertificate,
   }) =>
       offerOutcome(
         domain: domain,
@@ -1636,6 +1996,7 @@ class NomosBridge {
         force: force,
         session: session,
         authorSecret: authorSecret,
+        birthCertificate: birthCertificate,
       );
 
   /// THE ONE OUTCOME-RETURNING OFFER LANE — [offerDirective] answering the full typed [NomosOfferOutcome]
@@ -1655,6 +2016,7 @@ class NomosBridge {
     // Per-offer signing key (base64 device secret): sign THIS offer with a specific device key instead
     // of the connect-time one — the parent-directed lanes (sibling births after a signer repair) use it.
     String? authorSecret,
+    NomosBirthCertificate? birthCertificate,
   }) async {
     final Map<String, Object?> r;
     // OFFER SPAN TAXONOMY (bridge legs): stamp the Dart-side send/receive around the op; the runner
@@ -1676,6 +2038,8 @@ class NomosBridge {
         if (force != null) 'force': force,
         if (session != null) 'session': session,
         if (authorSecret != null) 'authorSecret': authorSecret,
+        if (birthCertificate != null)
+          'birthCertificate': birthCertificate.toWire(),
       }));
     } catch (e) {
       throw await _wrapDomainNotInstalled(e,
@@ -1748,9 +2112,16 @@ class NomosBridge {
       }
     }
     // The offer ran on this workspace (NomosRef) — stamp every minted ref with it so it is a complete locator.
-    final ws = (r['workspace'] ?? '').toString();
+    final ws = (r['workspace'] ?? sourceSession ?? '').toString();
+    final intentId = (r['intentId'] ?? '').toString();
+    final receipt = _registerOperationReceipt(ws, intentId);
+    for (final child in bornNames) {
+      _eventPlane._birthReceipts[child] = receipt;
+    }
     return NomosOfferOutcome(
       head: r['head'].toString(),
+      intentId: intentId,
+      receipt: receipt,
       workspace: ws,
       created: ((r['created'] as List?) ?? const [])
           .whereType<Map>()
@@ -1889,6 +2260,16 @@ class NomosBridge {
             'acquireSession("$workspace"): the workspace is already bound to a different signed-in person');
       }
       plane._sessionPrincipals[workspace] = sourcePrincipal;
+      final source = _sessionName;
+      if (source != null) {
+        final handler = plane._sessionModelChangeHandlers[source];
+        if (handler != null) {
+          plane._sessionModelChangeHandlers.putIfAbsent(
+            workspace,
+            () => handler,
+          );
+        }
+      }
     }
 
     Future<NomosSession> ready(NomosSession opened) async {
@@ -1920,7 +2301,9 @@ class NomosBridge {
           return ready(session(workspace));
         }
         // Consult the plane's TRUTHFUL registry (mounted ∪ parked ∪ resident custody — the runner's
-        // realm.list()): anything the device already holds opens locally, no cloud, no credentials.
+        // realm.list()). A resident child needs no clone, but a generated application still binds its
+        // retained cloud/session proof here so continuous sync owns that child too. With no retained
+        // credentials (an explicitly local tool/test), preserve the local-only open.
         var resident = false;
         try {
           resident = (await listWorkspaces())
@@ -1929,11 +2312,26 @@ class NomosBridge {
           // a pre-connect plane has no registry yet — fall through to the credentials decision below.
         }
         if (resident) {
-          await connect(
+          if (ifAbsentCredentials == null) {
+            await connect(
+                workspace: workspace,
+                session: workspace,
+                allowUnborn: true,
+                authorSecret: authorSecret);
+          } else {
+            final c = await ifAbsentCredentials();
+            await connect(
+              cloud: c.cloud,
               workspace: workspace,
               session: workspace,
+              clientId: c.clientId,
+              authToken: c.authToken,
+              authorSecret: c.authorSecret ?? authorSecret,
+              // The local birth may not have reached remote custody yet. Binding the cloud posture must
+              // not turn that expected parent-first convergence window into an open failure.
               allowUnborn: true,
-              authorSecret: authorSecret);
+            );
+          }
           return ready(session(workspace));
         }
         if (ifAbsentCredentials == null) {
@@ -2182,6 +2580,21 @@ class NomosBridge {
         .cast<String, Object?>();
   }
 
+  /// Framework-private generated-model staging seam. The generated client owns
+  /// the packaged USDA candidate and the bound session authors the ordinary
+  /// lifecycle offer; tenant code never handles transport bytes or routing.
+  Future<void> nomosInternalStageGeneratedModel({
+    required String domain,
+    required String candidateHash,
+    required List<int> lawUsdz,
+  }) async {
+    await _call('stageGeneratedModel', {
+      'domain': domain,
+      'candidateHash': candidateHash,
+      'lawUsdz': base64Encode(lawUsdz),
+    });
+  }
+
   /// Framework-private exact-history restoration seam. Generated clients expose
   /// `model.restorePrevious()` and a chained `decision.accept(reason)`; predecessor
   /// identity, derived dispositions, heads and receipts stay below this bridge.
@@ -2260,14 +2673,11 @@ class NomosBridge {
   /// VA ROOT-OF-TRUST: sign a BirthCert through the kernel `cert_sign` op (the SINGLE source of the cert
   /// byte-layout — no Dart copy). `fields` = `{child, founder, verified, parentKey (this device's base64
   /// ed25519 PUBLIC half), parentId, epoch}`; `deviceSecret` is that key's base64 SECRET half, handed to the
-  /// LOCAL kernel only (it never reaches a server). Returns the snake_case cert JSON `verify_to_root` parses.
-  Future<Map<String, Object?>> signBirthCert(
-          Map<String, Object?> fields, String deviceSecret) async =>
-      _asMap(await _call('signBirthCert', {
-        'fields': fields,
-        'deviceSecret': deviceSecret
-      }))['cert'] as Map<String, Object?>? ??
-      const {};
+  /// LOCAL kernel only (it never reaches a server). Returns typed authority evidence suitable for an offer.
+  Future<NomosBirthCertificate> signBirthCert(
+          NomosBirthCertificateSpec spec, String deviceSecret) async =>
+      NomosBirthCertificate.fromWire(_asMap(_asMap(await _call('signBirthCert',
+          {'fields': spec.toWire(), 'deviceSecret': deviceSecret}))['cert']));
 
   /// MINT THE KEYLESS ENROLL-ONCE DELEGATION (`enrollFirstDevice.delegationCert`, the verified-first-device
   /// lane). The device SELF-signs it; its authority is the carried `idpToken` (the kernel re-verifies that to
@@ -2862,14 +3272,113 @@ class NomosBridge {
   /// THE APP-READY SYNC STATE — a truthful aggregation of sync rounds, the doorbell, transfer progress, and a
   /// periodic metrics poll. Map straight to a sync-state page. Starts a lightweight 4s metrics poll while
   /// listened to (stops on cancel). [currentStatus] is the latest snapshot for a non-stream read.
-  Stream<SyncStatus> get syncStatus => _eventPlane._syncStatusCtrl.stream;
-  SyncStatus get currentStatus => _eventPlane._status;
+  Stream<SyncStatus> get syncStatus {
+    final session = _sessionName;
+    return session == null
+        ? _eventPlane._syncStatusCtrl.stream
+        : _eventPlane._sessionSyncStatus(session);
+  }
+
+  SyncStatus get currentStatus {
+    final session = _sessionName;
+    return session == null
+        ? _eventPlane._status
+        : _eventPlane._currentSessionStatus(session);
+  }
+
+  Stream<SyncStatus> _sessionSyncStatus(String session) =>
+      _eventPlane._syncStatusBySession
+          .putIfAbsent(
+            session,
+            () => StreamController<SyncStatus>.broadcast(
+              onListen: () => _eventPlane._startSessionStatusPoll(session),
+              onCancel: _eventPlane._stopStatusPollIfUnused,
+            ),
+          )
+          .stream;
+
+  SyncStatus _currentSessionStatus(String session) =>
+      _eventPlane._statusBySession[session] ?? const SyncStatus();
 
   void _pushStatus(SyncStatus s) {
     _status = s;
     if (!_syncStatusCtrl.isClosed) _syncStatusCtrl.add(s);
   }
 
+  void _pushSessionStatus(String session, SyncStatus status) {
+    _statusBySession[session] = status;
+    final controller = _syncStatusBySession[session];
+    if (controller != null && !controller.isClosed) controller.add(status);
+  }
+
+  void _updateScopedStatus(
+    String? session,
+    SyncStatus Function(SyncStatus current) update,
+  ) {
+    if (session == null || session.isEmpty) {
+      _pushStatus(update(_status));
+      return;
+    }
+    _pushSessionStatus(session, update(_currentSessionStatus(session)));
+    _foldApplicationStatusFromSessions();
+  }
+
+  void _foldApplicationStatusFromSessions() {
+    final statuses = _sessionNames
+        .map((session) => _statusBySession[session])
+        .whereType<SyncStatus>()
+        .toList(growable: false);
+    if (statuses.isEmpty) return;
+
+    SyncPhase phase;
+    if (statuses.any((status) => status.phase == SyncPhase.error)) {
+      phase = SyncPhase.error;
+    } else if (statuses.any((status) => status.phase == SyncPhase.offline)) {
+      phase = SyncPhase.offline;
+    } else if (statuses
+        .any((status) => status.phase == SyncPhase.transferring)) {
+      phase = SyncPhase.transferring;
+    } else if (statuses.any(
+        (status) => status.phase == SyncPhase.behind || status.behind > 0)) {
+      phase = SyncPhase.behind;
+    } else if (statuses.any(
+        (status) => status.phase == SyncPhase.syncing || status.ahead > 0)) {
+      phase = SyncPhase.syncing;
+    } else {
+      phase = SyncPhase.idle;
+    }
+
+    int total(int Function(SyncStatus status) read) =>
+        statuses.fold(0, (sum, status) => sum + read(status));
+    final lastSynced = statuses
+        .map((status) => status.lastSyncedAt)
+        .whereType<DateTime>()
+        .fold<DateTime?>(
+            null,
+            (oldest, value) =>
+                oldest == null || value.isBefore(oldest) ? value : oldest);
+    final error = statuses
+        .map((status) => status.lastError)
+        .whereType<String>()
+        .firstOrNull;
+    final transfer = statuses
+        .map((status) => status.transfer)
+        .whereType<TransferProgress>()
+        .firstOrNull;
+
+    _pushStatus(SyncStatus(
+      phase: phase,
+      ahead: total((status) => status.ahead),
+      behind: total((status) => status.behind),
+      saved: total((status) => status.saved),
+      onMain: total((status) => status.onMain),
+      deadLetters: total((status) => status.deadLetters),
+      transfer: transfer,
+      lastSyncedAt: lastSynced,
+      lastError: error,
+    ));
+  }
+
   void _startStatusPoll() {
     _pushStatus(_status); // seed the new listener with the current snapshot
     _pollMetricsOnce();
@@ -2877,33 +3386,109 @@ class NomosBridge {
         Timer.periodic(const Duration(seconds: 4), (_) => _pollMetricsOnce());
   }
 
+  void _startSessionStatusPoll(String session) {
+    _pushSessionStatus(session, _currentSessionStatus(session));
+    _pollMetricsOnce();
+    _metricsTimer ??=
+        Timer.periodic(const Duration(seconds: 4), (_) => _pollMetricsOnce());
+  }
+
+  void _stopStatusPollIfUnused() {
+    if (_syncStatusCtrl.hasListener ||
+        _syncStatusBySession.values
+            .any((controller) => controller.hasListener)) {
+      return;
+    }
+    _stopStatusPoll();
+  }
+
   void _stopStatusPoll() {
     _metricsTimer?.cancel();
     _metricsTimer = null;
   }
 
   Future<void> _pollMetricsOnce() async {
+    final plane = _eventPlane;
+    final inFlight = plane._metricsPoll;
+    if (inFlight != null) {
+      plane._metricsPollAgain = true;
+      return inFlight;
+    }
+
+    final poll = plane._pollMetricsForOpenSessions();
+    plane._metricsPoll = poll;
     try {
-      final m = await metrics();
-      int? n(String k) =>
-          m.containsKey(k) ? ((m[k] as num?)?.toInt() ?? 0) : null;
-      final ahead = n('ahead') ?? _status.ahead;
-      final behind = n('behind') ?? _status.behind;
-      // Don't stomp an in-flight transfer's phase; otherwise derive idle/behind/syncing from the counts.
-      final phase = _status.transfer != null
-          ? _status.phase
-          : (behind > 0
-              ? SyncPhase.behind
-              : (ahead > 0 ? SyncPhase.syncing : SyncPhase.idle));
-      _pushStatus(_status.copyWith(
-        ahead: ahead,
-        behind: behind,
-        saved: n('saved'),
-        onMain: n('onMain'),
-        deadLetters: n('deadLetters'),
-        phase: phase,
-        clearError: true,
-      ));
+      await poll;
+    } finally {
+      if (identical(plane._metricsPoll, poll)) plane._metricsPoll = null;
+      if (plane._metricsPollAgain) {
+        plane._metricsPollAgain = false;
+        unawaited(plane._pollMetricsOnce());
+      }
+    }
+  }
+
+  Future<void> _pollMetricsForOpenSessions() async {
+    try {
+      // SyncStatus belongs to the local application plane, not whichever
+      // workspace happened to connect first. Once that plane has more than
+      // one open workspace the raw bridge deliberately refuses an unscoped
+      // `metrics` call, so ask every live session explicitly and fold their
+      // counters into one application status.
+      final sessions = _eventPlane._sessionNames.toList(growable: false);
+      // A listener can attach just before the first connect finishes. Never
+      // issue an unscoped diagnostic request in that gap: by the time the
+      // runner handles it, several generated children may legitimately be
+      // open and the plane must then reject the ambiguous request. The next
+      // periodic tick (or sync event) will measure the now-open sessions.
+      if (sessions.isEmpty) return;
+      final measurements = await Future.wait(
+        sessions.map((session) => metrics(session)),
+      );
+
+      int? metric(Map<String, Object?> measurement, String key) {
+        if (!measurement.containsKey(key)) return null;
+        final value = measurement[key];
+        if (value is num) return value.toInt();
+        // The runtime's `behind` metric is deliberately a head-comparison
+        // verdict, whereas SyncStatus exposes the same fact as a count. Keep
+        // that typed boundary explicit instead of casting the boolean to num.
+        if (value is bool) return value ? 1 : 0;
+        throw FormatException(
+          "Nomos sync metric '$key' must be numeric or boolean, got ${value.runtimeType}",
+        );
+      }
+
+      for (var index = 0; index < sessions.length; index += 1) {
+        final session = sessions[index];
+        final measurement = measurements[index];
+        final current = _currentSessionStatus(session);
+        final ahead = metric(measurement, 'ahead') ?? current.ahead;
+        final behind = metric(measurement, 'behind') ?? current.behind;
+        // Counters prove custody debt, but they do not prove that a failed or
+        // offline transport recovered. Only a subsequent successful sync/link
+        // event may clear those lifecycle states.
+        final phase = current.transfer != null ||
+                current.phase == SyncPhase.error ||
+                current.phase == SyncPhase.offline
+            ? current.phase
+            : (behind > 0
+                ? SyncPhase.behind
+                : (ahead > 0 ? SyncPhase.syncing : SyncPhase.idle));
+        _pushSessionStatus(
+          session,
+          current.copyWith(
+            ahead: ahead,
+            behind: behind,
+            saved: metric(measurement, 'saved'),
+            onMain: metric(measurement, 'onMain'),
+            deadLetters: metric(measurement, 'deadLetters'),
+            phase: phase,
+            clearError: phase != SyncPhase.error && phase != SyncPhase.offline,
+          ),
+        );
+      }
+      _foldApplicationStatusFromSessions();
     } catch (e) {
       _pushStatus(
           _status.copyWith(phase: SyncPhase.error, lastError: e.toString()));
@@ -3194,8 +3779,18 @@ class NomosBridge {
     return ctrl.stream;
   }
 
-  /// Tear down: stop the transport subscription + fail any in-flight calls.
+  /// Tear down the application realm, then stop the transport subscription and
+  /// fail any remaining in-flight calls. The native kernel plane may remain
+  /// resident for custody/cache reuse, but its application-owned sessions,
+  /// watches and continuous-sync loops must not survive this client.
   Future<void> dispose() async {
+    try {
+      await _call('disposeRealm').timeout(const Duration(seconds: 10));
+    } catch (_) {
+      // A dead/unstarted embedding has no reachable runner to release. The
+      // enclosing engine host is still disposed below by NomosScope; never let
+      // teardown strand the Flutter lifecycle on an unavailable transport.
+    }
     await _sub.cancel();
     final pending = _pending.entries
         .map((entry) => (
@@ -3239,6 +3834,11 @@ class NomosBridge {
     if (!_flameEvents.isClosed) await _flameEvents.close();
     if (!_spanEvents.isClosed) await _spanEvents.close();
     if (!_transferEvents.isClosed) await _transferEvents.close();
+    final sessionStatuses = _syncStatusBySession.values.toList(growable: false);
+    _syncStatusBySession.clear();
+    for (final status in sessionStatuses) {
+      if (!status.isClosed) unawaited(status.close());
+    }
     if (!_syncStatusCtrl.isClosed) await _syncStatusCtrl.close();
   }
 }
@@ -3311,6 +3911,7 @@ class NomosSession extends NomosBridge {
       String? authorSecret,
       String? inheritedPrincipal}) {
     final retained = parent._sessionCloudAccess[this.workspace];
+    final modelChange = parent._sessionModelChangeHandlers[this.workspace];
     final opened = parent.acquireSession(
       workspace,
       ifAbsentCredentials: ifAbsentCredentials ??
@@ -3325,10 +3926,63 @@ class NomosSession extends NomosBridge {
       // credential posture (home -> shared home -> child workspace remains one stateful application).
       if (retained != null)
         parent._sessionCloudAccess.putIfAbsent(workspace, () => retained);
+      if (modelChange != null) {
+        parent._sessionModelChangeHandlers.putIfAbsent(
+          workspace,
+          () => modelChange,
+        );
+      }
       return session;
     });
   }
 
+  /// Generator-only parent-to-child model inheritance. The compiled USDZ is
+  /// opaque transport; the target child's kernel re-derives its identity and
+  /// judges the ordinary signed stageDomain offer before custody changes.
+  Future<void> nomosInternalEnsureGeneratedModelInChild({
+    required String childWorkspace,
+    required String domain,
+    required String candidateHash,
+    required List<int> lawUsdz,
+  }) async {
+    final source = _sessionName;
+    if (source == null || source.isEmpty) {
+      throw StateError(
+          'Generated child model inheritance needs a bound parent session.');
+    }
+    await _call('stageGeneratedModelFromParent', {
+      'sourceSession': source,
+      'session': childWorkspace,
+      'domain': domain,
+      'candidateHash': candidateHash,
+      'lawUsdz': base64Encode(lawUsdz),
+    });
+  }
+
+  /// Retain the application's typed model-decision policy for generated child
+  /// workspaces. This is not a deployment callback and carries no protocol data.
+  void nomosInternalRetainModelChangeHandler(
+    Future<void> Function(DomainClientModelAdoptionRequired) handler,
+  ) {
+    final workspace = _sessionName;
+    if (workspace == null || workspace.isEmpty) {
+      throw StateError(
+          'Model change handling needs a bound application session.');
+    }
+    _eventPlane._sessionModelChangeHandlers[workspace] = handler;
+  }
+
+  Future<void> nomosInternalHandleModelChange(
+    DomainClientModelAdoptionRequired change,
+  ) async {
+    final workspace = _sessionName;
+    final handler = workspace == null
+        ? null
+        : _eventPlane._sessionModelChangeHandlers[workspace];
+    if (handler == null) throw change;
+    await handler(change);
+  }
+
   /// Generator/runtime-host seam: retain this application's refreshable cloud access privately so
   /// generated reference reads can mount another authorized workspace after a cold start.
   ///