@githolon/dsl 0.113.4 → 0.114.0

package/dart/lib/src/reception/dart_reception.dart

@@ -51,7 +51,8 @@ import '../generated_call.dart'
         NmsGeneratedCall,
         NmsGeneratedQuery,
         NmsGeneratedResult,
-        NmsInternalGeneratedResults;
+        NmsInternalGeneratedResults,
+        nmsGeneratedCallCreatedAt;
 import '../application_model_adoption.dart'
     show
         NmsApprovedModelLawPackageSource,
@@ -63,8 +64,10 @@ import '../application_model_adoption.dart'
 import '../application_framework_calls.dart'
     show OwnedCustody, OwnedDeviceRequest;
 import '../kernel_primitives.dart' show NmsKernelPrimitives;
+import '../nomos_trace.dart' show NomosTrace;
 import '../observed_session_directory.dart' show NmsObservedSessionDirectory;
 import '../replica_readiness.dart' show nmsUntilReplicaReady;
+import '../rows_watch.dart' show NmsRowsMerge, nmsMergeRows;
 import '../operation_receipts.dart'
     show NmsOperationReceiptProjection, NomosOperationReceipt;
 import 'event_desk.dart' show ReceptionEventDesk;
@@ -565,6 +568,17 @@ class NomosOwnedDeviceApprovalPreparation {
   });
 }
 
+/// Whether generated offers ask the kernel for its phase timings, which this
+/// reception prints as `[nomos-kernel-perf]` diagnostics. On by default in
+/// debug and profile builds. A release build leaves them off: carrying the spans
+/// costs the kernel, the Peer Office and this isolate work on every write that
+/// nobody reads. `--dart-define=NOMOS_KERNEL_SPANS=false` measures a profile
+/// build as a release user experiences it; `=true` restores them in release.
+const bool kNomosOfferKernelSpans = bool.fromEnvironment(
+  'NOMOS_KERNEL_SPANS',
+  defaultValue: !bool.fromEnvironment('dart.vm.product'),
+);
+
 /// The result of [DartReception.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.
 /// The proof material a generated offer presents to the kernel.
@@ -890,6 +904,15 @@ class DartReception {
       );
       return;
     }
