@githolon/dsl 0.117.0 → 0.119.9

package/dart/test/unshared_work_status_test.dart

@@ -0,0 +1,269 @@
+// Work a sync round leaves owed is never "in sync", until a round shows progress (CAP-923).
+//
+// Jack's iPad (TestFlight 1338, 11 Oct 2026 14:32 UTC): the Lippold estate's round ended
+// `deferred=1` with "Sharing is waiting for catalogue-0744 to become resident", the next round did
+// nothing (pulled nothing, head and bookmark unchanged, deferred=0), and the status went back to
+// in sync while the estate was 16 commits behind its server and the phone and iPad disagreed.
+import 'dart:async';
+
+import 'package:fixnum/fixnum.dart';
+
+import 'package:nomos_client/src/nms_generated_runtime.dart';
+import 'package:nomos_types/nomos_kernel_protocol.dart' as p;
+import 'package:test/test.dart';
+
+const _estate = 'estate-0fbc5c6a931205ae404d839df6ac9ff550b3ec82';
+const _ipadHead = '236fa9084f68a4baa0d00db5f8ae9587ca0d5d61';
+const _serverHead = 'cb90fef930fbf2310b62e8b5080ca4e70d7a616a';
+const _localEdit = '38865f0f65601093e3b0df6b56af383337f52d40';
+
+final class _Office
+    with NomosRuntimeV2KernelCalls
+    implements PeerOfficeConnection {
+  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.hasCloseRealm()) {
+      return p.RuntimeResponse(
+        protocolVersion: 2,
+        requestId: request.requestId,
+        realmClosed: p.RealmClosed(),
+      );
+    }
+    fail('Unexpected command: ${request.whichCommand()}');
+  }
+
+  void round(p.SyncWorkspaceResponse result) => events.add(
+        p.RuntimeEvent(
+          session: _estate,
+          syncCompleted: p.SyncCompleted(result: result),
+        ),
+      );
+
+  /// The 14:32:16 round: deferred on a dependency, the custodian's work not received.
+  void deferredRound({String head = _ipadHead, String tracked = _ipadHead}) =>
+      round(p.SyncWorkspaceResponse(
+        workspace: _estate,
+        previousHead: tracked,
+        currentHead: head,
+        deferred: Int64(1),
+        directOfferDeferred: true,
+        stillAhead: true,
+        reconnectRequired: true,
+        offerReceipt: p.CustodyOfferReceipt(
+          requestId: 'workspace-sync-9:dependency',
+          blocked: p.RuntimeBlocked(
+            kernelResidency: p.WorkspaceKernelResidencyRequired(
+              workspace: 'catalogue-0744dbfae089741266a9abfd9d86485bb6580a03',
+              detail: 'sync awaits catalogue-0744 state 51324b73',
+            ),
+          ),
+        ),
+      ));
+
+  /// The 14:32:34 round: nothing pulled, heads unchanged, nothing deferred.
+  void roundThatDidNothing(
+          {String head = _ipadHead, String tracked = _ipadHead}) =>
+      round(p.SyncWorkspaceResponse(
+        workspace: _estate,
+        previousHead: tracked,
+        currentHead: head,
+      ));
+}
+
+void main() {
+  late _Office office;
+  late DartReception reception;
+  late NomosSession session;
+
+  setUp(() {
+    office = _Office();
+    reception = DartReception(office);
+    session = reception.session(_estate);
+  });
+  tearDown(() async {
+    await reception.dispose();
+    await office.events.close();
+  });
+
+  test(
+      'the iPad sequence: a deferred round, then a round that did nothing, is still not in sync',
+      () {
+    office.roundThatDidNothing();
+    expect(session.currentStatus.phase, SyncPhase.idle);
+    expect(reception.currentStatus.unsharedWork, isEmpty);
+
+    office.deferredRound();
+    expect(reception.currentStatus.unsharedWork.keys, [_estate]);
+    final owed = reception.currentStatus.unsharedWork[_estate]!;
+    expect(owed.outbound, isFalse,
+        reason: 'local main == bookmark: the owed work is the server\'s');
+    expect(owed.detail, contains('catalogue-0744'));
+    final since = owed.since;
+
+    office.roundThatDidNothing();
+    expect(session.currentStatus.phase, isNot(SyncPhase.idle));
+    expect(reception.currentStatus.phase, isNot(SyncPhase.idle));
+    expect(reception.currentStatus.unsharedWork.keys, [_estate]);
+    expect(reception.currentStatus.unsharedWork[_estate]!.since, since,
+        reason: 'the first sighting is kept for the attention timer');
+    expect(session.currentStatus.unsharedWork.keys, [_estate]);
+  });
+
+  test('a round that receives the server\'s work clears it', () {
+    office.deferredRound();
+    office.round(p.SyncWorkspaceResponse(
+      workspace: _estate,
+      previousHead: _serverHead,
+      currentHead: _serverHead,
+      pulled: true,
+      mainAdvanced: true,
+    ));
+    expect(reception.currentStatus.unsharedWork, isEmpty);
+    expect(session.currentStatus.phase, SyncPhase.idle);
+  });
+
+  test(
+      'local changes not shared are outbound, and clear once the server admits them',
+      () {
+    office.deferredRound(head: _localEdit, tracked: _serverHead);
+    expect(reception.currentStatus.unsharedWork[_estate]!.outbound, isTrue);
+    office.roundThatDidNothing(head: _localEdit, tracked: _serverHead);
+    expect(reception.currentStatus.unsharedWork.keys, [_estate]);
+
+    office.round(p.SyncWorkspaceResponse(
+      workspace: _estate,
+      previousHead: _localEdit,
+      currentHead: _localEdit,
+      offerReceipt: p.CustodyOfferReceipt(
+        admission: p.CustodyOfferAdmissionReceipt(
+            main: _localEdit, sealedMain: _localEdit),
+      ),
+    ));
+    expect(reception.currentStatus.unsharedWork, isEmpty);
+    expect(session.currentStatus.phase, SyncPhase.idle);
+  });
+
+  test('admitted by the server but not yet sealed is not owed work', () {
+    office.round(p.SyncWorkspaceResponse(
+      workspace: _estate,
+      previousHead: _serverHead,
+      currentHead: _localEdit,
+      stillAhead: true,
+      offerReceipt: p.CustodyOfferReceipt(
+        admission: p.CustodyOfferAdmissionReceipt(main: _localEdit),
+      ),
+    ));
+    expect(reception.currentStatus.unsharedWork, isEmpty);
+  });
+
+  test('a refetch that replaced the copy clears owed work', () {
+    office.deferredRound();
+    office.round(p.SyncWorkspaceResponse(
+      workspace: _estate,
+      previousHead: _ipadHead,
+      currentHead: _ipadHead,
+      custodyReplaced: true,
+    ));
+    expect(reception.currentStatus.unsharedWork, isEmpty);
+  });
+
+  test(
+      'a round answered "the server is opening this workspace" owes nothing: a level workspace '
+      'is not left "not caught up" after the server restarts', () {
+    // Prod web, 12 Oct 2026: a tab loaded a minute after the cloud restarted. Four level
+    // workspaces' frontier probes were answered "opening"; their next rounds levelled over the
+    // stream and moved no head, and the popover said "haven't caught up - retrying" for ever.
+    office.round(p.SyncWorkspaceResponse(
+      workspace: _estate,
+      previousHead: _ipadHead,
+      currentHead: _ipadHead,
+      deferred: Int64(1),
+      directOfferDeferred: true,
+      custodianWarmingRetryAfterMillis: 2000,
+    ));
+    expect(reception.currentStatus.unsharedWork, isEmpty);
+    office.roundThatDidNothing();
+    expect(reception.currentStatus.unsharedWork, isEmpty);
+    expect(session.currentStatus.phase, SyncPhase.idle);
+  });
+
+  test('a warming round still owes local changes above the bookmark', () {
+    office.round(p.SyncWorkspaceResponse(
+      workspace: _estate,
+      previousHead: _serverHead,
+      currentHead: _localEdit,
+      stillAhead: true,
+      custodianWarmingRetryAfterMillis: 2000,
+    ));
+    expect(reception.currentStatus.unsharedWork[_estate]!.outbound, isTrue);
+  });
+
+  test(
+      'a level copy whose server has not sealed its main yet is not "not caught up"',
+      () {
+    // The round levelled over the stream at the head the copy holds; the server's seal of that
+    // main is still pending, so the round reports stillAhead with equal heads and no deferral.
+    office.round(p.SyncWorkspaceResponse(
+      workspace: _estate,
+      previousHead: _serverHead,
+      currentHead: _serverHead,
+      stillAhead: true,
+    ));
+    expect(reception.currentStatus.unsharedWork, isEmpty);
+    // The same heads with a deferral are still owed work (the iPad sequence).
+    office.deferredRound(head: _serverHead, tracked: _serverHead);
+    expect(reception.currentStatus.unsharedWork.keys, [_estate]);
+  });
+
+  test(
+      'a level round with nothing deferred clears an inbound record that no deferral set',
+      () {
+    // A round answered "another round is converging this workspace": no heads, nothing judged.
+    office.round(p.SyncWorkspaceResponse(
+      workspace: _estate,
+      stillAhead: true,
+      directOfferDeferred: true,
+    ));
+    expect(reception.currentStatus.unsharedWork[_estate]!.outbound, isFalse);
+    office.roundThatDidNothing();
+    expect(reception.currentStatus.unsharedWork, isEmpty);
+    expect(session.currentStatus.phase, SyncPhase.idle);
+
+    // The same at one head throughout: the record's heads never move, the level round clears it.
+    office.round(p.SyncWorkspaceResponse(
+      workspace: _estate,
+      previousHead: _ipadHead,
+      currentHead: _ipadHead,
+      stillAhead: true,
+      directOfferDeferred: true,
+    ));
+    expect(reception.currentStatus.unsharedWork.keys, [_estate]);
+    office.roundThatDidNothing();
+    expect(reception.currentStatus.unsharedWork, isEmpty);
+  });
+
+  test('a level round does not clear unshared local changes', () {
+    office.round(p.SyncWorkspaceResponse(
+      workspace: _estate,
+      previousHead: _serverHead,
+      currentHead: _localEdit,
+      stillAhead: true,
+    ));
+    expect(reception.currentStatus.unsharedWork[_estate]!.outbound, isTrue);
+    office.round(p.SyncWorkspaceResponse(
+      workspace: _estate,
+      previousHead: _serverHead,
+      currentHead: _localEdit,
+    ));
+    expect(reception.currentStatus.unsharedWork.keys, [_estate]);
+  });
+}

