@githolon/dsl 0.117.0 → 0.119.9

package/dart/test/replica_readiness_test.dart

@@ -1,10 +1,16 @@
-// One-shot reads wait out a copy that is not ready yet; nothing else waits.
-import 'dart:async';
+// Reads answer at once from what is on this device; nothing waits for the network.
 import 'dart:io';
+import 'dart:typed_data';
 
 import 'package:nomos_client/src/replica_readiness.dart';
+import 'package:nomos_client/src/result_usda.dart' show NmsUsdaResult;
+import 'package:nomos_client/src/sync_status_projection.dart'
+    show LocalCopyReadiness;
 import 'package:nomos_types/nomos_types.dart'
     show NomosUnavailable, NomosUnavailableReason;
+import 'package:nomos_types/nomos_kernel_protocol.dart' as protocol;
+import 'package:nomos_types/src/proto/google/protobuf/any.pb.dart'
+    as google_protobuf;
 import 'package:test/test.dart';
 
 NomosUnavailable _unavailable(
@@ -15,135 +21,245 @@ NomosUnavailable _unavailable(
       reason: reason,
       workspace: 'catalogue-cars',
       retryable: retryable,
+      // A long hint: if anything still slept on it, the test would time out.
+      retryAfter: const Duration(minutes: 1),
     );
 
 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);
-  });
+  group('a one-shot read answers at once', () {
+    for (final (reason, readiness) in [
+      (
+        NomosUnavailableReason.localReplicaNotReady,
+        LocalCopyReadiness.arriving,
+      ),
+      (NomosUnavailableReason.workspaceOpening, LocalCopyReadiness.arriving),
+      (NomosUnavailableReason.readIndexRefreshing, LocalCopyReadiness.updating),
+    ]) {
+      test(
+        '${reason.name}: the empty answer and ${readiness.name}, asked once',
+        () async {
+          var reads = 0;
+          final reported = <LocalCopyReadiness>[];
+          final clock = Stopwatch()..start();
+          final rows = await nmsReadNow<List<String>>(
+            () async {
+              reads++;
+              throw _unavailable(reason);
+            },
+            pending: (_) => const [],
+            report: reported.add,
+          );
+          clock.stop();
+          expect(rows, isEmpty);
+          expect(reads, 1, reason: 'no retry');
+          expect(reported, [readiness]);
+          expect(clock.elapsedMilliseconds, lessThan(50));
+        },
+      );
+    }
 
-  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)),
+    test('a read that answers reports the copy ready', () async {
+      final reported = <LocalCopyReadiness>[];
+      final rows = await nmsReadNow<List<String>>(
+        () async => ['Hatchback'],
+        pending: (_) => const [],
+        report: reported.add,
       );
-      expect(reads, 1);
+      expect(rows, ['Hatchback']);
+      expect(reported, [LocalCopyReadiness.ready]);
     });
-  }
 
-  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>()),
+    test(
+      'a read with no empty form reports the typed answer at once',
+      () async {
+        var reads = 0;
+        final reported = <LocalCopyReadiness>[];
+        final notReady = _unavailable(
+          NomosUnavailableReason.localReplicaNotReady,
+        );
+        await expectLater(
+          nmsReadNow<List<String>>(
+            () async {
+              reads++;
+              throw notReady;
+            },
+            pending: (_) => null,
+            report: reported.add,
+          ),
+          throwsA(same(notReady)),
+        );
+        expect(reads, 1);
+        expect(reported, [LocalCopyReadiness.arriving]);
+      },
     );
+
+    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 and is not "pending"', () async {
+        var reads = 0;
+        final reported = <LocalCopyReadiness>[];
+        await expectLater(
+          nmsReadNow<void>(
+            () async {
+              reads++;
+              throw error;
+            },
+            pending: (_) => fail('not a pending copy'),
+            report: reported.add,
+          ),
+          throwsA(same(error)),
+        );
+        expect(reads, 1);
+        expect(reported, isEmpty);
+      });
+    }
   });
 
