@githolon/dsl 0.108.7 → 0.110.0

package/dart/test/platform_credential_effect_test.dart

@@ -0,0 +1,386 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:typed_data';
+
+import 'package:fixnum/fixnum.dart';
+import 'package:crypto/crypto.dart' show sha256;
+import 'package:nomos_client/src/runtime_v2_transport.dart';
+import 'package:nomos_peer_host/nomos_peer_host.dart'
+    show NomosDeviceIdentityStore, NomosProviderCredentialStore;
+import 'package:nomos_types/nomos_kernel_protocol.dart' as p;
+import 'package:test/test.dart';
+
+class _Platform
+    with NmsPlatformCredentialProviderHost
+    implements NomosRuntimeV2Transport {
+  final requests = <p.RuntimeRequest>[];
+  int sequence = 40;
+  @override
+  int nextRuntimeRequestId() => ++sequence;
+  @override
+  Future<p.RuntimeResponse> invokeRuntime(p.RuntimeRequest request) async {
+    requests.add(request);
+    return p.RuntimeResponse(
+        protocolVersion: 2,
+        requestId: request.requestId,
+        credentialsRefreshed: p.CredentialsRefreshed(session: 'home'));
+  }
+}
+
+p.CorrespondencePending pending() => p.CorrespondencePending(
+    workId: 'work',
+    refreshCredential: p.PeerCredentialRefreshEffect(
+        effectId: 'effect', capability: 'opaque-capability'));
+
+class _MemoryIdentityStore implements NomosDeviceIdentityStore {
+  final Map<String, Uint8List> saved = {};
+  final List<String> log = [];
+  @override
+  Future<Uint8List?> load(String identity) async {
+    log.add('load:$identity');
+    return saved[identity];
+  }
+
+  @override
+  Future<void> save(String identity, Uint8List secret) async {
+    log.add('save:$identity');
+    saved[identity] = Uint8List.fromList(secret);
+  }
+}
+
+class _MemoryProviderCredentialStore implements NomosProviderCredentialStore {
+  final Map<String, List<String>> saved = {};
+
+  @override
+  Future<List<String>> loadCandidates(String entry) async =>
+      List<String>.from(saved[entry] ?? const []);
+
+  @override
+  Future<void> retainCandidate(String entry, String authToken) async {
+    final existing = saved[entry] ?? const [];
+    saved[entry] = [
+      authToken,
+      ...existing.where((candidate) => candidate != authToken),
+    ].take(4).toList(growable: false);
+  }
+}
+
+Uint8List secretOf(String label) => Uint8List.fromList(List<int>.generate(
+    32, (i) => (label.codeUnitAt(i % label.length) ^ i) & 0xff));
+
+p.PeerDeviceIdentityEffect loadEffect() => p.PeerDeviceIdentityEffect(
+    effectId: 'identity:load',
+    identity: 'co2|user:ada',
+    load: p.PeerDeviceIdentityLoad());
+
+void main() {
+  test(
+      'secure recovery journal round-trips separately from the active identity',
+      () async {
+    final platform = _Platform();
+    final store = _MemoryIdentityStore();
+    platform.registerDeviceIdentityStore(store);
+    const identity = 'independent-app|user:ada';
+    final old = secretOf('old');
+    final candidate = secretOf('new');
+    store.saved[identity] = old;
+    final record = p.DeviceRecoveryRecord(
+        version: 1,
+        application: 'independent-app',
+        principal: 'user:ada',
+        previousSecret: old,
+        candidateSecret: candidate);
+    final saved = await platform.performDeviceIdentityEffect(
+        p.PeerDeviceIdentityEffect(
+            effectId: 'save-recovery',
+            identity: identity,
+            saveRecovery: p.PeerDeviceRecoverySave(record: record)));
+    expect(saved.hasDeviceIdentity(), isTrue);
+    expect(store.saved[identity], old, reason: 'staging is not activation');
+    final loaded = await platform.performDeviceIdentityEffect(
+        p.PeerDeviceIdentityEffect(
+            effectId: 'load-recovery',
+            identity: identity,
+            loadRecovery: p.PeerDeviceRecoveryLoad()));
+    expect(loaded.deviceIdentity.hasSecret(), isFalse);
+    expect(loaded.deviceIdentity.recovery, record);
+    store.saved['nomos-device-recovery-v1|$identity'] =
+        Uint8List.fromList([255]);
+    final corrupt = await platform.performDeviceIdentityEffect(
+        p.PeerDeviceIdentityEffect(
+            effectId: 'load-corrupt',
+            identity: identity,
+            loadRecovery: p.PeerDeviceRecoveryLoad()));
+    expect(corrupt.hasFailure(), isTrue);
+    expect(store.saved[identity], old);
+    store.saved[identity] = Uint8List(0);
+    final empty = await platform.performDeviceIdentityEffect(
+        p.PeerDeviceIdentityEffect(
+            effectId: 'empty',
+            identity: identity,
+            load: p.PeerDeviceIdentityLoad()));
+    expect(empty.hasFailure(), isTrue,
+        reason: 'present corruption must not cross protobuf as a missing key');
+    expect(empty.failure.message, contains('malformed'));
+  });
+
+  test('a readiness wake leaves the transport available for another request',
+      () async {
+    final platform = _Platform();
+    var frames = 0;
+    final waiting = platform.driveCredentialEffects(
+        p.RuntimeRequest(protocolVersion: 2, requestId: Int64(7)),
+        (request) async {
+      frames++;
+      if (frames == 1)
+        return p.RuntimeResponse(
+            protocolVersion: 2,
+            requestId: request.requestId,
+            correspondencePending: p.CorrespondencePending(
+                workId: 'wait',
+                wake: p.PeerWakeEffect(effectId: 'wake', delayMillis: 10)));
+      expect(request.continueCorrespondence.receipt.hasWoken(), isTrue);
+      expect(request.continueCorrespondence.receipt.effectId, 'wake');
+      expect(platform.requests, hasLength(1));
+      return p.RuntimeResponse(
+          protocolVersion: 2,
+          requestId: request.requestId,
+          authenticationReadiness: p.AuthenticationReadiness());
+    });
+    await platform.invokeRuntime(
+        p.RuntimeRequest(protocolVersion: 2, requestId: Int64(8)));
+    expect((await waiting).hasAuthenticationReadiness(), isTrue);
+    expect(frames, 2);
+  });
+
+  test('foreground carries capability proof and continues the same request',
+      () async {
+    final platform = _Platform();
+    var calls = 0;
+    platform.registerCredentialProvider(
+        capability: 'opaque-capability',
+        cloud: 'https://example.test',
+        signIn: ({deviceChallenge}) async {
+          calls++;
+          return ' fresh-proof ';
+        });
+    platform.registerCredentialProvider(
+        capability: 'different',
+        cloud: 'https://example.test',
+        signIn: ({deviceChallenge}) async =>
+            throw StateError('wrong provider'));
+    final initial = p.RuntimeRequest(protocolVersion: 2, requestId: Int64(7));
+    var frames = 0;
+    final result =
+        await platform.driveCredentialEffects(initial, (request) async {
+      frames++;
+      expect(request.requestId, Int64(7));
+      if (frames == 1)
+        return p.RuntimeResponse(
+            protocolVersion: 2,
+            requestId: request.requestId,
+            correspondencePending: pending());
+      expect(request.continueCorrespondence.workId, 'work');
+      final receipt = request.continueCorrespondence.receipt;
+      expect(receipt.effectId, 'effect');
+      expect(utf8.decode(receipt.credentialRefreshed.authToken), 'fresh-proof');
+      return p.RuntimeResponse(
+          protocolVersion: 2,
+          requestId: request.requestId,
+          kernelCall: p.CallResponse());
+    });
+    expect(result.hasKernelCall(), isTrue);
+    expect(frames, 2);
+    expect(calls, 1);
+  });
+
+  test(
+      'native-style durable credentials survive restart and a rejected token falls back through the rolling set',
+      () async {
+    final durable = _MemoryProviderCredentialStore();
+    final first = _Platform()..registerProviderCredentialStore(durable);
+    final issued = ['old-proof', 'new-proof'];
+    first.registerCredentialProvider(
+        capability: 'opaque-capability',
+        cloud: 'https://provider-a.example',
+        signIn: ({deviceChallenge}) async => issued.removeAt(0));
+    for (var i = 0; i < 2; i += 1) {
+      final receipt = await first.performCredentialRefresh(
+          p.PeerCredentialRefreshEffect(
+              effectId: 'online-$i', capability: 'opaque-capability'));
+      expect(receipt.hasCredentialRefreshed(), isTrue);
+    }
+
+    var providerCalls = 0;
+    final restarted = _Platform()..registerProviderCredentialStore(durable);
+    restarted.registerCredentialProvider(
+        capability: 'opaque-capability',
+        cloud: 'https://provider-a.example',
+        signIn: ({deviceChallenge}) async {
+          providerCalls += 1;
+          return 'network-proof';
+        });
+    var receipt = await restarted.performCredentialRefresh(
+        p.PeerCredentialRefreshEffect(
+            effectId: 'restart',
+            capability: 'opaque-capability',
+            allowCached: true));
+    expect(utf8.decode(receipt.credentialRefreshed.authToken), 'new-proof');
+    expect(providerCalls, 0,
+        reason: 'a process restart must not require Firebase');
+
+    receipt = await restarted.performCredentialRefresh(
+        p.PeerCredentialRefreshEffect(
+            effectId: 'rejected',
+            capability: 'opaque-capability',
+            allowCached: true,
+            rejectedAuthTokenSha256: Uint8List.fromList(
+                sha256.convert(utf8.encode('new-proof')).bytes)));
+    expect(utf8.decode(receipt.credentialRefreshed.authToken), 'old-proof');
+    expect(providerCalls, 0,
+        reason: 'the preceding admitted proof remains usable during rollout');
+  });
+
+  test(
+      'unavailable and failing providers return receipts without replay policy',
+      () async {
+    final platform = _Platform();
+    var result =
+        await platform.performCredentialRefresh(pending().refreshCredential);
+    expect(result.hasCredentialRefreshed(), isTrue);
+    expect(result.credentialRefreshed.hasAuthToken(), isFalse);
+    platform.registerCredentialProvider(
+        capability: 'opaque-capability',
+        cloud: 'https://example.test',
+        signIn: ({deviceChallenge}) async =>
+            throw StateError('secret diagnostic'));
+    result =
+        await platform.performCredentialRefresh(pending().refreshCredential);
+    expect(result.hasFailure(), isTrue);
+    expect(result.failure.message, isNot(contains('secret diagnostic')));
+  });
+
+  test('background physical event is consumed and returns a correlated receipt',
+      () async {
+    final platform = _Platform();
+    final failures = <Object>[];
+    expect(
+        platform.consumeCredentialRefreshEvent(
+            p.RuntimeEvent(), platform, (error, stack) => failures.add(error)),
+        isFalse);
+    expect(
+        platform.consumeCredentialRefreshEvent(
+            p.RuntimeEvent(
+                credentialRefreshRequested:
+                    p.CredentialRefreshRequested(pending: pending())),
+            platform,
+            (error, stack) => failures.add(error)),
+        isTrue);
+    await Future<void>.delayed(Duration.zero);
+    expect(platform.requests, hasLength(1));
+    expect(platform.requests.single.requestId, Int64(41));
+    expect(platform.requests.single.continueCorrespondence.workId, 'work');
+    expect(failures, isEmpty);
+  });
+
+  test(
+      'the device challenge reaches the provider verbatim and only when carried',
+      () async {
+    final platform = _Platform();
+    final seen = <String?>[];
+    platform.registerCredentialProvider(
+        capability: 'opaque-capability',
+        cloud: 'https://example.test',
+        signIn: ({deviceChallenge}) async {
+          seen.add(deviceChallenge);
+          return 'bound-${deviceChallenge ?? 'plain'}';
+        });
+    var receipt = await platform.performCredentialRefresh(
+        p.PeerCredentialRefreshEffect(
+            effectId: 'effect',
+            capability: 'opaque-capability',
+            deviceChallenge: 'ab' * 32));
+    expect(utf8.decode(receipt.credentialRefreshed.authToken),
+        'bound-${'ab' * 32}');
+    receipt =
+        await platform.performCredentialRefresh(pending().refreshCredential);
+    expect(utf8.decode(receipt.credentialRefreshed.authToken), 'bound-plain');
+    expect(seen, ['ab' * 32, null]);
+  });
+
+  test(
+      'a device identity load and save round-trip through the registered store',
+      () async {
+    final platform = _Platform();
+    final store = _MemoryIdentityStore();
+    platform.registerDeviceIdentityStore(store);
+    final secret = secretOf('device-a');
+    var receipt = await platform.performDeviceIdentityEffect(loadEffect());
+    expect(receipt.effectId, 'identity:load');
+    expect(receipt.hasDeviceIdentity(), isTrue);
+    expect(receipt.deviceIdentity.hasSecret(), isFalse);
+    receipt = await platform.performDeviceIdentityEffect(
+        p.PeerDeviceIdentityEffect(
+            effectId: 'identity:save',
+            identity: 'co2|user:ada',
+            save: p.PeerDeviceIdentitySave(secret: secret)));
+    expect(receipt.hasDeviceIdentity(), isTrue);
+    receipt = await platform.performDeviceIdentityEffect(loadEffect());
+    expect(receipt.deviceIdentity.secret, secret);
+    expect(store.log,
+        ['load:co2|user:ada', 'save:co2|user:ada', 'load:co2|user:ada']);
+  });
+
+  test('a shell without a device identity store refuses typed', () async {
+    final platform = _Platform();
+    final receipt = await platform.performDeviceIdentityEffect(loadEffect());
+    expect(receipt.hasFailure(), isTrue);
+    expect(receipt.failure.message, contains('device identity store'));
+  });
+
+  test(
+      'driveCredentialEffects answers a device identity paper on the same request',
+      () async {
+    final platform = _Platform();
+    final store = _MemoryIdentityStore()
+      ..saved['co2|user:ada'] = secretOf('device-b');
+    platform.registerDeviceIdentityStore(store);
+    var frames = 0;
+    final result = await platform.driveCredentialEffects(
+        p.RuntimeRequest(protocolVersion: 2, requestId: Int64(7)),
+        (request) async {
+      frames++;
+      expect(request.requestId, Int64(7));
+      if (frames == 1) {
+        return p.RuntimeResponse(
+            protocolVersion: 2,
+            requestId: request.requestId,
+            correspondencePending: p.CorrespondencePending(
+                workId: 'device-identity-1', deviceIdentity: loadEffect()));
+      }
+      expect(request.continueCorrespondence.workId, 'device-identity-1');
+      final receipt = request.continueCorrespondence.receipt;
+      expect(receipt.effectId, 'identity:load');
+      expect(receipt.deviceIdentity.secret, secretOf('device-b'));
+      return p.RuntimeResponse(
+          protocolVersion: 2,
+          requestId: request.requestId,
+          credentialsRefreshed:
+              p.CredentialsRefreshed(session: 'home', hasAuthorSecret: true));
+    });
+    expect(result.credentialsRefreshed.hasAuthorSecret, isTrue);
+    expect(frames, 2);
+  });
+
+  test('unrelated response cannot invoke a credential provider', () async {
+    final platform = _Platform();
+    await expectLater(
+        platform.driveCredentialEffects(
+            p.RuntimeRequest(protocolVersion: 2, requestId: Int64(7)),
+            (_) async => p.RuntimeResponse(
+                protocolVersion: 2,
+                requestId: Int64(8),
+                correspondencePending: pending())),
+        throwsStateError);
+  });
+}

