@githolon/dsl 0.117.1 → 0.119.9

package/dart/test/copy_repair_status_test.dart

@@ -0,0 +1,238 @@
+// A damaged local copy is "repairing" on its status, never "in sync".
+//
+// The device that set it: Jack's iPad mini (TestFlight 1338, 11 Oct 2026 14:28 UTC). The Lippold
+// estate's rounds "completed" (pullBytes=19641276 pulled=false mainAdvanced=false), while a separate
+// round failed `nomos.runtime.component_failure … commit b156478a… unreadable` and reads answered
+// localReplicaNotReady "local Git history is incomplete … being refetched". The status said every
+// workspace was in sync, and every edit failed.
+import 'dart:async';
+import 'dart:typed_data';
+
+import 'package:nomos_client/src/nms_generated_runtime.dart';
+import 'package:nomos_client/src/replica_readiness.dart';
+import 'package:nomos_client/src/sync_status_reducer.dart';
+import 'package:nomos_types/nomos_kernel_protocol.dart' as p;
+import 'package:nomos_types/src/proto/google/protobuf/any.pb.dart' as protobuf;
+import 'package:test/test.dart';
+
+const _workspace = 'estate-0fbc5c6a931205ae404d839df6ac9ff550b3ec82';
+const _missing = 'b156478a9512b1aa12e93ef513e0e3693c26d6db';
+const _resultType =
+    'type.nomos.dev/nomos.operation.v1.QueryResult_3407d8ac4c444f26';
+const _damagedDetail =
+    "the local copy of '$_workspace' cannot be read: local Git history is incomplete; "
+    'it is being refetched from its provider';
+
+final _query = NmsInternalGeneratedQueries.create(
+  domain: 'estate',
+  query: 'sitesByEstate',
+  protobufType: 'type.nomos.dev/nomos.operation.v1.Query_3407d8ac4c444f26',
+  protobufPayload: Uint8List.fromList([10, 1, 120]),
+);
+
+final class _Office
+    with NomosRuntimeV2KernelCalls
+    implements PeerOfficeConnection {
+  bool damaged = true;
+  final events = StreamController<p.RuntimeEvent>.broadcast(sync: true);
+  int sequence = 0;
+
+  @override
+  Stream<p.RuntimeEvent> get runtimeEvents => events.stream;
+
+  @override
+  int nextRuntimeRequestId() => ++sequence;
+
+  @override
+  Future<p.RuntimeResponse> invokeRuntime(p.RuntimeRequest request) async {
+    if (request.hasKernelCall() && request.kernelCall.request.hasQuery()) {
+      if (damaged) {
+        return p.RuntimeResponse(
+          protocolVersion: 2,
+          requestId: request.requestId,
+          unavailable: p.RuntimeUnavailable(
+            reason: p.RuntimeUnavailableReason
+                .RUNTIME_UNAVAILABLE_REASON_LOCAL_REPLICA_NOT_READY,
+            workspace: _workspace,
+            retryable: true,
+            retryAfterMillis: 1000,
+            detail: _damagedDetail,
+          ),
+        );
+      }
+      return p.RuntimeResponse(
+        protocolVersion: 2,
+        requestId: request.requestId,
+        kernelCall: p.CallResponse(
+          query: p.QueryResponse(
+            applicationResult: protobuf.Any(typeUrl: _resultType, value: [7]),
+          ),
+        ),
+      );
+    }
+    if (request.hasCloseRealm()) {
+      return p.RuntimeResponse(
+        protocolVersion: 2,
+        requestId: request.requestId,
+        realmClosed: p.RealmClosed(),
+      );
+    }
+    fail('Unexpected command: ${request.whichCommand()}');
+  }
+
+  /// The estate's round "completes": nothing pulled, head unchanged.
+  void roundCompletes() => events.add(
+        p.RuntimeEvent(
+          session: _workspace,
+          syncCompleted: p.SyncCompleted(
+            result: p.SyncWorkspaceResponse(
+              workspace: _workspace,
+              currentHead: '236fa9084f68a4baa0d00db5f8ae9587ca0d5d61',
+            ),
+          ),
+        ),
+      );
+
+  /// The separate failure, application-scoped as on the iPad.
+  void kernelCannotReadCommit() => events.add(
+        p.RuntimeEvent(
+          syncCompleted: p.SyncCompleted(
+            failure: p.RuntimeFailure(
+              code: 'nomos.runtime.component_failure',
+              message:
+                  'workspace-sync-12 workspace=$_workspace: NMS-KERNEL-CALL: commit $_missing '
+                  'unreadable: An object with id $_missing could not be found',
+            ),
+          ),
+        ),
+      );
+}
+
+void main() {
+  late _Office office;
+  late DartReception reception;
+  late NomosSession session;
+
+  setUp(() {
+    office = _Office();
+    reception = DartReception(office);
+    session = reception.session(_workspace);
+  });
+  tearDown(() async {
+    await reception.dispose();
+    await office.events.close();
+  });
+
+  test(
+    'the iPad sequence: a completed round, a commit the kernel cannot read and an incomplete-history '
+    'read leave the estate "repairing", and a later completed round does not undo it',
+    () async {
+      office.roundCompletes();
+      expect(session.currentStatus.localCopy, LocalCopyReadiness.ready);
+
+      office.kernelCannotReadCommit();
+      expect(session.currentStatus.localCopy, LocalCopyReadiness.repairing);
+      expect(reception.currentStatus.repairingCopies.keys, [_workspace]);
+      expect(session.currentStatus.repairingCopies.keys, [_workspace]);
+
+      await session.nmsQuery(_query);
+      expect(session.currentStatus.localCopy, LocalCopyReadiness.repairing);
+
+      // The next round "completes" over the same damaged copy: still repairing.
+      office.roundCompletes();
+      expect(session.currentStatus.localCopy, LocalCopyReadiness.repairing);
+      expect(reception.currentStatus.repairingCopies.keys, [_workspace]);
+
+      // Repaired: a read answers from the copy again.
+      office.damaged = false;
+      await session.nmsQuery(_query);
+      expect(session.currentStatus.localCopy, LocalCopyReadiness.ready);
+      expect(reception.currentStatus.repairingCopies, isEmpty);
+      expect(session.currentStatus.repairingCopies, isEmpty);
+    },
+  );
+
+  test('an incomplete-history read alone marks the copy repairing', () async {
+    await session.nmsQuery(_query);
+    expect(session.currentStatus.localCopy, LocalCopyReadiness.repairing);
+    expect(reception.currentStatus.repairingCopies, contains(_workspace));
+  });
+
+  test('a refetch that replaced the copy says it is repaired', () async {
+    office.kernelCannotReadCommit();
+    expect(reception.currentStatus.repairingCopies, contains(_workspace));
+    office.events.add(
+      p.RuntimeEvent(
+        session: _workspace,
+        syncCompleted: p.SyncCompleted(
+          result: p.SyncWorkspaceResponse(
+            workspace: _workspace,
+            currentHead: 'a' * 40,
+            custodyReplaced: true,
+          ),
+        ),
+      ),
+    );
+    expect(reception.currentStatus.repairingCopies, isEmpty);
+    expect(session.currentStatus.localCopy, LocalCopyReadiness.ready);
+  });
+
+  group('classification', () {
+    test('localReplicaNotReady with a damaged-copy reason is repairing', () {
+      expect(
+        nmsLocalCopyReadiness(
+          const NomosUnavailable(
+            reason: NomosUnavailableReason.localReplicaNotReady,
+            workspace: _workspace,
+            retryable: true,
+            detail: _damagedDetail,
+          ),
+        ),
+        LocalCopyReadiness.repairing,
+      );
+      expect(
+        nmsLocalCopyReadiness(
+          const NomosUnavailable(
+            reason: NomosUnavailableReason.localReplicaNotReady,
+            workspace: _workspace,
+            retryable: true,
+            detail: 'opening the workspace',
+          ),
+        ),
+        LocalCopyReadiness.arriving,
+      );
+    });
+
+    test('a round over a copy being refetched names the workspace', () {
+      expect(
+        nmsDamagedCopyOf(
+          p.SyncCompleted(
+            result: p.SyncWorkspaceResponse(
+              workspace: _workspace,
+              reconnectRequired: true,
+              discoveryError: p.RuntimeTransportFailure(
+                message: 'nomos.runtime.local_copy_refetching: unreadable',
+              ),
+            ),
+          ),
+        ),
+        _workspace,
+      );
+    });
+
+    test('an ordinary failure is not a damaged copy', () {
+      expect(
+        nmsDamagedCopyOf(
+          p.SyncCompleted(
+            failure: p.RuntimeFailure(
+              code: 'nomos.stream.timeout',
+              message: "'$_workspace' stream did not answer in time",
+              workspace: _workspace,
+            ),
+          ),
+        ),
+        isNull,
+      );
+    });
+  });
+}

