@githolon/dsl 0.108.6 → 0.110.0

package/dart/test/reception_span_trace_test.dart

@@ -0,0 +1,23 @@
+import 'package:fixnum/fixnum.dart';
+import 'package:nomos_client/src/reception/progress_desk.dart';
+import 'package:nomos_types/nomos_kernel_protocol.dart' as protocol;
+import 'package:test/test.dart';
+
+void main() {
+  test('reception preserves the peer trace id and measured duration', () {
+    final span = protocol.RuntimeSpan(
+      traceId: List<int>.generate(16, (index) => index),
+      spanId: List<int>.filled(8, 1),
+      name: 'peer.correspondence.inspect-outbox',
+      startedUnixNanos: Int64(1700000000000000000),
+      durationNanos: Int64(22000000),
+    );
+
+    final observed = NomosSpanEvent.fromRuntime(span, session: 'home');
+
+    expect(observed.traceId, '000102030405060708090a0b0c0d0e0f');
+    expect(observed.startedAtMillis, 1700000000000);
+    expect(observed.endedAtMillis, 1700000000022);
+    expect(observed.session, 'home');
+  });
+}

package/dart/test/replica_readiness_test.dart

@@ -0,0 +1,156 @@
+// One-shot reads wait out a copy that is not ready yet; nothing else waits.
+import 'dart:async';
+import 'dart:io';
+
+import 'package:nomos_client/src/replica_readiness.dart';
+import 'package:nomos_types/nomos_types.dart'
+    show NomosUnavailable, NomosUnavailableReason;
+import 'package:test/test.dart';
+
+NomosUnavailable _unavailable(
+  NomosUnavailableReason reason, {
+  bool retryable = true,
+}) =>
+    NomosUnavailable(
+      reason: reason,
+      workspace: 'catalogue-cars',
+      retryable: retryable,
+    );
+
+void main() {
+  setUp(() {
+    nmsReplicaReadyFirstDelay = const Duration(milliseconds: 1);
+    nmsReplicaReadyGiveUpAfter = const Duration(minutes: 10);
+  });
+
+  test('a copy still arriving is asked again until it answers', () async {
+    var reads = 0;
+    final rows = await nmsUntilReplicaReady(() async {
+      reads++;
+      if (reads == 1) {
+        throw _unavailable(NomosUnavailableReason.workspaceOpening);
+      }
+      if (reads < 4) {
+        throw _unavailable(NomosUnavailableReason.localReplicaNotReady);
+      }
+      return ['Hatchback', 'Saloon'];
+    });
+    expect(rows, ['Hatchback', 'Saloon']);
+    expect(reads, 4);
+  });
+
+  for (final (label, error) in [
+    (
+      'a non-retryable unavailable answer',
+      _unavailable(NomosUnavailableReason.localReplicaNotReady,
+          retryable: false),
+    ),
+    (
+      'a remote-side unavailable answer',
+      _unavailable(NomosUnavailableReason.remoteUnreachable),
+    ),
+    ('any other error', StateError('NMS-KERNEL-CALL: query failed')),
+  ]) {
+    test('$label is reported at once', () async {
+      var reads = 0;
+      await expectLater(
+        nmsUntilReplicaReady<void>(() async {
+          reads++;
+          throw error;
+        }),
+        throwsA(same(error)),
+      );
+      expect(reads, 1);
+    });
+  }
+
+  test('a copy that never arrives still ends in an error', () async {
+    nmsReplicaReadyGiveUpAfter = const Duration(milliseconds: 20);
+    await expectLater(
+      nmsUntilReplicaReady<void>(
+        () async =>
+            throw _unavailable(NomosUnavailableReason.localReplicaNotReady),
+      ),
+      throwsA(isA<NomosUnavailable>()),
+    );
+  });
+
+  group('a completed sync wakes the wait', () {
+    // The runtime asks for a long pause; only the sync event can end it early.
+    NomosUnavailable notReady(String workspace) => NomosUnavailable(
+          reason: NomosUnavailableReason.localReplicaNotReady,
+          workspace: workspace,
+          retryable: true,
+          retryAfter: const Duration(minutes: 1),
+        );
+
+    test('the read asks again the moment its workspace syncs', () async {
+      final synced = StreamController<String>.broadcast();
+      final asked = Completer<void>();
+      var reads = 0;
+      final rows = nmsUntilReplicaReady(() async {
+        reads++;
+        if (!asked.isCompleted) asked.complete();
+        if (reads == 1) throw notReady('estate-a');
+        return ['Boiler'];
+      }, synced: synced.stream);
+      await asked.future;
+      await pumpEventQueue();
+      synced.add('estate-b');
+      await pumpEventQueue();
+      expect(reads, 1, reason: 'another workspace syncing is not this copy');
+      synced.add('estate-a');
+      expect(
+        await rows.timeout(const Duration(seconds: 1)),
+        ['Boiler'],
+      );
+      expect(reads, 2);
+      await synced.close();
+    });
+
+    test('a sync that lands before the wait begins is not missed', () async {
+      final synced = StreamController<String>.broadcast(sync: true);
+      var reads = 0;
+      final rows = await nmsUntilReplicaReady(() async {
+        reads++;
+        if (reads == 1) {
+          // The copy becomes ready while the "not yet" answer is in flight.
+          synced.add('estate-a');
+          throw notReady('estate-a');
+        }
+        return ['Boiler'];
+      }, synced: synced.stream)
+          .timeout(const Duration(seconds: 1));
+      expect(rows, ['Boiler']);
+      await synced.close();
+    });
+  });
+
+  // The guard: every one-shot read reaches the kernel through one of these two
+  // request shapes. Each must sit inside nmsUntilReplicaReady, so a new read
+  // path cannot hand callers a "not ready yet" as an error.
+  test('every kernel query request is built inside nmsUntilReplicaReady', () {
+    final source = File(
+      'lib/src/reception/dart_reception.dart',
+    ).readAsLinesSync();
+    final requestSites = <int>[];
+    for (var i = 0; i < source.length; i++) {
+      final line = source[i];
+      if (line.contains(r":query:$") ||
+          line.contains(
+              'historicQuery: nomos_protocol.HistoricQueryRequest(')) {
+        requestSites.add(i);
+      }
+    }
+    expect(requestSites, hasLength(2), reason: 'query request sites moved');
+    for (final site in requestSites) {
+      final window = source.sublist(site - 16 < 0 ? 0 : site - 16, site);
+      expect(
+        window.any((line) => line.contains('nmsUntilReplicaReady(')),
+        isTrue,
+        reason: 'dart_reception.dart:${site + 1} sends a kernel query outside '
+            'nmsUntilReplicaReady',
+      );
+    }
+  });
+}