+    if (event.hasReadAccessPreparation()) {
+      // The read itself still ends typed (rows, or NomosUnavailable with
+      // credentialUnavailable); this only says why it is taking a moment.
+      final preparation = event.readAccessPreparation;
+      // ignore: avoid_print
+      print('[nomos-read-access] enrolling this device to read '
+          'workspace=${preparation.workspace} request=${preparation.requestId}');
+      return;
+    }
     if (event.hasReady()) {
       final stale = _staleBundleError(event.ready.runtimeVersion);
       if (stale != null && !allowStaleRunnerBundle) {
@@ -946,6 +969,19 @@ class DartReception {
     if (event.hasLinkChanged()) {
       _eventPlane._events.publishSync(event);
       final session = event.hasSession() ? event.session : null;
+      if (NomosTrace.enabled && event.linkChanged.hasClosure()) {
+        // How the live connection ended (CAP-683): who closed it, how, and what it had carried.
+        final closure = event.linkChanged.closure;
+        NomosTrace.emit(
+            'dart',
+            'link.closed',
+            'ws=${closure.workspace} conn=${closure.connectionId} '
+                'by=${closure.socket.initiator.name} '
+                'code=${closure.socket.hasCode() ? closure.socket.code : '-'} '
+                'clean=${closure.socket.clean} openMs=${closure.openMillis} '
+                'admissions=${closure.admissions} '
+                'unanswered=${closure.unansweredBatches}');
+      }
       if (event.linkChanged.status ==
           nomos_protocol.LinkStatus.LINK_STATUS_CLOSED) {
         final closedAt = DateTime.now();
@@ -1692,7 +1728,6 @@ class DartReception {
   Future<NomosOfferOutcome> offerGeneratedCallOutcome({
     required NmsGeneratedCall call,
     String? actor,
-    String? domainHash,
     String? session,
     String? authorSecret,
     NomosBirthCertificate? birthCertificate,
@@ -1729,11 +1764,27 @@ class DartReception {
     // ignore: avoid_print
     print('[nomos-offer] dispatch ${call.domain}/${call.directive} in '
         '$workspace using ${authenticationProof.name}');
+    // Opt-in timeline (nomos_trace.dart): this call's id, and when the generated code made it.
+    final traceCall = NomosTrace.enabled ? NomosTrace.nextCall() : 0;
+    final traceBegin = NomosTrace.enabled ? NomosTrace.now() : 0;
+    if (NomosTrace.enabled) {
+      final created = nmsGeneratedCallCreatedAt(call);
+      NomosTrace.emit(
+          'dart',
+          'call.begin',
+          'c=$traceCall op=offer:${call.domain}/${call.directive} '
+              'sinceCreateUs=${created == 0 ? -1 : traceBegin - created}');
+    }
     Future<nomos_protocol.CallResponse> attempt() async {
       final requestNumber = ++plane._sequences.request;
       final requestId = '$runtimeSession:offer:$requestNumber';
       final observer = NomosWrite.captureObserver();
       if (observer != null) plane._writeObservers[requestId] = observer;
+      final sent = NomosTrace.enabled ? NomosTrace.now() : 0;
+      if (NomosTrace.enabled) {
+        NomosTrace.emit('dart', 'call.send',
+            'c=$traceCall lr=$requestId sinceBeginUs=${sent - traceBegin}');
+      }
       try {
         return await kernelTransport.callKernel(
           session: runtimeSession,
@@ -1758,9 +1809,8 @@ class DartReception {
                     ? const <int>[]
                     : base64Decode(explicitSecret),
                 deferProjection: true,
-                spans: true,
+                spans: kNomosOfferKernelSpans,
               ),
-              controllerLawHash: domainHash,
               conflictSnapshots: conflictSnapshots,
               birthCertificate: birthCertificate,
             ),
@@ -1770,6 +1820,10 @@ class DartReception {
       } finally {
         plane._writeObservers.remove(requestId);
         observer?.call(const NomosWriteProgress(NomosWritePhase.running));
+        if (NomosTrace.enabled) {
+          NomosTrace.emit('dart', 'call.reply',
+              'c=$traceCall lr=$requestId us=${NomosTrace.now() - sent}');
+        }
       }
     }
 
@@ -1791,6 +1845,10 @@ class DartReception {
       response = await attempt();
     }
     if (response.hasFailure()) {
+      if (NomosTrace.enabled) {
+        NomosTrace.emit('dart', 'call.end',
+            'c=$traceCall outcome=failure us=${NomosTrace.now() - traceBegin}');
+      }
       // ignore: avoid_print
       print('[nomos-offer] refused ${call.domain}/${call.directive} in '
           '$workspace: ${response.failure.code}: ${response.failure.message}');
@@ -1850,6 +1908,10 @@ class DartReception {
     for (final child in born) {
       plane._receipts.rememberBirth(child, receipt);
     }
+    if (NomosTrace.enabled) {
+      NomosTrace.emit('dart', 'call.end',
+          'c=$traceCall outcome=admitted us=${NomosTrace.now() - traceBegin}');
+    }
     return NomosOfferOutcome(
       head: admitted.head,
       intentId: admitted.intentId,
@@ -2550,9 +2612,22 @@ class DartReception {
     // overlapping logical request identities despite sharing one executor.
     // A copy still being fetched or opened answers "not ready yet": ask again
     // rather than hand every caller a state that passes by itself.
+    final traceCall = NomosTrace.enabled ? NomosTrace.nextCall() : 0;
+    final traceBegin = NomosTrace.enabled ? NomosTrace.now() : 0;
+    if (NomosTrace.enabled) {
+      NomosTrace.emit('dart', 'call.begin',
+          'c=$traceCall op=${NomosTrace.describeCall(nomos_protocol.CallRequest(query: query))}');
+    }
     final response = await nmsUntilReplicaReady(
       () {
         final requestNumber = ++plane._sequences.request;
+        if (NomosTrace.enabled) {
+          NomosTrace.emit(
+              'dart',
+              'call.send',
+              'c=$traceCall lr=$runtimeSession:query:$requestNumber '
+                  'sinceBeginUs=${NomosTrace.now() - traceBegin}');
+        }
         return (transport as NomosKernelCallTransport).callKernel(
           session: runtimeSession,
           // An explicit device key is an additional proof, not a replacement for
@@ -2569,6 +2644,13 @@ class DartReception {
       },
       synced: _eventPlane._events.workspacesSynced,
     );
+    if (NomosTrace.enabled) {
+      NomosTrace.emit(
+          'dart',
+          'call.end',
+          'c=$traceCall outcome=${response.whichOutcome().name} '
+              'us=${NomosTrace.now() - traceBegin}');
+    }
     if (response.hasFailure()) {
       throw StateError('${response.failure.code}: ${response.failure.message}');
     }
@@ -2664,10 +2746,16 @@ class DartReception {
       birthEvidence: posture.birthEvidence.status,
       birthEvidenceDetail: posture.birthEvidence.detail,
     );
+    // An enrolled device proves its principal with its own key and carries no
+    // provider token by design (D22): name that, rather than `missingToken`
+    // and `unresolved`, which read like a fault.
+    final tokenless = result.enrolledDevice &&
+        result.providerToken == NomosProviderTokenVerification.missingToken;
     print(
         '[nomos-auth-posture] workspace=${_eventPlane._sessions.workspaceFor(session ?? _sessionName ?? '')} '
-        'token=${result.providerToken.name} enrolled=${result.enrolledDevice} '
-        'principal=${result.resolvedPrincipal.isEmpty ? 'unresolved' : 'resolved'}');
+        'token=${tokenless ? 'notCarried(enrolledDevice)' : result.providerToken.name} '
+        'enrolled=${result.enrolledDevice} '
+        'principal=${result.resolvedPrincipal.isNotEmpty ? 'resolved' : tokenless ? 'byDeviceSigner' : 'unresolved'}');
     return result;
   }
 
@@ -2676,16 +2764,15 @@ class DartReception {
   /// must already be bound to the principal's receiving-group workspace. The
   /// shared desk owns whatever placement, identity and birth work the operation
   /// requires. Its convergence tail runs as background correspondence and reports on
-  /// [receivingGroupConvergence]. [contract] is the application's law identity
-  /// from the compiled descriptor; tenant seed steps are law, never carried
-  /// here. A typed refusal surfaces as a [NomosRuntimeError] carrying the
+  /// [receivingGroupConvergence]. The Home is born under the law its platform
+  /// serves, which the desk observes at birth; tenant seed steps are law, never
+  /// carried here. A typed refusal surfaces as a [NomosRuntimeError] carrying the
   /// desk's own code (`nomos.runtime.receiving_group_*`).
   @internal
   Future<nomos_protocol.ReceivingGroupOpened> nmsOpenReceivingGroup({
     required String application,
     required String principal,
     required String authToken,
-    required nomos_protocol.ApplicationBirthContract contract,
     bool verifyHistory = false,
     String? session,
     nomos_protocol.ConsoleEnrolmentRoute? enrolment,
@@ -2697,7 +2784,6 @@ class DartReception {
           application: application,
           principal: principal,
           authToken: utf8.encode(authToken),
-          contract: contract,
           verifyHistory: verifyHistory,
           enrolment: enrolment,
         ),
@@ -2954,6 +3040,51 @@ class DartReception {
         intervalMs: intervalMs,
       );
 
+  /// Reactive rows of a declared query, kept current by kernel deltas (CAP-731).
+  ///
+  /// The watch opts into row deltas: after its first complete result, each
+  /// local frontier advance delivers only the rows that changed (decoded with
+  /// the same generated [decode]) and the ids that left. The rows are merged
+  /// by [idOf] in the kernel's id order; a row the change did not touch keeps
+  /// its identity, and nothing is emitted when nothing changed. A delta that
+  /// does not start at this watch's position ends the stream with
+  /// [NomosWatchPositionMismatch].
+  Stream<List<T>> nmsWatchRows<T>(
+    NmsGeneratedQuery query, {
+    required List<T> Function(NmsGeneratedResult result) decode,
+    required String Function(T row) idOf,
+    List<NomosScopeKey>? keys,
+    String? principal,
+    String? session,
+    int intervalMs = _defaultWatchSafetyPollMs,
+  }) =>
+      NomosTrace.timedListener(
+          nmsMergeRows(
+            _nmsWatchQuery<nomos_protocol.WatchChanged>(
+              nomos_protocol.QueryRequest(
+                rows: nomos_protocol.RowsQuery(
+                  id: query.query,
+                  principal: principal ?? '',
+                  applicationArguments: google_protobuf.Any(
+                    typeUrl: query.protobufType,
+                    value: query.protobufPayload,
+                  ),
+                ),
+              ),
+              resultFormat: nomos_protocol
+                  .QueryResultFormat.QUERY_RESULT_FORMAT_APPLICATION_PROTOBUF,
+              decode: (changed) => changed,
+              acceptRowDelta: true,
+              keys: keys,
+              principal: principal,
+              session: session,
+              intervalMs: intervalMs,
+            ),
+            NmsRowsMerge<T>(decode: decode, idOf: idOf),
+          ),
+          // The application's own listener time per emission (the inner watch's is the merge).
+          'q=query:rows:${query.query} stage=app');
+
   /// Reactive form of [nmsQueryUsda]. Subscription mechanics are Runtime v2
   /// protobuf; each emission is the kernel's nominal USDA result and is decoded
   /// only by the generated domain client which owns [query].
@@ -3054,6 +3185,7 @@ class DartReception {
     nomos_protocol.QueryRequest request, {
     required nomos_protocol.QueryResultFormat resultFormat,
     required T Function(nomos_protocol.WatchChanged) decode,
+    bool acceptRowDelta = false,
     List<NomosScopeKey>? keys,
     String? principal,
     String? session,
@@ -3070,6 +3202,9 @@ class DartReception {
       ..resultFormat = resultFormat;
     final NmsTypedWatchHandle<T> watch = plane._events.typedWatches.open<T>(
       session: runtimeSession,
+      label: NomosTrace.enabled
+          ? NomosTrace.describeCall(nomos_protocol.CallRequest(query: request))
+          : '',
       decode: decode,
       stop: _unwatch,
       start: (subscriptionId) async {
@@ -3081,6 +3216,7 @@ class DartReception {
               kind: nomos_protocol.WatchKind.WATCH_KIND_QUERY,
               query: request,
               intervalMillis: intervalMs,
+              acceptRowDelta: acceptRowDelta,
             ),
           ),
         );
@@ -4160,6 +4296,7 @@ class NomosSession extends DartReception {
         adoptApplicationModel: nomos_protocol.AdoptApplicationModelRequest(
           session: workspace,
           lawSha256: model.lawSha256,
+          unitSet: model.unitSet,
           domainKeys: model.domainKeys,
           acceptanceReason: model.reason,
           dryRun: dryRun,