-  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),
+  group('the empty answer of a copy not readable here yet', () {
+    test(
+      'a declared rows query answers its own generated result type with no rows',
+      () {
+        final empty = nmsPendingQueryResponse(
+          protocol.QueryRequest(
+            resultFormat: protocol
+                .QueryResultFormat.QUERY_RESULT_FORMAT_APPLICATION_PROTOBUF,
+            rows: protocol.RowsQuery(
+              id: 'listingsByCatalogueId',
+              applicationArguments: google_protobuf.Any(
+                typeUrl:
+                    'type.nomos.dev/nomos.operation.v1.Query_3407d8ac4c444f26',
+                value: [10, 1, 120],
+              ),
+            ),
+          ),
+        )!;
+        expect(
+          empty.applicationResult.typeUrl,
+          'type.nomos.dev/nomos.operation.v1.QueryResult_3407d8ac4c444f26',
         );
+        expect(empty.applicationResult.value, isEmpty);
+      },
+    );
 
-    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');
+    test('a page of the same query is empty too', () {
+      final empty = nmsPendingQueryResponse(
+        protocol.QueryRequest(
+          resultFormat: protocol
+              .QueryResultFormat.QUERY_RESULT_FORMAT_APPLICATION_PROTOBUF,
+          page: protocol.PageQuery(
+            id: 'listingsByCatalogueId',
+            limit: 100,
+            applicationArguments: google_protobuf.Any(
+              typeUrl: 'type.nomos.dev/nomos.operation.v1.Query_abc',
+            ),
+          ),
+        ),
+      )!;
       expect(
-        await rows.timeout(const Duration(seconds: 1)),
-        ['Boiler'],
+        empty.applicationResult.typeUrl,
+        'type.nomos.dev/nomos.operation.v1.QueryResult_abc',
       );
-      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');
+    test(
+      'nominal by-id, by-type and spatial reads answer a result with no rows',
+      () {
+        for (final query in [
+          protocol.QueryRequest(
+            byId: protocol.ByIdQuery(aggregateType: 'a', aggregateId: 'b'),
+          ),
+          protocol.QueryRequest(
+            byType: protocol.ByTypeQuery(aggregateType: 'a'),
+          ),
+          protocol.QueryRequest(spatial: protocol.SpatialQuery()),
+        ]) {
+          query.resultFormat =
+              protocol.QueryResultFormat.QUERY_RESULT_FORMAT_NOMINAL_USDA;
+          final empty = nmsPendingQueryResponse(query)!;
+          final parsed = NmsUsdaResult.parse(
+            Uint8List.fromList(empty.resultUsda),
+          );
+          expect(parsed.rows, isEmpty, reason: query.whichQuery().name);
+          expect(parsed.done, isTrue);
         }
-        return ['Boiler'];
-      }, synced: synced.stream)
-          .timeout(const Duration(seconds: 1));
-      expect(rows, ['Boiler']);
-      await synced.close();
+      },
+    );
+
+    test('a count and a sum answer an exact zero', () {
+      for (final query in [
+        protocol.QueryRequest(count: protocol.TallyQuery(id: 'assets')),
+        protocol.QueryRequest(sum: protocol.TallyQuery(id: 'wattage')),
+      ]) {
+        final empty = nmsPendingQueryResponse(query)!;
+        expect(empty.hasIntegerValue(), isTrue);
+        expect(empty.integerValue.toInt(), 0);
+        final changed = nmsPendingWatchChanged(query, 'estate:watch:1')!;
+        expect(changed.hasIntegerValue(), isTrue);
+        expect(changed.subscriptionId, 'estate:watch:1');
+      }
+    });
+
+    test('a framework read has no empty form', () {
+      expect(
+        nmsPendingQueryResponse(
+          protocol.QueryRequest(
+            authenticationPosture: protocol.AuthenticationPostureQuery(),
+          ),
+        ),
+        isNull,
+      );
+      expect(
+        nmsPendingQueryResponse(
+          protocol.QueryRequest(
+            resultFormat: protocol
+                .QueryResultFormat.QUERY_RESULT_FORMAT_APPLICATION_PROTOBUF,
+            rows: protocol.RowsQuery(
+              applicationArguments: google_protobuf.Any(
+                typeUrl: 'type.nomos.dev/untyped',
+              ),
+            ),
+          ),
+        ),
+        isNull,
+        reason: 'only a generated Query_<sid> names its result type',
+      );
     });
   });
 