package/dart/test/runtime_projections_test.dart

@@ -0,0 +1,92 @@
+import 'dart:async';
+
+import 'package:nomos_client/src/observed_session_directory.dart';
+import 'package:nomos_client/src/operation_receipts.dart';
+import 'package:nomos_client/src/sync_status_projection.dart';
+import 'package:nomos_client/src/typed_watch_registry.dart';
+import 'package:nomos_types/nomos_kernel_protocol.dart' as protocol;
+import 'package:test/test.dart';
+
+void main() {
+  test('observed session directory is a stable facade over successful opens',
+      () {
+    final directory = NmsObservedSessionDirectory<Object>();
+    final handle = Object();
+    directory.observeBound(
+      session: 'estate',
+      workspace: 'estate-1',
+      credentialCapability: 'device:jack',
+    );
+
+    expect(directory.isBound('estate'), isTrue);
+    expect(directory.workspaceFor('estate'), 'estate-1');
+    expect(directory.credentialCapabilityFor('estate'), 'device:jack');
+    expect(directory.handle('estate', () => handle), same(handle));
+    expect(directory.handle('estate', Object.new), same(handle));
+  });
+
+  test('sync projection folds typed per-session observations for the UI', () {
+    final projection = NmsSyncStatusProjection();
+    projection.ensureSession(
+      'home',
+      const SyncStatus(phase: SyncPhase.idle, behind: 0, saved: 2),
+    );
+    projection.ensureSession(
+      'estate',
+      const SyncStatus(phase: SyncPhase.behind, behind: 3, saved: 5),
+    );
+    projection.foldApplication(const ['home', 'estate']);
+
+    expect(projection.applicationStatus.phase, SyncPhase.behind);
+    expect(projection.applicationStatus.behind, 3);
+    expect(projection.applicationStatus.saved, 7);
+  });
+
+  test('operation receipts advance only from runtime-issued stable identities',
+      () async {
+    final projection = NmsOperationReceiptProjection();
+    final receipt = projection.register('estate', 'intent-1');
+    projection.advance(
+      'estate',
+      protocol.SyncWorkspaceResponse(admittedIntentIds: const ['intent-1']),
+    );
+    await receipt.admitted;
+    expect(receipt.current.phase, NomosOperationPhase.admittedToRemoteCustody);
+
+    projection.advance(
+      'estate',
+      protocol.SyncWorkspaceResponse(convergedIntentIds: const ['intent-1']),
+    );
+    await receipt.converged;
+    expect(receipt.current.phase, NomosOperationPhase.converged);
+  });
+
+  test('typed watch registry only correlates runtime events and cancellation',
+      () async {
+    final registry = NmsTypedWatchRegistry();
+    final stopped = <String>[];
+    final handle = registry.open<List<int>>(
+      session: 'estate',
+      decode: (event) => event.resultUsda,
+      start: (_) async {},
+      stop: (id) async => stopped.add(id),
+    );
+    final values = <List<int>>[];
+    final subscription = handle.stream.listen(values.add);
+
+    registry.deliver(
+      protocol.WatchChanged(
+        subscriptionId: handle.id,
+        resultUsda: const [1, 2, 3],
+      ),
+    );
+    await Future<void>.delayed(Duration.zero);
+    expect(values, const [
+      <int>[1, 2, 3]
+    ]);
+
+    await subscription.cancel();
+    expect(stopped, [handle.id]);
+    registry.close();
+  });
+}

