@githolon/dsl 0.108.7 → 0.110.0

package/dart/lib/src/runtime_v2_gateway.dart

@@ -5,7 +5,14 @@ import 'package:fixnum/fixnum.dart' as fixnum;
 import 'package:meta/meta.dart' show internal;
 import 'package:nomos_types/nomos_kernel_protocol.dart' as nomos_protocol;
 import 'package:nomos_types/nomos_types.dart'
-    show NomosErrorInfo, nomosErrorFromInfo;
+    show
+        NomosErrorInfo,
+        NomosRefusalReason,
+        NomosRefused,
+        NomosRuntimeFailure,
+        NomosRuntimeFailureKind,
+        NomosUnavailable,
+        nomosErrorFromInfo;
 
 import 'runtime_v2_transport.dart';
 
@@ -16,12 +23,11 @@ final class NmsRuntimeV2Gateway {
   NmsRuntimeV2Gateway(this._transport);
 
   final NomosRuntimeV2Transport _transport;
-  int _sequence = 0;
 
   Future<nomos_protocol.RuntimeResponse> invoke(
     nomos_protocol.RuntimeRequest request,
   ) async {
-    final requestId = fixnum.Int64(++_sequence);
+    final requestId = fixnum.Int64(_transport.nextRuntimeRequestId());
     request
       ..protocolVersion = 2
       ..requestId = requestId;
@@ -36,8 +42,55 @@ final class NmsRuntimeV2Gateway {
         'Runtime v2 response ${response.requestId} belongs to another request',
       );
     }
+    if (response.hasUnavailable()) {
+      throw NomosUnavailable.fromRuntime(response.unavailable);
+    }
+    if (response.hasRefused()) {
+      final refused = response.refused;
+      throw NomosRefused(
+        reason: switch (refused.reason) {
+          nomos_protocol.RuntimeRefusalReason
+                .RUNTIME_REFUSAL_REASON_INVALID_CREDENTIAL =>
+            NomosRefusalReason.invalidCredential,
+          nomos_protocol
+                .RuntimeRefusalReason.RUNTIME_REFUSAL_REASON_ACCESS_DENIED =>
+            NomosRefusalReason.accessDenied,
+          nomos_protocol
+                .RuntimeRefusalReason.RUNTIME_REFUSAL_REASON_PLACEMENT_POLICY =>
+            NomosRefusalReason.placementPolicy,
+          nomos_protocol
+                .RuntimeRefusalReason.RUNTIME_REFUSAL_REASON_SESSION_UNBOUND =>
+            NomosRefusalReason.sessionUnbound,
+          _ => NomosRefusalReason.unknown,
+        },
+        workspace: refused.workspace,
+        retryable: refused.retryable,
+        detail: refused.detail,
+      );
+    }
     if (response.hasFailure()) {
       final failure = response.failure;
+      if (failure.kind !=
+          nomos_protocol.RuntimeFailureKind.RUNTIME_FAILURE_KIND_UNSPECIFIED) {
+        throw NomosRuntimeFailure(
+          kind: switch (failure.kind) {
+            nomos_protocol.RuntimeFailureKind.RUNTIME_FAILURE_KIND_INTERNAL =>
+              NomosRuntimeFailureKind.internal,
+            nomos_protocol.RuntimeFailureKind.RUNTIME_FAILURE_KIND_PROTOCOL =>
+              NomosRuntimeFailureKind.protocol,
+            nomos_protocol.RuntimeFailureKind.RUNTIME_FAILURE_KIND_INTEGRITY =>
+              NomosRuntimeFailureKind.integrity,
+            nomos_protocol
+                  .RuntimeFailureKind.RUNTIME_FAILURE_KIND_UNSUPPORTED =>
+              NomosRuntimeFailureKind.unsupported,
+            _ => NomosRuntimeFailureKind.unknown,
+          },
+          code: failure.code,
+          message: failure.message,
+          component: failure.component,
+          workspace: failure.hasWorkspace() ? failure.workspace : null,
+        );
+      }
       throw nomosErrorFromInfo(
         NomosErrorInfo(
           code: failure.code,

package/dart/lib/src/runtime_v2_transport.dart

@@ -2,16 +2,32 @@
 library;
 
 import 'dart:async';
+import 'dart:convert';
+import 'dart:developer' as developer;
+import 'dart:typed_data';
 
 import 'package:fixnum/fixnum.dart' as fixnum;
 import 'package:meta/meta.dart' show internal;
+import 'package:crypto/crypto.dart' show sha256;
+import 'package:nomos_peer_host/nomos_peer_host.dart'
+    show
+        NomosDeviceIdentityStore,
+        NomosLawPackageSource,
+        NomosProviderCredentialStore,
+        NomosSignIn;
 import 'package:nomos_types/nomos_kernel_protocol.dart' as nomos_protocol;
+import 'package:nomos_types/nomos_types.dart' show NomosUnavailable;
+
+import 'console_enrolment.dart';
+import 'console_http_stub.dart' if (dart.library.io) 'console_http_io.dart'
+    as console_http;
 
 /// Binary generated-message path from an application host to the kernel.
 abstract interface class NomosKernelCallTransport {
   Future<nomos_protocol.CallResponse> callKernel({
     required String session,
     required nomos_protocol.CallRequest request,
+    required nomos_protocol.CredentialUse credentialUse,
   });
 }
 
@@ -21,6 +37,12 @@ abstract interface class NomosRuntimeV2Transport {
   Future<nomos_protocol.RuntimeResponse> invokeRuntime(
     nomos_protocol.RuntimeRequest request,
   );
+
+  /// ONE request-id space per transport. Every caller that frames a Runtime v2 request over this
+  /// transport (the reception's gateway, direct kernel calls, the native plane) must draw its id
+  /// here; two independent counters on one transport collided in flight ("request N is already
+  /// pending") the moment a child workspace session opened beside its parent.
+  int nextRuntimeRequestId();
 }
 
 /// Generated asynchronous runtime event lane. It is separate from invocation
@@ -29,10 +51,519 @@ abstract interface class NomosRuntimeV2EventTransport {
   Stream<nomos_protocol.RuntimeEvent> get runtimeEvents;
 }
 
+/// What a genuine cloud acquisition needs when the peer reports that its live
+/// identity proof is no longer usable. The platform credential provider owns
+/// how this is obtained; generated clients and Reception only receive the
+/// refreshed proof selected for a runtime session.
+final class NomosSessionCredentials {
+  const NomosSessionCredentials({
+    required this.cloud,
+    this.authToken,
+    this.authorSecret,
+  });
+
+  final String cloud;
+  final String? authToken;
+  final String? authorSecret;
+}
+
+/// Platform-shell capability supplying renewable identity proof to a peer.
+///
+/// This is deliberately not part of a generated application client and it is
+/// not workspace authority. Firebase, an OS account provider, or another
+/// platform service may produce a token; the kernel still decides whether the
+/// proof is admissible. A child session aliases the same capability rather
+/// than copying either its callback or its current token.
+abstract interface class NomosPlatformCredentialProviders {
+  void registerCredentialProvider({
+    required String capability,
+    required String cloud,
+    required NomosSignIn signIn,
+  });
+
+  Future<NomosSessionCredentials> Function({String? deviceChallenge})?
+      credentialProviderForCapability(String capability);
+
+  /// The shell's durable device identity store, answering the runtime's
+  /// load/save effect. A shell that registers none refuses that effect typed.
+  void registerDeviceIdentityStore(NomosDeviceIdentityStore store);
+
+  /// Register the platform's durable ID-token cache. Native shells use
+  /// Keychain/Keystore; a shell without one simply asks its provider.
+  void registerProviderCredentialStore(NomosProviderCredentialStore store);
+
+  /// The application's compiled law package by identity, answering the
+  /// runtime's law-package effect when a workspace must stage the package it
+  /// was released against. A shell that registers none refuses that effect
+  /// typed; the runtime reports the adoption deferred.
+  void registerLawPackageSource(NomosLawPackageSource source);
+
+  /// Replace the shell's console transport (D22 enrolment). Native shells
+  /// default to `dart:io`; a shell without it must register one.
+  void registerConsolePost(NomosConsolePost post);
+}
+
+final class _NmsPlatformCredentialProvider {
+  _NmsPlatformCredentialProvider({required this.cloud, required this.signIn});
+
+  final String cloud;
+  final NomosSignIn signIn;
+
+  /// One flight per challenge: a burst of refreshes for the same proof shares
+  /// one provider call, while a device-bound request never rides a plain one.
+  final Map<String, Future<String>> _refreshFlights = {};
+
+  Future<NomosSessionCredentials> credentials({String? deviceChallenge}) async {
+    final key = deviceChallenge ?? '';
+    final token =
+        await (_refreshFlights[key] ?? _startRefresh(key, deviceChallenge));
+    return NomosSessionCredentials(cloud: cloud, authToken: token);
+  }
+
+  Future<String> _startRefresh(String key, String? deviceChallenge) {
+    final flight = () async {
+      final token =
+          (await signIn(deviceChallenge: deviceChallenge))?.trim() ?? '';
+      if (token.isEmpty) {
+        throw StateError(
+          'Nomos could not refresh the signed-in identity for this peer session',
+        );
+      }
+      return token;
+    }();
+    _refreshFlights[key] = flight;
+    return flight.whenComplete(() {
+      if (identical(_refreshFlights[key], flight)) _refreshFlights.remove(key);
+    });
+  }
+}
+
+/// Reusable platform-shell implementation. Concrete native, WebView, browser
+/// and Node connections mix this in; Reception merely uses the capability.
+/// The map is keyed by the opaque capability identity issued by Runtime v2.
+/// Session-to-capability ownership remains exclusively in the peer runtime;
+/// this platform adapter therefore never mirrors or inherits session state.
+mixin NmsPlatformCredentialProviderHost
+    implements NomosPlatformCredentialProviders {
+  final Map<String, _NmsPlatformCredentialProvider>
+      _nmsCredentialProvidersByCapability = {};
+  NomosDeviceIdentityStore? _nmsDeviceIdentityStore;
+  NomosProviderCredentialStore? _nmsProviderCredentialStore;
+
+  @override
+  void registerCredentialProvider({
+    required String capability,
+    required String cloud,
+    required NomosSignIn signIn,
+  }) {
+    _nmsCredentialProvidersByCapability[capability] =
+        _NmsPlatformCredentialProvider(cloud: cloud, signIn: signIn);
+  }
+
+  @override
+  Future<NomosSessionCredentials> Function({String? deviceChallenge})?
+      credentialProviderForCapability(String capability) {
+    final provider = _nmsCredentialProvidersByCapability[capability];
+    return provider == null ? null : provider.credentials;
+  }
+
+  @override
+  void registerDeviceIdentityStore(NomosDeviceIdentityStore store) {
+    _nmsDeviceIdentityStore = store;
+  }
+
+  @override
+  void registerProviderCredentialStore(NomosProviderCredentialStore store) {
+    _nmsProviderCredentialStore = store;
+  }
+
+  NomosLawPackageSource? _nmsLawPackageSource;
+
+  @override
+  void registerLawPackageSource(NomosLawPackageSource source) {
+    _nmsLawPackageSource = source;
+  }
+
+  NomosConsolePost _nmsConsolePost = console_http.nomosDefaultConsolePost;
+
+  @override
+  void registerConsolePost(NomosConsolePost post) {
+    _nmsConsolePost = post;
+  }
+
+  /// D22/D23: enrol this device's key with the application's console enroller.
+  /// Peer Office decides when and how often; this performs one attempt. The
+  /// provider is asked for a FRESH plain identity token (no device challenge,
+  /// never the durable cache: the console spends each token once), the request
+  /// is signed with the device secret this shell's identity store holds, and
+  /// the token goes only to the console. Neither the token nor the secret is
+  /// returned to the runtime.
+  Future<nomos_protocol.PeerEffectReceipt> performConsoleEnrolment(
+    nomos_protocol.PeerConsoleEnrolmentEffect effect,
+  ) async {
+    nomos_protocol.PeerEffectReceipt failed(String message) =>
+        nomos_protocol.PeerEffectReceipt(
+          effectId: effect.effectId,
+          failure: nomos_protocol.PeerEffectFailure(
+            reason: nomos_protocol
+                .PeerEffectFailureReason.PEER_EFFECT_FAILURE_REASON_TRANSPORT,
+            message: message,
+          ),
+        );
+    nomos_protocol.PeerEffectReceipt refused(int status, String message,
+            {String code = '', bool? retryable}) =>
+        nomos_protocol.PeerEffectReceipt(
+          effectId: effect.effectId,
+          consoleEnrolmentRefused: nomos_protocol.PeerConsoleEnrolmentRefused(
+            status: status,
+            message: message,
+            code: code,
+            retryable: retryable,
+          ),
+        );
+    final store = _nmsDeviceIdentityStore;
+    if (store == null) {
+      return failed(
+          'this platform shell keeps no durable device identity store');
+    }
+    final provider = _nmsCredentialProvidersByCapability[effect.capability];
+    if (provider == null) {
+      return failed(
+          'this platform shell has no identity provider for the session');
+    }
+    final Uint8List? secret;
+    try {
+      secret = await store.load(effect.deviceIdentity);
+    } catch (_) {
+      return failed(
+          'the platform device identity store could not load the device identity');
+    }
+    if (secret == null || secret.length != 32) {
+      return failed('this device holds no usable identity to enrol');
+    }
+    final String token;
+    try {
+      token = (await provider.signIn(deviceChallenge: null))?.trim() ?? '';
+    } catch (_) {
+      return failed('the identity provider could not sign this person in');
+    }
+    if (token.isEmpty) {
+      return failed('the identity provider returned no identity token');
+    }
+    try {
+      final enrolled = await enrolWithConsole(
+        console: effect.console,
+        tenant: effect.tenant,
+        scope: effect.scope,
+        providerToken: token,
+        device: NomosConsoleEnrolmentDevice.fromSeed(secret),
+        workspaces: effect.workspaces,
+        post: _nmsConsolePost,
+      );
+      // The console's fan-out into the person's other workspaces: what it
+      // could not enrol stays visible (those workspaces refuse this device's
+      // writes until an enrolment lands there).
+      for (final entry in enrolled.refused.entries) {
+        developer.log(
+            'console enrolment into ${entry.key} was refused: ${entry.value}',
+            name: 'nomos.console_enrolment');
+      }
+      return nomos_protocol.PeerEffectReceipt(
+        effectId: effect.effectId,
+        consoleEnrolled: nomos_protocol.PeerConsoleEnrolled(
+          principal: enrolled.principal,
+          keyHash: enrolled.keyHash,
+          heads: enrolled.workspaces.entries,
+        ),
+      );
+    } on NomosConsoleEnrolmentRefused catch (refusal) {
+      return refused(refusal.status, refusal.message,
+          code: refusal.code, retryable: refusal.retryable);
+    } catch (error) {
+      // Never echo the request: it carries the token.
+      return failed('the console could not be reached (${error.runtimeType})');
+    }
+  }
+
+  /// Hand the runtime the application's law package for the identity it
+  /// names. The runtime decides when a package is needed (a workspace that
+  /// must stage the approved model); this only performs the physical read.
+  /// A shell without a source, or without that package, answers typed.
+  Future<nomos_protocol.PeerEffectReceipt> performLawPackageEffect(
+    nomos_protocol.PeerLawPackageEffect effect,
+  ) async {
+    nomos_protocol.PeerEffectReceipt refused(String message) =>
+        nomos_protocol.PeerEffectReceipt(
+          effectId: effect.effectId,
+          failure: nomos_protocol.PeerEffectFailure(
+            reason: nomos_protocol
+                .PeerEffectFailureReason.PEER_EFFECT_FAILURE_REASON_TRANSPORT,
+            message: message,
+          ),
+        );
+    final source = _nmsLawPackageSource;
+    if (source == null) {
+      return refused(
+          'this platform shell supplies no application law packages');
+    }
+    if (!RegExp(r'^[0-9a-f]{64}$').hasMatch(effect.lawSha256)) {
+      return refused('law package effect names no package identity');
+    }
+    try {
+      final bytes = await source.load(effect.lawSha256);
+      if (bytes == null || bytes.isEmpty) {
+        return refused(
+            'this application holds no law package with identity ${effect.lawSha256}');
+      }
+      return nomos_protocol.PeerEffectReceipt(
+        effectId: effect.effectId,
+        lawPackage: nomos_protocol.PeerLawPackage(lawUsdz: bytes),
+      );
+    } catch (error) {
+      return refused('the application law package could not be read: $error');
+    }
+  }
+
+  /// Execute the opaque platform capability requested by Peer Office. The
+  /// runtime owns the decision to refresh (a refusal, or renewal ahead of
+  /// expiry), the device challenge it carries, and any subsequent offer retry.
+  Future<nomos_protocol.PeerEffectReceipt> performCredentialRefresh(
+    nomos_protocol.PeerCredentialRefreshEffect effect,
+  ) async {
+    try {
+      final registered = _nmsCredentialProvidersByCapability[effect.capability];
+      final provider = registered?.credentials;
+      final challenge =
+          effect.hasDeviceChallenge() ? effect.deviceChallenge : null;
+      final entry = registered == null
+          ? null
+          : sha256
+              .convert(utf8.encode(
+                'nomos-provider-credential-v1\u0000${registered.cloud}'
+                '\u0000${effect.capability}\u0000${challenge ?? ''}',
+              ))
+              .toString();
+      String? token;
+      final durable = _nmsProviderCredentialStore;
+      if (effect.allowCached && durable != null && entry != null) {
+        try {
+          final rejected = effect.hasRejectedAuthTokenSha256()
+              ? effect.rejectedAuthTokenSha256
+              : const <int>[];
+          for (final candidate in await durable.loadCandidates(entry)) {
+            final value = candidate.trim();
+            if (value.isEmpty) continue;
+            final digest = sha256.convert(utf8.encode(value)).bytes;
+            if (rejected.length == digest.length) {
+              var same = true;
+              for (var i = 0; i < digest.length; i += 1) {
+                if (rejected[i] != digest[i]) {
+                  same = false;
+                  break;
+                }
+              }
+              if (same) continue;
+            }
+            token = value;
+            break;
+          }
+        } catch (_) {
+          // A damaged/unavailable cache never blocks the provider. The store
+          // exposes no token material through diagnostics.
+        }
+      }
+      NomosSessionCredentials? credentials;
+      if (token == null && provider != null) {
+        credentials = await provider(deviceChallenge: challenge);
+        token = credentials.authToken?.trim();
+        if (token != null &&
+            token.isNotEmpty &&
+            durable != null &&
+            entry != null) {
+          try {
+            await durable.retainCandidate(entry, token);
+          } catch (_) {
+            // The fresh proof remains usable for this process even when its
+            // durable cache cannot be updated.
+          }
+        }
+      }
+      final secret = credentials?.authorSecret?.trim();
+      return nomos_protocol.PeerEffectReceipt(
+        effectId: effect.effectId,
+        credentialRefreshed: nomos_protocol.PeerCredentialRefreshed(
+          authToken: token == null || token.isEmpty ? null : utf8.encode(token),
+          authorSecret:
+              secret == null || secret.isEmpty ? null : base64Decode(secret),
+        ),
+      );
+    } catch (_) {
+      return nomos_protocol.PeerEffectReceipt(
+        effectId: effect.effectId,
+        failure: nomos_protocol.PeerEffectFailure(
+          reason: nomos_protocol
+              .PeerEffectFailureReason.PEER_EFFECT_FAILURE_REASON_TRANSPORT,
+          message:
+              'Platform credential provider could not refresh identity proof',
+        ),
+      );
+    }
+  }
+
+  /// Move one identity's secret between the runtime and this shell's durable
+  /// store. The runtime owns the sequence (load before the first signed offer,
+  /// save once a secret exists); this only performs the named physical effect.
+  /// A shell without a store answers typed; it never invents a secret.
+  Future<nomos_protocol.PeerEffectReceipt> performDeviceIdentityEffect(
+    nomos_protocol.PeerDeviceIdentityEffect effect,
+  ) async {
+    final store = _nmsDeviceIdentityStore;
+    nomos_protocol.PeerEffectReceipt refused(String message) =>
+        nomos_protocol.PeerEffectReceipt(
+          effectId: effect.effectId,
+          failure: nomos_protocol.PeerEffectFailure(
+            reason: nomos_protocol
+                .PeerEffectFailureReason.PEER_EFFECT_FAILURE_REASON_TRANSPORT,
+            message: message,
+          ),
+        );
+    if (store == null) {
+      return refused(
+          'this platform shell keeps no durable device identity store');
+    }
+    if (effect.identity.isEmpty) {
+      return refused('device identity effect names no identity');
+    }
+    try {
+      Uint8List? secret;
+      nomos_protocol.DeviceRecoveryRecord? recovery;
+      if (effect.hasLoad()) {
+        secret = await store.load(effect.identity);
+        // Dart's protobuf bytes field elides empty values. Refuse corruption
+        // here so it cannot cross the wire disguised as an absent identity.
+        if (secret != null && secret.length != 32) {
+          return refused('the stored device identity is malformed');
+        }
+      } else if (effect.hasSave()) {
+        await store.save(
+            effect.identity, Uint8List.fromList(effect.save.secret));
+      } else if (effect.hasLoadRecovery()) {
+        final bytes =
+            await store.load('nomos-device-recovery-v1|${effect.identity}');
+        if (bytes != null) {
+          recovery = nomos_protocol.DeviceRecoveryRecord.fromBuffer(bytes);
+        }
+      } else if (effect.hasSaveRecovery()) {
+        if (!effect.saveRecovery.hasRecord()) {
+          return refused('device recovery save contains no record');
+        }
+        await store.save('nomos-device-recovery-v1|${effect.identity}',
+            effect.saveRecovery.record.writeToBuffer());
+      } else {
+        return refused('device identity effect has no operation');
+      }
+      return nomos_protocol.PeerEffectReceipt(
+        effectId: effect.effectId,
+        deviceIdentity: nomos_protocol.PeerDeviceIdentity(
+          secret: secret,
+          recovery: recovery,
+        ),
+      );
+    } catch (_) {
+      // Never print store exceptions: they may name the key path.
+      return refused(
+          'the platform device identity store could not ${effect.hasSave() ? 'save' : 'load'} the device identity');
+    }
+  }
+
+  Future<nomos_protocol.RuntimeResponse> driveCredentialEffects(
+    nomos_protocol.RuntimeRequest request,
+    Future<nomos_protocol.RuntimeResponse> Function(
+            nomos_protocol.RuntimeRequest)
+        invokeFrame,
+  ) async {
+    var next = request;
+    for (;;) {
+      final response = await invokeFrame(next);
+      if (response.requestId != request.requestId ||
+          response.protocolVersion != 2) {
+        throw StateError(
+            'Credential effect response belongs to another runtime request');
+      }
+      if (!response.hasCorrespondencePending() ||
+          (!response.correspondencePending.hasRefreshCredential() &&
+              !response.correspondencePending.hasDeviceIdentity() &&
+              !response.correspondencePending.hasLawPackage() &&
+              !response.correspondencePending.hasConsoleEnrolment() &&
+              !response.correspondencePending.hasWake())) return response;
+      final pending = response.correspondencePending;
+      final nomos_protocol.PeerEffectReceipt receipt;
+      if (pending.hasDeviceIdentity()) {
+        receipt = await performDeviceIdentityEffect(pending.deviceIdentity);
+      } else if (pending.hasLawPackage()) {
+        receipt = await performLawPackageEffect(pending.lawPackage);
+      } else if (pending.hasConsoleEnrolment()) {
+        receipt = await performConsoleEnrolment(pending.consoleEnrolment);
+      } else if (pending.hasWake()) {
+        // The shared runtime chooses the delay and checks its own clock.
+        // Waiting outside the serial Node frame lane keeps it available for
+        // credential-provider calls while authentication is pending.
+        await Future<void>.delayed(
+            Duration(milliseconds: pending.wake.delayMillis));
+        receipt = nomos_protocol.PeerEffectReceipt(
+          effectId: pending.wake.effectId,
+          woken: nomos_protocol.PeerWoken(),
+        );
+      } else {
+        receipt = await performCredentialRefresh(pending.refreshCredential);
+      }
+      next = nomos_protocol.RuntimeRequest(
+        protocolVersion: 2,
+        requestId: request.requestId,
+        continueCorrespondence: nomos_protocol.ContinueCorrespondenceRequest(
+          workId: pending.workId,
+          receipt: receipt,
+        ),
+      );
+    }
+  }
+
+  bool consumeCredentialRefreshEvent(
+    nomos_protocol.RuntimeEvent event,
+    NomosRuntimeV2Transport transport,
+    void Function(Object, StackTrace) onError,
+  ) {
+    if (!event.hasCredentialRefreshRequested()) return false;
+    final pending = event.credentialRefreshRequested.pending;
+    if (!pending.hasRefreshCredential()) {
+      throw StateError('Credential refresh event omitted its physical effect');
+    }
+    Future<void> complete() async {
+      final receipt = await performCredentialRefresh(pending.refreshCredential);
+      final response =
+          await transport.invokeRuntime(nomos_protocol.RuntimeRequest(
+        protocolVersion: 2,
+        requestId: fixnum.Int64(transport.nextRuntimeRequestId()),
+        continueCorrespondence: nomos_protocol.ContinueCorrespondenceRequest(
+          workId: pending.workId,
+          receipt: receipt,
+        ),
+      ));
+      if (response.hasFailure()) {
+        throw StateError(
+            '${response.failure.code}: ${response.failure.message}');
+      }
+    }
+
+    unawaited(complete().catchError(onError));
+    return true;
+  }
+}
+
 /// A level-triggered generated event stream. Runtime readiness can arrive while
-/// a WebView script is loading, before [NomosBridge] exists; a broadcast stream
+/// a WebView script is loading, before Reception exists; a broadcast stream
 /// would silently discard it and turn a successful boot into an infinite wait.
-/// Buffering ends when the first bridge subscribes, after which events remain a
+/// Buffering ends when Reception first subscribes, after which events remain a
 /// normal broadcast stream.
 final class NmsBufferedRuntimeEvents {
   NmsBufferedRuntimeEvents() {
@@ -83,12 +614,16 @@ mixin NomosRuntimeV2KernelCalls
     implements NomosRuntimeV2Transport, NomosKernelCallTransport {
   int _nmsRuntimeRequestSequence = 0;
 
+  @override
+  int nextRuntimeRequestId() => ++_nmsRuntimeRequestSequence;
+
   @override
   Future<nomos_protocol.CallResponse> callKernel({
     required String session,
     required nomos_protocol.CallRequest request,
+    required nomos_protocol.CredentialUse credentialUse,
   }) async {
-    final requestId = fixnum.Int64(++_nmsRuntimeRequestSequence);
+    final requestId = fixnum.Int64(nextRuntimeRequestId());
     final response = await invokeRuntime(
       nomos_protocol.RuntimeRequest(
         protocolVersion: 2,
@@ -96,6 +631,7 @@ mixin NomosRuntimeV2KernelCalls
         kernelCall: nomos_protocol.KernelCallRequest(
           session: session,
           request: request,
+          credentialUse: credentialUse,
         ),
       ),
     );
@@ -107,6 +643,11 @@ mixin NomosRuntimeV2KernelCalls
     if (response.hasFailure()) {
       throw StateError('${response.failure.code}: ${response.failure.message}');
     }
+    // Typed, as on the native transport: a copy still being fetched, opened or indexed is a
+    // retryable wait that reads sit out (replica_readiness.dart), never a bare error.
+    if (response.hasUnavailable()) {
+      throw NomosUnavailable.fromRuntime(response.unavailable);
+    }
     if (!response.hasKernelCall()) {
       throw StateError(
         'Runtime v2 returned ${response.whichOutcome().name} for a kernel call',