-  // 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. A site is where the
-  // request is BUILT (its requestId, or the historic request), never a trace line
-  // that merely names the same logical id (CAP-741's `call.send`), and "inside"
-  // means the readiness wait opens between the site's enclosing member and the
-  // site, however much tracing the closure carries.
-  test('every kernel query request is built inside nmsUntilReplicaReady', () {
-    final source = File(
-      'lib/src/reception/dart_reception.dart',
-    ).readAsLinesSync();
+  // The guard: every one-shot read reaches the kernel through one of these two request
+  // shapes. Each must sit inside nmsReadNow, so a new read path can neither wait for a copy
+  // nor hand callers a "not ready yet" as an error. A site is where the request is BUILT (its
+  // requestId, or the historic request), never a trace line that merely names the same logical
+  // id (CAP-741's `call.send`), and "inside" means the read opens between the site's enclosing
+  // member and the site, however much tracing the closure carries.
+  test('every kernel query request is built inside nmsReadNow', () {
+    final source =
+        File('lib/src/reception/dart_reception.dart').readAsLinesSync();
+    expect(
+      source.any((line) => line.contains('nmsUntilReplicaReady')),
+      isFalse,
+      reason: 'reads never wait for a copy to arrive',
+    );
     final member = RegExp(r'^  [A-Za-z_]');
     final requestSites = <int>[];
     for (var i = 0; i < source.length; i++) {
       final line = source[i];
       if ((line.contains('requestId:') && line.contains(r":query:$")) ||
           line.contains(
-              'historicQuery: nomos_protocol.HistoricQueryRequest(')) {
+            'historicQuery: nomos_protocol.HistoricQueryRequest(',
+          )) {
         requestSites.add(i);
       }
     }
@@ -154,12 +270,10 @@ void main() {
         start--;
       }
       expect(
-        source
-            .sublist(start, site)
-            .any((line) => line.contains('nmsUntilReplicaReady(')),
+        source.sublist(start, site).any((line) => line.contains('nmsReadNow')),
         isTrue,
         reason: 'dart_reception.dart:${site + 1} sends a kernel query outside '
-            'nmsUntilReplicaReady',
+            'nmsReadNow',
       );
     }
   });

package/dart/test/sync_status_reducer_test.dart

@@ -358,6 +358,45 @@ void main() {
         reason: 'a completed round never forgets the link state');
   });
 