package/dart/test/runtime_v2_gateway_test.dart

@@ -0,0 +1,131 @@
+import 'package:nomos_client/src/runtime_v2_gateway.dart';
+import 'package:nomos_client/src/runtime_v2_transport.dart';
+import 'package:nomos_types/nomos_kernel_protocol.dart' as protocol;
+import 'package:nomos_types/nomos_types.dart';
+import 'package:test/test.dart';
+
+final class _ScriptedRuntime implements NomosRuntimeV2Transport {
+  _ScriptedRuntime(this.answer);
+
+  final protocol.RuntimeResponse Function(protocol.RuntimeRequest request)
+      answer;
+  var _requestId = 0;
+
+  @override
+  int nextRuntimeRequestId() => ++_requestId;
+
+  @override
+  Future<protocol.RuntimeResponse> invokeRuntime(
+    protocol.RuntimeRequest request,
+  ) async =>
+      answer(request);
+}
+
+final class _ScriptedKernelCalls extends _ScriptedRuntime
+    with NomosRuntimeV2KernelCalls {
+  _ScriptedKernelCalls(super.answer);
+
+  @override
+  int nextRuntimeRequestId() => super.nextRuntimeRequestId();
+}
+
+void main() {
+  test('a kernel call on a copy not ready yet is the typed wait reads sit out',
+      () async {
+    // A fresh device's first read of a workspace it is still fetching (node, web and in-app
+    // transports): once a bare "Runtime v2 returned unavailable for a kernel call".
+    final runtime = _ScriptedKernelCalls(
+      (request) => protocol.RuntimeResponse(
+        protocolVersion: 2,
+        requestId: request.requestId,
+        unavailable: protocol.RuntimeUnavailable(
+          reason: protocol.RuntimeUnavailableReason
+              .RUNTIME_UNAVAILABLE_REASON_LOCAL_REPLICA_NOT_READY,
+          workspace: 'estate',
+          retryable: true,
+          retryAfterMillis: 250,
+          detail:
+              'placement requires a local replica which Replica Follow has not established yet',
+        ),
+      ),
+    );
+    await expectLater(
+      runtime.callKernel(
+        session: 'estate',
+        request: protocol.CallRequest(),
+        credentialUse: protocol.CredentialUse.CREDENTIAL_USE_SESSION,
+      ),
+      throwsA(
+        isA<NomosUnavailable>()
+            .having((value) => value.reason, 'reason',
+                NomosUnavailableReason.localReplicaNotReady)
+            .having((value) => value.workspace, 'workspace', 'estate')
+            .having((value) => value.retryable, 'retryable', true),
+      ),
+    );
+  });
+
+  test('unavailability is exhaustive application control state', () async {
+    final runtime = _ScriptedRuntime(
+      (request) => protocol.RuntimeResponse(
+        protocolVersion: 2,
+        requestId: request.requestId,
+        unavailable: protocol.RuntimeUnavailable(
+          reason: protocol.RuntimeUnavailableReason
+              .RUNTIME_UNAVAILABLE_REASON_REMOTE_ONLY_OFFLINE,
+          workspace: 'catalogue',
+          retryable: true,
+          retryAfterMillis: 1200,
+          detail: 'diagnostic text is not control flow',
+        ),
+      ),
+    );
+
+    await expectLater(
+      NmsRuntimeV2Gateway(runtime).invoke(protocol.RuntimeRequest()),
+      throwsA(
+        isA<NomosUnavailable>()
+            .having(
+              (value) => value.reason,
+              'reason',
+              NomosUnavailableReason.remoteOnlyOffline,
+            )
+            .having((value) => value.workspace, 'workspace', 'catalogue')
+            .having(
+              (value) => value.retryAfter,
+              'retryAfter',
+              const Duration(milliseconds: 1200),
+            ),
+      ),
+    );
+  });
+
+  test('policy refusal does not collapse into a string failure', () async {
+    final runtime = _ScriptedRuntime(
+      (request) => protocol.RuntimeResponse(
+        protocolVersion: 2,
+        requestId: request.requestId,
+        refused: protocol.RuntimeRefusal(
+          reason: protocol
+              .RuntimeRefusalReason.RUNTIME_REFUSAL_REASON_PLACEMENT_POLICY,
+          workspace: 'catalogue',
+          retryable: false,
+          detail: 'local residency is not permitted',
+        ),
+      ),
+    );
+
+    await expectLater(
+      NmsRuntimeV2Gateway(runtime).invoke(protocol.RuntimeRequest()),
+      throwsA(
+        isA<NomosRefused>()
+            .having(
+              (value) => value.reason,
+              'reason',
+              NomosRefusalReason.placementPolicy,
+            )
+            .having((value) => value.retryable, 'retryable', false),
+      ),
+    );
+  });
+}