package/dart/test/reads_never_wait_test.dart

@@ -0,0 +1,387 @@
+// Jack's rule (11 Oct 2026): the UI never waits on the network. Every read answers at once from
+// what is on this device; sync is a background effect.
+//
+// The device that set it: TestFlight 1334, 11 Oct 2026 10:07 UTC. In the Lippold catalogue panel a
+// read of data-profile-c6155961 (first fetch, previousHead=none) was held 11 s, until its download
+// finished, behind a full-panel spinner.
+import 'dart:async';
+import 'dart:typed_data';
+
+import 'package:nomos_client/src/application_status.dart';
+import 'package:nomos_client/src/nms_generated_runtime.dart';
+import 'package:nomos_types/nomos_kernel_protocol.dart' as p;
+import 'package:nomos_types/src/proto/google/protobuf/any.pb.dart' as protobuf;
+import 'package:test/test.dart';
+
+const _workspace = 'data-profile-c6155961aa5f0d41b7958269c5b9e957fe90b74d';
+const _resultType =
+    'type.nomos.dev/nomos.operation.v1.QueryResult_3407d8ac4c444f26';
+
+final _query = NmsInternalGeneratedQueries.create(
+  domain: 'data_profile',
+  query: 'fieldsByProfileId',
+  protobufType: 'type.nomos.dev/nomos.operation.v1.Query_3407d8ac4c444f26',
+  protobufPayload: Uint8List.fromList([10, 1, 120]),
+);
+
+/// The Peer Office as this device meets it: [copy] says what it holds of the workspace.
+enum _Copy {
+  absent,
+
+  /// Never on this device: the office answers FIRST_DOWNLOAD (Jack, 11 Oct 2026).
+  firstDownload,
+  refreshingUnderNewLaw,
+  servedFromLastReady,
+  here,
+}
+
+final class _Office
+    with NomosRuntimeV2KernelCalls
+    implements PeerOfficeConnection {
+  _Copy copy = _Copy.absent;
+  final events = StreamController<p.RuntimeEvent>.broadcast(sync: true);
+  final calls = <p.RuntimeRequest>[];
+  int sequence = 0;
+
+  @override
+  Stream<p.RuntimeEvent> get runtimeEvents => events.stream;
+
+  @override
+  int nextRuntimeRequestId() => ++sequence;
+
+  p.RuntimeResponse _unavailable(p.RuntimeRequest request) => p.RuntimeResponse(
+        protocolVersion: 2,
+        requestId: request.requestId,
+        unavailable: p.RuntimeUnavailable(
+          reason: switch (copy) {
+            _Copy.refreshingUnderNewLaw => p.RuntimeUnavailableReason
+                .RUNTIME_UNAVAILABLE_REASON_READ_INDEX_REFRESHING_SUCCESSOR_LAW,
+            _Copy.firstDownload => p.RuntimeUnavailableReason
+                .RUNTIME_UNAVAILABLE_REASON_FIRST_DOWNLOAD,
+            _ => p.RuntimeUnavailableReason
+                .RUNTIME_UNAVAILABLE_REASON_LOCAL_REPLICA_NOT_READY,
+          },
+          workspace: _workspace,
+          retryable: true,
+          // Long on purpose: only the workspace's sync may end a watch's pause.
+          retryAfterMillis: 60000,
+        ),
+      );
+
+  @override
+  Future<p.RuntimeResponse> invokeRuntime(p.RuntimeRequest request) async {
+    calls.add(request.deepCopy());
+    final response = p.RuntimeResponse(
+      protocolVersion: 2,
+      requestId: request.requestId,
+    );
+    if (request.hasKernelCall() && request.kernelCall.request.hasOffer()) {
+      // A write is judged only against a copy that is here (and ready for editing).
+      if (copy != _Copy.here) return _unavailable(request);
+      response.kernelCall = p.CallResponse(
+        offer: p.OfferResponse(
+          admitted: p.OfferAdmitted(head: 'a' * 40, intentId: 'intent-1'),
+        ),
+      );
+    } else if (request.hasKernelCall() &&
+        request.kernelCall.request.hasQuery()) {
+      if (copy == _Copy.absent ||
+          copy == _Copy.firstDownload ||
+          copy == _Copy.refreshingUnderNewLaw) {
+        return _unavailable(request);
+      }
+      final query = p.QueryResponse(
+        applicationResult: protobuf.Any(typeUrl: _resultType, value: [7, 8]),
+      );
+      if (copy == _Copy.servedFromLastReady) {
+        // CAP-891/900: answered from the last-ready index, the head's index owed in the
+        // background.
+        query.readIndexBehind = p.ReadIndexBehind(
+          workspace: _workspace,
+          servedFrontier: 'c966',
+          requestedFrontier: 'f7b7',
+        );
+      }
+      response.kernelCall = p.CallResponse(query: query);
+    } else if (request.hasWatch()) {
+      if (copy == _Copy.absent ||
+          copy == _Copy.firstDownload ||
+          copy == _Copy.refreshingUnderNewLaw) {
+        return _unavailable(request);
+      }
+      response.watchStarted = p.WatchStarted(
+        subscriptionId: request.watch.subscriptionId,
+      );
+    } else if (request.hasUnwatch()) {
+      response.watchStopped = p.WatchStopped(
+        subscriptionId: request.unwatch.subscriptionId,
+      );
+    } else if (request.hasCloseRealm()) {
+      response.realmClosed = p.RealmClosed();
+    } else {
+      fail('Unexpected command: ${request.whichCommand()}');
+    }
+    return response;
+  }
+
+  /// The copy's download landed: the office reports the sync round.
+  void synced() => events.add(
+        p.RuntimeEvent(
+          syncCompleted: p.SyncCompleted(
+            result: p.SyncWorkspaceResponse(workspace: _workspace),
+          ),
+        ),
+      );
+
+  void emit(p.WatchChanged changed) {
+    changed.subscriptionId =
+        calls.lastWhere((r) => r.hasWatch()).watch.subscriptionId;
+    events.add(p.RuntimeEvent(watchChanged: changed));
+  }
+
+  int get queries => calls
+      .where((r) => r.hasKernelCall() && r.kernelCall.request.hasQuery())
+      .length;
+  int get watches => calls.where((r) => r.hasWatch()).length;
+  int get offers => calls
+      .where((r) => r.hasKernelCall() && r.kernelCall.request.hasOffer())
+      .length;
+}
+
+List<int> _rows(NmsGeneratedResult result) {
+  expect(result.protobufType, _resultType);
+  return result.protobufPayload.toList();
+}
+
+void main() {
+  late _Office office;
+  late DartReception reception;
+  late NomosSession session;
+
+  setUp(() {
+    office = _Office();
+    reception = DartReception(office);
+    session = reception.session(_workspace);
+  });
+  tearDown(() async {
+    await reception.dispose();
+    await office.events.close();
+  });
+
+  test(
+    'a read of a never-fetched workspace answers empty and "arriving" at once, asked once',
+    () async {
+      final clock = Stopwatch()..start();
+      final result = await session.nmsQuery(_query);
+      clock.stop();
+      expect(
+        clock.elapsedMilliseconds,
+        lessThan(50),
+        reason: 'no wait, no retry',
+      );
+      expect(office.queries, 1);
+      expect(
+        _rows(result),
+        isEmpty,
+        reason: 'the generated result type, with no rows',
+      );
+      expect(session.currentStatus.localCopy, LocalCopyReadiness.arriving);
+
+      // The download lands in the background; the next read answers from the copy.
+      office.copy = _Copy.here;
+      office.synced();
+      expect(_rows(await session.nmsQuery(_query)), [7, 8]);
+      expect(session.currentStatus.localCopy, LocalCopyReadiness.ready);
+    },
+  );
+
+  test(
+    'a page, a by-id read and a count answer their empty forms at once',
+    () async {
+      final clock = Stopwatch()..start();
+      final page = await session.nmsQueryPage(_query);
+      final byId = await session.nmsQueryByIdUsda('catalogue.Catalogue', 'c1');
+      final count = await session.nmsCount('listingCount');
+      clock.stop();
+      expect(clock.elapsedMilliseconds, lessThan(50));
+      expect(page.protobufType, _resultType);
+      expect(page.protobufPayload, isEmpty);
+      expect(NmsUsdaResult.parse(byId).rows, isEmpty);
+      expect(count, 0);
+      expect(office.queries, 3);
+    },
+  );
+
+  test(
+    'a copy re-indexed under a law this app cannot decode answers empty and "updating" at once',
+    () async {
+      office.copy = _Copy.refreshingUnderNewLaw;
+      final clock = Stopwatch()..start();
+      final result = await session.nmsQuery(_query);
+      clock.stop();
+      expect(clock.elapsedMilliseconds, lessThan(50));
+      expect(_rows(result), isEmpty);
+      expect(office.queries, 1);
+      expect(session.currentStatus.localCopy, LocalCopyReadiness.updating);
+    },
+  );
+
+  test(
+    'a copy being re-indexed answers from its last-ready frontier, ready',
+    () async {
+      office.copy = _Copy.servedFromLastReady;
+      final clock = Stopwatch()..start();
+      final result = await session.nmsQuery(_query);
+      clock.stop();
+      expect(clock.elapsedMilliseconds, lessThan(50));
+      expect(_rows(result), [7, 8]);
+      expect(office.queries, 1);
+      expect(session.currentStatus.localCopy, LocalCopyReadiness.ready);
+    },
+  );
+
+  test(
+    'a watch emits empty and "arriving" at once, then the rows after the sync lands',
+    () async {
+      final statuses = <LocalCopyReadiness>[];
+      final statusSubscription = session.syncStatus
+          .map((status) => status.localCopy)
+          .distinct()
+          .listen(statuses.add);
+      final emissions = StreamIterator(
+        session.nmsWatchRows<int>(_query, decode: _rows, idOf: (row) => '$row'),
+      );
+
+      final clock = Stopwatch()..start();
+      expect(await emissions.moveNext(), isTrue);
+      clock.stop();
+      expect(clock.elapsedMilliseconds, lessThan(50));
+      expect(
+        emissions.current,
+        isEmpty,
+        reason: 'what is on the device: nothing',
+      );
+      expect(office.watches, 1);
+      expect(session.currentStatus.localCopy, LocalCopyReadiness.arriving);
+
+      // The download lands: the watch registers the moment the sync completes, not after its
+      // runtime-suggested minute.
+      office.copy = _Copy.here;
+      final next = emissions.moveNext();
+      office.synced();
+      await pumpEventQueue();
+      expect(office.watches, 2);
+      office.emit(
+        p.WatchChanged(
+          applicationResult: protobuf.Any(typeUrl: _resultType, value: [7, 8]),
+        ),
+      );
+      expect(await next.timeout(const Duration(seconds: 1)), isTrue);
+      expect(emissions.current, [7, 8]);
+      expect(session.currentStatus.localCopy, LocalCopyReadiness.ready);
+      await pumpEventQueue();
+      expect(statuses, [
+        LocalCopyReadiness.ready, // the session's status before any read
+        LocalCopyReadiness.arriving,
+        LocalCopyReadiness.ready,
+      ]);
+
+      await emissions.cancel();
+      await statusSubscription.cancel();
+    },
+  );
+
+  test(
+    'a watch on a copy that is here registers once and shows its rows',
+    () async {
+      office.copy = _Copy.here;
+      final emissions = StreamIterator(session.nmsWatch(_query));
+      final first = emissions.moveNext();
+      office.emit(
+        p.WatchChanged(
+          applicationResult: protobuf.Any(typeUrl: _resultType, value: [7]),
+        ),
+      );
+      expect(await first, isTrue);
+      expect(_rows(emissions.current), [7], reason: 'no empty emission first');
+      expect(office.watches, 1);
+      expect(session.currentStatus.localCopy, LocalCopyReadiness.ready);
+      await emissions.cancel();
+    },
+  );
+
+  test('cancelling a watch still waiting for its copy stops at once', () async {
+    final emissions = StreamIterator(session.nmsWatch(_query));
+    expect(await emissions.moveNext(), isTrue);
+    expect(_rows(emissions.current), isEmpty);
+    await emissions.cancel().timeout(const Duration(seconds: 1));
+    expect(office.watches, 1, reason: 'no re-registration after the cancel');
+  });
+
+  group(
+      'first download (Jack, 11 Oct 2026: one-time, explained, no awaiting-base outbox)',
+      () {
+    final write = NmsInternalGeneratedCalls.create(
+      domain: 'estate',
+      directive: 'createAsset',
+      protobufType: 'type.nomos.dev/nomos.operation.v1.Payload_create_asset',
+      protobufPayload: Uint8List.fromList([1]),
+    );
+
+    test('a read says "first download", not merely "arriving"', () async {
+      office.copy = _Copy.firstDownload;
+      final result = await session.nmsQuery(_query);
+      expect(_rows(result), isEmpty);
+      expect(
+        session.currentStatus.localCopy,
+        LocalCopyReadiness.firstDownload,
+      );
+      final status = ApplicationStatus(
+        phase: ApplicationStatusPhase.receiving,
+        localChanges: 0,
+        availableChanges: null,
+        savedChanges: null,
+        acceptedChanges: null,
+        decisionsNeeded: null,
+        localCopy: session.currentStatus.localCopy,
+      );
+      expect(status.localCopyFirstDownload, isTrue);
+      expect(status.localCopyArriving, isTrue, reason: 'CO2-1776 guards hold');
+    });
+
+    test(
+      'a write is refused at once with the typed reason, and admits once the copy is here',
+      () async {
+        office.copy = _Copy.firstDownload;
+        final clock = Stopwatch()..start();
+        await expectLater(
+          session.offerGeneratedCallOutcome(call: write),
+          throwsA(
+            isA<NomosUnavailable>()
+                .having((e) => e.reason, 'reason',
+                    NomosUnavailableReason.firstDownload)
+                .having((e) => e.retryable, 'retryable', isTrue)
+                .having((e) => e.workspace, 'workspace', _workspace),
+          ),
+        );
+        clock.stop();
+        expect(clock.elapsedMilliseconds, lessThan(100));
+        expect(office.offers, 1, reason: 'asked once: no hidden retry loop');
+
+        // The copy lands (its indexes being prepared): reads say "arriving", no longer "first".
+        office.copy = _Copy.absent;
+        await session.nmsQuery(_query);
+        expect(session.currentStatus.localCopy, LocalCopyReadiness.arriving);
+
+        // Ready: a read answers from the copy and the next write admits.
+        office.copy = _Copy.here;
+        office.synced();
+        await session.nmsQuery(_query);
+        expect(session.currentStatus.localCopy, LocalCopyReadiness.ready);
+        final admitted = await session.offerGeneratedCallOutcome(call: write);
+        expect(admitted.intentId, 'intent-1');
+        expect(office.offers, 2);
+      },
+    );
+  });
+}