package/dart/test/receiving_group_open_test.dart

@@ -0,0 +1,213 @@
+// THE RECEIVING-GROUP GATE FROM DART (receiving_group_lifecycle.md cut 4): Reception
+// transports ONE `OpenReceivingGroupRequest` paper and renders the office's answer; it
+// owns no ceremony. The desk's typed refusal surfaces as a NomosRuntimeError carrying the
+// desk's own code, and the convergence tail arrives as `ReceivingGroupConvergence`
+// runtime events scoped to the group's session.
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:nomos_client/src/nms_generated_runtime.dart';
+import 'package:nomos_types/nomos_kernel_protocol.dart' as protocol;
+import 'package:test/test.dart';
+
+const _principal = 'user:ada';
+// The office names the receiving group; Reception asks for it. A test scripts
+// that answer like any other paper.
+const _group = 'nomos-rg-scripted';
+final _lawSha256 = '2' * 64;
+
+final class _Office implements PeerOfficeConnection {
+  _Office({this.refuse});
+
+  /// A scripted desk refusal, or null for an opened gate.
+  final ({String code, String message})? refuse;
+  final _events = StreamController<protocol.RuntimeEvent>.broadcast();
+  final calls = <protocol.RuntimeRequest>[];
+
+  @override
+  Stream<protocol.RuntimeEvent> get runtimeEvents => _events.stream;
+
+  void emit(protocol.RuntimeEvent event) => _events.add(event);
+
+  int _requests = 0;
+  @override
+  int nextRuntimeRequestId() => ++_requests;
+
+  @override
+  Future<protocol.RuntimeResponse> invokeRuntime(
+    protocol.RuntimeRequest request,
+  ) async {
+    calls.add(request.deepCopy());
+    if (request.hasBindSession()) {
+      return protocol.RuntimeResponse(
+        protocolVersion: 2,
+        requestId: request.requestId,
+        sessionBound: protocol.SessionBound(
+          workspace: request.bindSession.workspace,
+          session: request.bindSession.session,
+          credentialCapability: request.bindSession.session,
+        ),
+      );
+    }
+    if (request.hasOpenReceivingGroup()) {
+      final refusal = refuse;
+      if (refusal != null) {
+        return protocol.RuntimeResponse(
+          protocolVersion: 2,
+          requestId: request.requestId,
+          failure: protocol.RuntimeFailure(
+            code: refusal.code,
+            message: refusal.message,
+            component: 'receiving-group-desk',
+          ),
+        );
+      }
+      return protocol.RuntimeResponse(
+        protocolVersion: 2,
+        requestId: request.requestId,
+        receivingGroupOpened: protocol.ReceivingGroupOpened(
+          session: request.openReceivingGroup.session,
+          workspace: _group,
+          deviceKeySubject: 'key:${'a' * 64}',
+        ),
+      );
+    }
+    throw StateError('unexpected runtime call ${request.whichCommand().name}');
+  }
+}
+
+Future<DartReception> _connected(_Office office) async {
+  final reception = DartReception(office);
+  addTearDown(reception.dispose);
+  await reception.bindSession(
+    workspace: _group,
+    principal: _principal,
+  );
+  return reception;
+}
+
+void main() {
+  test(
+      'the session sends exactly one open paper: contract, principal, session, no seed',
+      () async {
+    final office = _Office();
+    final reception = await _connected(office);
+
+    final opened = await reception.session(_group).nmsOpenReceivingGroup(
+          application: 'acme-platform',
+          principal: _principal,
+          authToken: 'id-token',
+          contract: protocol.ApplicationBirthContract(lawSha256: _lawSha256),
+          verifyHistory: true,
+        );
+
+    final papers =
+        office.calls.where((c) => c.hasOpenReceivingGroup()).toList();
+    expect(papers, hasLength(1));
+    final paper = papers.single.openReceivingGroup;
+    expect(paper.session, _group, reason: 'the session is the group workspace');
+    expect(paper.application, 'acme-platform');
+    expect(paper.principal, _principal);
+    expect(utf8.decode(paper.authToken), 'id-token');
+    expect(paper.contract.lawSha256, _lawSha256);
+    expect(paper.contract.toProto3Json(), {'lawSha256': _lawSha256},
+        reason:
+            'the contract is law-only: the platform controller is observed by the desk');
+    expect(paper.genesisSeed, isEmpty, reason: 'seeds are law');
+    expect(paper.verifyHistory, isTrue);
+    expect(papers.single.protocolVersion, 2);
+
+    expect(opened.workspace, _group);
+    expect(opened.deviceKeySubject, startsWith('key:'));
+  });
+
+  test("the desk's typed refusal surfaces as a runtime error carrying its code",
+      () async {
+    final office = _Office(
+      refuse: (
+        code: 'nomos.runtime.receiving_group_platform_controller_unknown',
+        message:
+            "the platform 'acme-platform' reports no current 'nomos' controller law",
+      ),
+    );
+    final reception = await _connected(office);
+
+    await expectLater(
+      reception.session(_group).nmsOpenReceivingGroup(
+            application: 'acme-platform',
+            principal: _principal,
+            authToken: 'id-token',
+            contract: protocol.ApplicationBirthContract(lawSha256: _lawSha256),
+          ),
+      throwsA(isA<NomosRuntimeError>().having(
+        (e) => e.info.code,
+        'code',
+        'nomos.runtime.receiving_group_platform_controller_unknown',
+      )),
+    );
+  });
+
+  test(
+      'convergence events reach the session bound to the group, and only that one',
+      () async {
+    final office = _Office();
+    final reception = await _connected(office);
+    await reception.bindSession(
+      workspace: 'estate-1',
+      principal: _principal,
+    );
+    final groupEvents = <protocol.ReceivingGroupConvergence>[];
+    final estateEvents = <protocol.ReceivingGroupConvergence>[];
+    final planeEvents = <protocol.ReceivingGroupConvergence>[];
+    final groupSub = reception
+        .session(_group)
+        .receivingGroupConvergence
+        .listen(groupEvents.add);
+    final estateSub = reception
+        .session('estate-1')
+        .receivingGroupConvergence
+        .listen(estateEvents.add);
+    final planeSub =
+        reception.receivingGroupConvergence.listen(planeEvents.add);
+    addTearDown(() async {
+      await groupSub.cancel();
+      await estateSub.cancel();
+      await planeSub.cancel();
+    });
+
+    protocol.RuntimeEvent event(
+      protocol.ReceivingGroupConvergencePhase phase,
+      protocol.ReceivingGroupConvergenceOutcome outcome,
+    ) =>
+        protocol.RuntimeEvent(
+          session: _group,
+          receivingGroupConvergence: protocol.ReceivingGroupConvergence(
+            workspace: _group,
+            phase: phase,
+            outcome: outcome,
+          ),
+        );
+    office.emit(event(
+      protocol.ReceivingGroupConvergencePhase
+          .RECEIVING_GROUP_CONVERGENCE_PHASE_POSTURE,
+      protocol.ReceivingGroupConvergenceOutcome
+          .RECEIVING_GROUP_CONVERGENCE_OUTCOME_IN_PROGRESS,
+    ));
+    office.emit(event(
+      protocol.ReceivingGroupConvergencePhase
+          .RECEIVING_GROUP_CONVERGENCE_PHASE_VERIFICATION,
+      protocol.ReceivingGroupConvergenceOutcome
+          .RECEIVING_GROUP_CONVERGENCE_OUTCOME_CONVERGED,
+    ));
+    await Future<void>.delayed(Duration.zero);
+
+    expect(groupEvents.map((e) => e.outcome.name), [
+      'RECEIVING_GROUP_CONVERGENCE_OUTCOME_IN_PROGRESS',
+      'RECEIVING_GROUP_CONVERGENCE_OUTCOME_CONVERGED',
+    ]);
+    expect(estateEvents, isEmpty,
+        reason: 'another workspace never sees the group tail');
+    expect(planeEvents, hasLength(2),
+        reason: 'the root reception sees the plane');
+  });
+}