+  test(
+      'while every workspace stays live, re-folding emits no new application status (CAP-930)',
+      () async {
+    final projection = NmsSyncStatusProjection();
+    addTearDown(projection.close);
+    final settled = reduce(protocol.SyncWorkspaceResponse(
+        previousHead: 'head', currentHead: 'head'));
+    final emitted = <SyncStatus>[];
+    final subscription = projection.applicationStream.listen(emitted.add);
+    addTearDown(subscription.cancel);
+    projection.pushSession('estate', settled.copyWith(live: true));
+    projection.pushSession('home', settled.copyWith(live: true));
+    projection.foldApplication(['estate', 'home']);
+    await Future<void>.delayed(Duration.zero);
+    expect(projection.applicationStatus.live, isTrue);
+    final becameLive = projection.applicationStatus.lastSyncedAt;
+    final before = emitted.length;
+    // Every incoming change re-reports the workspaces and re-folds the summary.
+    for (var i = 0; i < 20; i++) {
+      await Future<void>.delayed(const Duration(microseconds: 50));
+      projection.pushSession('estate', settled.copyWith(live: true));
+      projection.foldApplication(['estate', 'home']);
+    }
+    await Future<void>.delayed(Duration.zero);
+    expect(emitted.length, before,
+        reason: 'an unchanged live status is not a new status');
+    expect(projection.applicationStatus.lastSyncedAt, becameLive);
+    // Losing the link and regaining it is a new "current now".
+    projection.pushSession('estate', settled);
+    projection.foldApplication(['estate', 'home']);
+    expect(projection.applicationStatus.live, isFalse);
+    await Future<void>.delayed(const Duration(milliseconds: 2));
+    projection.pushSession('estate', settled.copyWith(live: true));
+    projection.foldApplication(['estate', 'home']);
+    expect(projection.applicationStatus.live, isTrue);
+    expect(projection.applicationStatus.lastSyncedAt!.isAfter(becameLive!),
+        isTrue);
+  });
+
   test(
       'the runtime follow inventory survives every re-fold of the application status',
       () async {

package/dart/test/typed_watch_registry_test.dart

@@ -1,4 +1,6 @@
 import 'dart:async';
+import 'package:nomos_client/src/sync_status_projection.dart'
+    show LocalCopyReadiness;
 import 'package:nomos_client/src/typed_watch_registry.dart';
 import 'package:nomos_types/nomos_kernel_protocol.dart' as protocol;
 import 'package:nomos_types/nomos_types.dart'
@@ -246,4 +248,71 @@ void main() {
     );
     await expectLater(watch.stream.first, throwsA(isA<NomosUnavailable>()));
   });
+
+  test(
+    'a copy not here yet: the empty answer at once, the copy reported arriving, never a wait',
+    () async {
+      final registry = NmsTypedWatchRegistry();
+      final reported = <LocalCopyReadiness>[];
+      final watch = registry.open(
+        session: 'catalogue',
+        decode: (event) => event.resultUsda,
+        pending: (id) => protocol.WatchChanged(subscriptionId: id),
+        report: reported.add,
+        start: (_) async => throw const NomosUnavailable(
+          reason: NomosUnavailableReason.localReplicaNotReady,
+          workspace: 'catalogue',
+          retryable: true,
+          retryAfter: Duration(minutes: 1),
+        ),
+        stop: (_) async {},
+      );
+      final clock = Stopwatch()..start();
+      expect(await watch.stream.first, isEmpty);
+      expect(clock.elapsedMilliseconds, lessThan(50));
+      expect(reported, [LocalCopyReadiness.arriving]);
+      await registry.close();
+    },
+  );
+
+  test(
+    'a registration the peer finished after answering "not ready" ends the re-asks',
+    () async {
+      final registry = NmsTypedWatchRegistry();
+      var starts = 0;
+      final reported = <LocalCopyReadiness>[];
+      late final String subscription;
+      final watch = registry.open(
+        session: 'catalogue',
+        decode: (event) => event.resultUsda,
+        pending: (id) => protocol.WatchChanged(subscriptionId: id),
+        report: reported.add,
+        start: (id) async {
+          subscription = id;
+          starts++;
+          throw const NomosUnavailable(
+            reason: NomosUnavailableReason.localReplicaNotReady,
+            workspace: 'catalogue',
+            retryable: true,
+            retryAfter: Duration(milliseconds: 20),
+          );
+        },
+        stop: (_) async {},
+      );
+      final values = StreamIterator(watch.stream);
+      expect(await values.moveNext(), isTrue);
+      expect(values.current, isEmpty);
+      // The peer completed the registration in the background and delivers its first result.
+      registry.deliver(
+        protocol.WatchChanged(subscriptionId: subscription, resultUsda: [7]),
+      );
+      expect(await values.moveNext(), isTrue);
+      expect(values.current, [7]);
+      await Future<void>.delayed(const Duration(milliseconds: 100));
+      expect(starts, 1, reason: 'a delivering watch is registered');
+      expect(reported, [LocalCopyReadiness.arriving, LocalCopyReadiness.ready]);
+      await values.cancel();
+      await registry.close();
+    },
+  );
 }