package/dart_types/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 0.15.2
+
+Add the shared kernel protocol fields for owned pack import continuations, cancellation and deferred admission.
+
+- Kernel protocol: `QueryRequest.serve_last_ready`, `QueryResponse.read_index_behind` (`ReadIndexBehind`) and `RUNTIME_UNAVAILABLE_REASON_READ_INDEX_REFRESHING_SUCCESSOR_LAW` (CAP-891).
+
+- `ReadIndexPending.lastReadyAbsent` and `LocalReadPending.heldReason` carry why a read is held for read maintenance (CAP-900).
+
+- `NomosUnavailableReason.readIndexRefreshing` types `RUNTIME_UNAVAILABLE_REASON_READ_INDEX_REFRESHING_SUCCESSOR_LAW`, which mapped to `unknown`. The generated Dart protocol bindings now carry the CAP-891 additions (`serve_last_ready`, `read_index_behind`, reason 8); they had not been regenerated (CAP-900).
+
+- `NomosUnavailableReason.firstDownload` types the new `RUNTIME_UNAVAILABLE_REASON_FIRST_DOWNLOAD` (CAP-913): this workspace has never been on this device and its first download is under way. A write to it is refused at once with this reason. It is distinct from `localReplicaNotReady`.
+
+- `PeerSocketObserved.rungWorkspaces` (CAP-931): the workspaces whose upstream rang, while the socket receipt was handled, for a main this copy does not hold. Each one's follow round is due now.
+
+## 0.15.1
+
+- `LiveFrontier.heldTrees`, `LiveCheckpointRequest.heldTrees`, `LiveCheckpointOffer.omittedTrees`/`sharedTrees` and `PeerStreamReceipt.omittedTrees` let a copy receive a checkpoint without the law closure it already holds (CAP-901).
+
 ## 0.15.0
 
 - `FollowObservationPhase.FOLLOW_OBSERVATION_PHASE_KERNEL_REFUSED`: this peer's kernel deterministically refused a replica follow's round, so the follow's sync is blocked and is not retrying.