package/dart/test/signing_identity_kernel_test.dart

@@ -0,0 +1,75 @@
+import 'dart:typed_data';
+
+import 'package:nomos_client/src/runtime_v2_transport.dart'
+    show NomosKernelCallTransport;
+import 'package:nomos_client/src/signing_identity_kernel.dart'
+    show NmsSigningIdentityKernel;
+import 'package:nomos_types/nomos_kernel_protocol.dart' as protocol;
+import 'package:test/test.dart';
+
+final class _KernelTransport implements NomosKernelCallTransport {
+  final List<protocol.CallRequest> requests = [];
+
+  @override
+  Future<protocol.CallResponse> callKernel({
+    required String session,
+    required protocol.CallRequest request,
+    protocol.CredentialUse credentialUse =
+        protocol.CredentialUse.CREDENTIAL_USE_UNSPECIFIED,
+  }) async {
+    expect(session, 'home-123');
+    expect(credentialUse, protocol.CredentialUse.CREDENTIAL_USE_NONE);
+    requests.add(request);
+    final signing = request.signingIdentity;
+    return switch (signing.whichOperation()) {
+      protocol.SigningIdentityRequest_Operation.generate =>
+        protocol.CallResponse(
+          protocolVersion: 1,
+          requestId: request.requestId,
+          signingIdentity: protocol.SigningIdentityResponse(
+            generated: protocol.SigningKeyPair(
+              secret: List<int>.filled(32, 7),
+              publicKey: List<int>.filled(32, 9),
+            ),
+          ),
+        ),
+      protocol.SigningIdentityRequest_Operation.derivePublic =>
+        protocol.CallResponse(
+          protocolVersion: 1,
+          requestId: request.requestId,
+          signingIdentity: protocol.SigningIdentityResponse(
+            derivedPublic: protocol.SigningPublicKey(
+              publicKey: List<int>.filled(32, 11),
+            ),
+          ),
+        ),
+      protocol.SigningIdentityRequest_Operation.notSet =>
+        throw StateError('missing signing operation'),
+    };
+  }
+}
+
+void main() {
+  test('signing identity crosses only the generated kernel contract', () async {
+    final transport = _KernelTransport();
+    final identity = NmsSigningIdentityKernel(
+      transport: transport,
+      session: 'home-123',
+    );
+
+    final generated = await identity.generate(requestId: 'generate-1');
+    expect(generated.secret, List<int>.filled(32, 7));
+    expect(generated.publicKey, List<int>.filled(32, 9));
+
+    final derived = await identity.derivePublic(
+      requestId: 'derive-1',
+      secret: Uint8List.fromList(List<int>.filled(32, 7)),
+    );
+    expect(derived.publicKey, List<int>.filled(32, 11));
+
+    expect(transport.requests, hasLength(2));
+    expect(transport.requests.first.hasSigningIdentity(), isTrue);
+    expect(transport.requests.last.signingIdentity.derivePublic.secret,
+        List<int>.filled(32, 7));
+  });
+}

package/dart/test/sync_status_preparation_report_test.dart

@@ -0,0 +1,29 @@
+import 'package:nomos_client/src/sync_status_projection.dart';
+import 'package:test/test.dart';
+
+void main() {
+  test(
+      'peer preparation reaches application status without a workspace session',
+      () async {
+    final projection = NmsSyncStatusProjection();
+    projection.updatePreparationCounts(1, 1,
+        activity: 'Installing workspace rules');
+    expect(projection.applicationStatus.preparingWorkspaces, 1);
+    expect(projection.applicationStatus.retryingWorkspaces, 1);
+    expect(projection.applicationStatus.preparationActivity,
+        'Installing workspace rules');
+
+    // Ordinary sync folding cannot erase the independently reported work.
+    projection.foldApplication(const []);
+    expect(projection.applicationStatus.preparingWorkspaces, 1);
+    expect(projection.applicationStatus.retryingWorkspaces, 1);
+    expect(projection.applicationStatus.preparationActivity,
+        'Installing workspace rules');
+
+    projection.updatePreparationCounts(0, 0);
+    expect(projection.applicationStatus.preparingWorkspaces, 0);
+    expect(projection.applicationStatus.retryingWorkspaces, 0);
+    expect(projection.applicationStatus.preparationActivity, isNull);
+    await projection.close();
+  });
+}