package/dart/test/reception/workspace_preparation_report_test.dart

@@ -0,0 +1,103 @@
+import 'package:nomos_client/src/reception/workspace_preparation_report.dart';
+import 'package:nomos_client/src/reception/progress_desk.dart';
+import 'package:nomos_client/src/reception/event_desk.dart';
+import 'package:nomos_types/nomos_kernel_protocol.dart' as protocol;
+import 'package:test/test.dart';
+
+void main() {
+  test('a new peer demand clears stale index readiness before its kernel turn',
+      () {
+    final settled = WorkspacePreparationReport.fromMaintenance(
+      protocol.ReadMaintenanceProgress(
+        workspace: 'estate-1',
+        kernel: protocol.MaintenanceQuantumResponse(
+          phase: protocol.MaintenancePhase.MAINTENANCE_PHASE_COMPLETE,
+          readFrontier: 'head-a',
+          sqliteFrontier: 'head-a',
+        ),
+      ),
+    );
+    expect(settled.active, isFalse);
+    expect(settled.sqliteCurrent, isTrue);
+
+    final scheduled = WorkspacePreparationReport.fromMaintenance(
+      protocol.ReadMaintenanceProgress(workspace: 'estate-1'),
+      previous: settled,
+    );
+    expect(scheduled.active, isTrue);
+    expect(scheduled.sqliteCurrent, isNull);
+  });
+
+  test('peer retry is visible without claiming a sync failure', () {
+    final retry = WorkspacePreparationReport.fromMaintenance(
+      protocol.ReadMaintenanceProgress(
+        workspace: 'estate-1',
+        retryAfterMillis: 1000,
+      ),
+    );
+    expect(retry.retrying, isTrue);
+    expect(retry.active, isFalse);
+  });
+
+  test('unreadable copy stops preparation', () {
+    final stopped = WorkspacePreparationReport.fromMaintenance(
+      protocol.ReadMaintenanceProgress(workspace: 'estate-1', stopped: true),
+    );
+    expect(stopped.active, isFalse);
+    expect(stopped.stopped, isTrue);
+  });
+
+  test('an answered read closes the observation without a kernel turn', () {
+    final answered = WorkspacePreparationReport.fromMaintenance(
+      protocol.ReadMaintenanceProgress(
+        workspace: 'estate-1',
+        satisfiedByRead: true,
+      ),
+    );
+    expect(answered.active, isFalse);
+    expect(answered.step, WorkspacePreparationStep.complete);
+  });
+
+  test('restore law hydration is reported as installing workspace rules', () {
+    final law = WorkspacePreparationReport.fromRestore(KernelProgress(
+      sequence: 1,
+      operation: KernelProgressOperation.restoreMain,
+      phase: KernelProgressPhase.hydrateLaw,
+      completed: 0,
+      total: 1,
+      unit: KernelProgressUnit.lawPackage,
+      terminal: false,
+      lawHydrationStep: KernelLawHydrationStep.composeStage,
+      lawPackageSha256: 'law',
+      hostObservedElapsedMicros: 0,
+      hostObservedPhaseElapsedMicros: 0,
+      kernelAllocatorLiveBytes: 0,
+      kernelAllocatorPeakBytes: 0,
+      processResidentBytes: 0,
+      processPeakResidentBytes: 0,
+    ));
+    expect(law.step, WorkspacePreparationStep.installingLaw);
+    expect(law.active, isTrue);
+  });
+
+  test('peer maintenance observations drive the application report', () async {
+    final events = ReceptionEventDesk();
+    events.observeMaintenance(protocol.ReadMaintenanceProgress(
+      workspace: 'estate-1',
+      cause: protocol.ReadMaintenanceCause.READ_MAINTENANCE_CAUSE_OPEN,
+    ));
+    expect(events.syncStatuses.applicationStatus.preparingWorkspaces, 1);
+    expect(events.syncStatuses.applicationStatus.preparationActivity,
+        'Getting workspace data ready');
+
+    events.observeMaintenance(protocol.ReadMaintenanceProgress(
+      workspace: 'estate-1',
+      cause: protocol.ReadMaintenanceCause.READ_MAINTENANCE_CAUSE_OPEN,
+      kernel: protocol.MaintenanceQuantumResponse(
+        phase: protocol.MaintenancePhase.MAINTENANCE_PHASE_COMPLETE,
+      ),
+    ));
+    expect(events.syncStatuses.applicationStatus.preparingWorkspaces, 0);
+    await events.close();
+  });
+}