@githolon/dsl 0.108.7 → 0.110.1

package/dart/lib/src/reception/event_desk.dart

@@ -0,0 +1,214 @@
+import 'dart:async';
+
+import 'package:nomos_types/nomos_kernel_protocol.dart' as nomos_protocol;
+import 'package:nomos_types/nomos_types.dart'
+    show NomosCustodyEvent, NomosLocalWorkRejectedEvent;
+
+import '../application_model_adoption.dart' show NomosModelAdoptionProgress;
+import 'local_copies.dart' show NomosPreservedLocalCopy;
+import '../sync_status_projection.dart' show NmsSyncStatusProjection;
+import '../typed_watch_registry.dart' show NmsTypedWatchRegistry;
+import 'progress_desk.dart' show ReceptionProgressDesk;
+import 'progress_desk.dart' show KernelProgress;
+import 'workspace_preparation_report.dart'
+    show WorkspacePreparationReport, WorkspacePreparationStep;
+
+/// Language-native event and presentation state for one Reception lifetime.
+///
+/// This desk observes typed Peer Office events. It does not decide custody,
+/// admission, placement, sync policy or application law. Workspace session
+/// views share this exact object; they never allocate a second event plane.
+final class ReceptionEventDesk {
+  ReceptionEventDesk() {
+    _syncStatusChanges = syncStatuses.changes.listen((_) => _notifyCopies());
+  }
+
+  late final StreamSubscription<void> _syncStatusChanges;
+  final StreamController<void> _copyChanges =
+      StreamController<void>.broadcast();
+  final Map<String, WorkspacePreparationReport> _preparation = {};
+  final StreamController<nomos_protocol.RuntimeEvent> _sync =
+      StreamController<nomos_protocol.RuntimeEvent>.broadcast();
+  final StreamController<NomosCustodyEvent> _custody =
+      StreamController<NomosCustodyEvent>.broadcast();
+  final StreamController<NomosLocalWorkRejectedEvent> _localWorkRejected =
+      StreamController<NomosLocalWorkRejectedEvent>.broadcast();
+  final StreamController<nomos_protocol.ReceivingGroupConvergence>
+      _receivingGroupConvergence =
+      StreamController<nomos_protocol.ReceivingGroupConvergence>.broadcast();
+  final StreamController<NomosModelAdoptionProgress> _modelAdoption =
+      StreamController<NomosModelAdoptionProgress>.broadcast();
+  final StreamController<NomosPreservedLocalCopy> _preserved =
+      StreamController<NomosPreservedLocalCopy>.broadcast();
+  final List<NomosPreservedLocalCopy> _preservedLog = [];
+  final StreamController<nomos_protocol.ForeignPlacementIgnored>
+      _foreignPlacements =
+      StreamController<nomos_protocol.ForeignPlacementIgnored>.broadcast();
+  final Completer<void> _ready = Completer<void>();
+
+  final ReceptionProgressDesk progress = ReceptionProgressDesk();
+  final NmsSyncStatusProjection syncStatuses = NmsSyncStatusProjection();
+  late final NmsTypedWatchRegistry typedWatches =
+      NmsTypedWatchRegistry(synced: workspacesSynced);
+
+  Future<void> get ready => _ready.future;
+  Stream<nomos_protocol.RuntimeEvent> get syncEvents => _sync.stream;
+  Stream<void> get copyChanges => _copyChanges.stream;
+  WorkspacePreparationReport? preparationFor(String workspace) =>
+      _preparation[workspace];
+
+  void observeMaintenance(nomos_protocol.ReadMaintenanceProgress progress) {
+    final previous = _preparation[progress.workspace];
+    final next = WorkspacePreparationReport.fromMaintenance(
+      progress,
+      previous: previous,
+    );
+    _preparation[progress.workspace] = next;
+    if (previous?.step != next.step ||
+        previous?.active != next.active ||
+        previous?.retrying != next.retrying ||
+        previous?.sqliteCurrent != next.sqliteCurrent ||
+        previous?.gitFrontier != next.gitFrontier ||
+        previous?.readFrontier != next.readFrontier ||
+        previous?.sqliteFrontier != next.sqliteFrontier) {
+      _notifyCopies();
+    }
+    _updatePreparationCounts();
+  }
+
+  void observeRestore(String workspace, KernelProgress progress) {
+    final previous = _preparation[workspace];
+    final next = WorkspacePreparationReport.fromRestore(
+      progress,
+    );
+    _preparation[workspace] = next;
+    if (previous?.step != next.step ||
+        previous?.active != next.active ||
+        previous?.gitFrontier != next.gitFrontier ||
+        previous?.readFrontier != next.readFrontier ||
+        previous?.sqliteFrontier != next.sqliteFrontier) {
+      _notifyCopies();
+    }
+    _updatePreparationCounts();
+  }
+
+  void _updatePreparationCounts() {
+    final active =
+        _preparation.values.where((report) => report.active).toList();
+    syncStatuses.updatePreparationCounts(
+      active.length,
+      _preparation.values.where((report) => report.retrying).length,
+      activity: active.length == 1
+          ? switch (active.single.step) {
+              WorkspacePreparationStep.restoringHistory =>
+                'Checking saved workspace history',
+              WorkspacePreparationStep.installingLaw =>
+                'Installing workspace rules',
+              WorkspacePreparationStep.preparingReads =>
+                'Getting workspace data ready',
+              WorkspacePreparationStep.preparingWrites =>
+                'Getting workspace actions ready',
+              WorkspacePreparationStep.preparingCustody =>
+                'Preparing saved workspace data',
+              _ => 'Preparing a workspace',
+            }
+          : null,
+    );
+  }
+
+  void _notifyCopies() {
+    if (!_copyChanges.isClosed) _copyChanges.add(null);
+  }
+
+  /// Each workspace whose sync round just completed: the moment a copy that
+  /// answered "not ready yet" may be ready to read.
+  Stream<String> get workspacesSynced => _sync.stream
+      .where((event) => event.hasSyncCompleted())
+      .map((event) => event.syncCompleted.result.workspace);
+  Stream<NomosCustodyEvent> get custodyEvents => _custody.stream;
+  Stream<NomosLocalWorkRejectedEvent> get localWorkRejectedEvents =>
+      _localWorkRejected.stream;
+  Stream<nomos_protocol.ReceivingGroupConvergence>
+      get receivingGroupConvergence => _receivingGroupConvergence.stream;
+
+  /// The model-adoption desk's observations for every workspace on this plane.
+  Stream<NomosModelAdoptionProgress> get modelAdoption => _modelAdoption.stream;
+
+  /// Diagnostics log: every local copy this lifetime saw replaced and kept aside.
+  Stream<NomosPreservedLocalCopy> get localCopiesPreserved => _preserved.stream;
+
+  /// The most recent preservations, oldest first (bounded).
+  List<NomosPreservedLocalCopy> get recentLocalCopiesPreserved =>
+      List.unmodifiable(_preservedLog);
+
+  /// Diagnostics log: a placement naming an origin outside this host's configured
+  /// providers was ignored (never contacted).
+  Stream<nomos_protocol.ForeignPlacementIgnored> get foreignPlacementsIgnored =>
+      _foreignPlacements.stream;
+
+  void publishForeignPlacementIgnored(
+      nomos_protocol.ForeignPlacementIgnored ignored) {
+    if (!_foreignPlacements.isClosed) _foreignPlacements.add(ignored);
+  }
+
+  void publishLocalCopyPreserved(NomosPreservedLocalCopy copy) {
+    _preservedLog.add(copy);
+    if (_preservedLog.length > 64) _preservedLog.removeAt(0);
+    if (!_preserved.isClosed) _preserved.add(copy);
+  }
+
+  void publishModelAdoption(NomosModelAdoptionProgress progress) {
+    if (!_modelAdoption.isClosed) _modelAdoption.add(progress);
+  }
+
+  void markReady() {
+    if (!_ready.isCompleted) _ready.complete();
+  }
+
+  void failReady(Object error, [StackTrace? stackTrace]) {
+    if (_ready.isCompleted) return;
+    stackTrace == null
+        ? _ready.completeError(error)
+        : _ready.completeError(error, stackTrace);
+  }
+
+  void publishSync(nomos_protocol.RuntimeEvent event) {
+    if (!_sync.isClosed) _sync.add(event);
+  }
+
+  void publishCustody(NomosCustodyEvent event) {
+    if (!_custody.isClosed) _custody.add(event);
+  }
+
+  void publishLocalWorkRejected(NomosLocalWorkRejectedEvent event) {
+    if (!_localWorkRejected.isClosed) _localWorkRejected.add(event);
+  }
+
+  void publishReceivingGroupConvergence(
+    nomos_protocol.ReceivingGroupConvergence event,
+  ) {
+    if (!_receivingGroupConvergence.isClosed) {
+      _receivingGroupConvergence.add(event);
+    }
+  }
+
+  Future<void> close() async {
+    await _syncStatusChanges.cancel();
+    // Public broadcast streams can have paused UI listeners. Their close()
+    // futures wait for those listeners to resume, so signal done without
+    // letting an external subscriber hold reception teardown open.
+    if (!_copyChanges.isClosed) unawaited(_copyChanges.close());
+    await typedWatches.close();
+    if (!_sync.isClosed) unawaited(_sync.close());
+    if (!_custody.isClosed) unawaited(_custody.close());
+    if (!_localWorkRejected.isClosed) unawaited(_localWorkRejected.close());
+    if (!_receivingGroupConvergence.isClosed) {
+      unawaited(_receivingGroupConvergence.close());
+    }
+    if (!_modelAdoption.isClosed) unawaited(_modelAdoption.close());
+    if (!_preserved.isClosed) unawaited(_preserved.close());
+    if (!_foreignPlacements.isClosed) unawaited(_foreignPlacements.close());
+    await progress.close();
+    await syncStatuses.close();
+  }
+}

package/dart/lib/src/reception/extremum_read.dart

@@ -0,0 +1,46 @@
+import 'package:nomos_types/nomos_kernel_protocol.dart' as protocol;
+
+/// Encode one fixed framework read; the kernel resolves law and read authority.
+protocol.QueryRequest extremumQuery(String id, String kind, String? groupKey) {
+  if (id.isEmpty || (kind != 'min' && kind != 'max')) {
+    throw ArgumentError('A declared extremum needs an id and min/max kind');
+  }
+  return protocol.QueryRequest(
+      named: protocol.NamedQuery(
+    operation: protocol.QueryOperation.QUERY_OPERATION_EXTREMUM,
+    arguments: protocol.NomosStruct(
+        fields: {
+      'extremumId': protocol.NomosValue(text: id),
+      'kind': protocol.NomosValue(text: kind),
+      'groupKey': protocol.NomosValue(text: groupKey ?? ''),
+    }.entries),
+  ));
+}
+
+/// Empty is explicit null, never a missing or refused result. Keep the same exact
+/// integer range as the generated TypeScript application, including on Dart web.
+int? extremumValue(protocol.QueryResponse response) {
+  if (!response.hasValue() || !response.value.hasObject()) {
+    throw StateError('Kernel extremum returned no typed value');
+  }
+  final fields = response.value.object.fields;
+  if (fields['ok']?.hasBoolean() != true || !fields['ok']!.boolean) {
+    throw StateError('Kernel extremum did not succeed');
+  }
+  final value = fields['value'];
+  if (value?.whichKind() == protocol.NomosValue_Kind.null_1) return null;
+  final integer = switch (value?.whichKind()) {
+    protocol.NomosValue_Kind.signedInteger => value!.signedInteger,
+    protocol.NomosValue_Kind.unsignedInteger => value!.unsignedInteger,
+    _ =>
+      throw StateError('Kernel extremum returned neither an integer nor null'),
+  };
+  // Check in Int64 before toInt so JavaScript targets cannot round silently.
+  if ((value.hasUnsignedInteger() && integer.isNegative) ||
+      integer < -9007199254740991 ||
+      integer > 9007199254740991) {
+    throw StateError(
+        'Kernel extremum integer is outside the safe number range');
+  }
+  return integer.toInt();
+}

package/dart/lib/src/reception/local_copies.dart

@@ -0,0 +1,371 @@
+import 'package:meta/meta.dart' show immutable;
+import 'package:nomos_types/nomos_kernel_protocol.dart' as nomos_protocol;
+import 'workspace_preparation_report.dart';
+import '../sync_status_projection.dart' show SyncStatus;
+
+/// The provider now serves this workspace from a different genesis than this
+/// device's local copy: it was re-founded ("reborn") remotely. Sync refuses to
+/// merge, rebase or offer across geneses and schedules no retry. Dropping the
+/// local copy ([ReceptionLocalCopies.drop]) is the fix.
+@immutable
+final class NomosWorkspaceRebirth {
+  const NomosWorkspaceRebirth({
+    required this.localGenesis,
+    required this.remoteGenesis,
+    required this.localHead,
+    required this.remoteHead,
+    required this.detail,
+  });
+
+  factory NomosWorkspaceRebirth.fromRuntime(
+    nomos_protocol.WorkspaceRebirth rebirth,
+  ) =>
+      NomosWorkspaceRebirth(
+        localGenesis: rebirth.localGenesis,
+        remoteGenesis: rebirth.remoteGenesis,
+        localHead: rebirth.localHead,
+        remoteHead: rebirth.remoteHead,
+        detail: rebirth.detail,
+      );
+
+  final String localGenesis;
+  final String remoteGenesis;
+  final String localHead;
+  final String remoteHead;
+
+  /// A short explanation to show next to the workspace.
+  final String detail;
+
+  @override
+  bool operator ==(Object other) =>
+      other is NomosWorkspaceRebirth &&
+      other.localGenesis == localGenesis &&
+      other.remoteGenesis == remoteGenesis &&
+      other.localHead == localHead &&
+      other.remoteHead == remoteHead &&
+      other.detail == detail;
+
+  @override
+  int get hashCode =>
+      Object.hash(localGenesis, remoteGenesis, localHead, remoteHead, detail);
+}
+
+/// One workspace this device holds or follows, as its local copy stands.
+@immutable
+final class NomosLocalWorkspaceCopy {
+  const NomosLocalWorkspaceCopy({
+    required this.workspace,
+    required this.followed,
+    required this.loaded,
+    required this.rebornRemotely,
+    required this.dropPending,
+    this.unreadableReason,
+    this.preservedCopies = const [],
+    this.preparation,
+    this.sessionStatuses = const [],
+  });
+
+  factory NomosLocalWorkspaceCopy.fromRuntime(
+          nomos_protocol.WorkspaceSummary summary,
+          {WorkspacePreparationReport? preparation,
+          List<SyncStatus> sessionStatuses = const []}) =>
+      NomosLocalWorkspaceCopy(
+        workspace: summary.workspace,
+        followed: summary.followed,
+        loaded: summary.kernelResident,
+        rebornRemotely: summary.hasRebornRemotely()
+            ? NomosWorkspaceRebirth.fromRuntime(summary.rebornRemotely)
+            : null,
+        dropPending: summary.localCopyDropPending,
+        unreadableReason: summary.hasLocalCopyUnreadable()
+            ? summary.localCopyUnreadable
+            : null,
+        preservedCopies: List.unmodifiable([
+          for (final copy in summary.preservedCopies)
+            NomosPreservedLocalCopy.fromRuntime(copy),
+        ]),
+        preparation: preparation,
+        sessionStatuses: sessionStatuses,
+      );
+
+  final String workspace;
+
+  /// A provider exists for this workspace, so a dropped copy can be refetched.
+  final bool followed;
+
+  /// The workspace's kernel is resident on this device right now.
+  final bool loaded;
+
+  /// Non-null while the provider serves another genesis than this copy.
+  final NomosWorkspaceRebirth? rebornRemotely;
+
+  /// A drop was authorized and its refetch has not finished yet.
+  final bool dropPending;
+
+  /// Non-null when this device's kernel cannot read the copy (for example it
+  /// is from an older storage format). The app opens around it; dropping the
+  /// copy refetches it.
+  final String? unreadableReason;
+
+  /// Earlier copies of this workspace that a refetch replaced and kept aside
+  /// (preserved, not merged), each with what it held that was never synced.
+  final List<NomosPreservedLocalCopy> preservedCopies;
+
+  /// Last preparation observation from the peer during this Reception lifetime.
+  final WorkspacePreparationReport? preparation;
+
+  /// Exact sync observations for sessions bound to this workspace. An empty
+  /// list does not prove that a followed copy has settled.
+  final List<SyncStatus> sessionStatuses;
+}
+
+/// A local copy replaced by a refetch and kept aside under
+/// `refs/heads/custody-preserved/`: never deleted, never merged.
+@immutable
+final class NomosPreservedLocalCopy {
+  const NomosPreservedLocalCopy({
+    required this.workspace,
+    required this.preservedHead,
+    required this.preservedRef,
+    required this.reason,
+    required this.unsyncedLocalChanges,
+    required this.changesCounted,
+    required this.automatic,
+    required this.preservedAt,
+    required this.syncedHead,
+  });
+
+  factory NomosPreservedLocalCopy.fromRuntime(
+    nomos_protocol.PreservedLocalCopy copy,
+  ) =>
+      NomosPreservedLocalCopy(
+        workspace: copy.workspace,
+        preservedHead: copy.preservedHead,
+        preservedRef: copy.preservedRef,
+        reason: copy.reason,
+        unsyncedLocalChanges: copy.unsyncedLocalChanges.toInt(),
+        changesCounted: copy.changesCounted,
+        automatic: copy.automatic,
+        preservedAt: copy.preservedAtUnixMillis == 0
+            ? null
+            : DateTime.fromMillisecondsSinceEpoch(
+                copy.preservedAtUnixMillis.toInt(),
+                isUtc: true,
+              ),
+        syncedHead: copy.hasSyncedHead() ? copy.syncedHead : null,
+      );
+
+  final String workspace;
+  final String preservedHead;
+  final String preservedRef;
+
+  /// Why it was replaced, e.g. "local copy is from an older storage format".
+  final String reason;
+
+  /// Commits it held above the provider's last admitted head.
+  final int unsyncedLocalChanges;
+
+  /// False when those could not be determined: [unsyncedLocalChanges] then
+  /// means "unknown", never "none".
+  final bool changesCounted;
+
+  /// The application's own open refetched it, not a user's drop.
+  final bool automatic;
+  final DateTime? preservedAt;
+  final String? syncedHead;
+
+  @override
+  bool operator ==(Object other) =>
+      other is NomosPreservedLocalCopy &&
+      other.workspace == workspace &&
+      other.preservedHead == preservedHead &&
+      other.reason == reason &&
+      other.unsyncedLocalChanges == unsyncedLocalChanges &&
+      other.changesCounted == changesCounted &&
+      other.automatic == automatic;
+
+  @override
+  int get hashCode => Object.hash(workspace, preservedHead, reason,
+      unsyncedLocalChanges, changesCounted, automatic);
+}
+
+/// What dropping a workspace's local copy would discard. Obtain it from
+/// [ReceptionLocalCopies.preview]; pass it back to [ReceptionLocalCopies.drop],
+/// which drops exactly the previewed copy and nothing newer.
+@immutable
+final class NomosLocalCopyDropPreview {
+  const NomosLocalCopyDropPreview({
+    required this.workspace,
+    required this.localHead,
+    required this.unsyncedLocalChanges,
+    required this.parkedLocalChanges,
+    required this.undeliveredLetters,
+    required this.lettersCounted,
+    required this.followed,
+    required this.rebornRemotely,
+    this.changesCounted = true,
+    this.unreadableReason,
+  });
+
+  factory NomosLocalCopyDropPreview.fromRuntime(
+    nomos_protocol.LocalCopyDropPreview preview,
+  ) =>
+      NomosLocalCopyDropPreview(
+        workspace: preview.workspace,
+        localHead: preview.hasLocalHead() ? preview.localHead : null,
+        unsyncedLocalChanges: preview.unsyncedLocalChanges.toInt(),
+        parkedLocalChanges: preview.parkedLocalChanges.toInt(),
+        undeliveredLetters: preview.undeliveredLetters.toInt(),
+        lettersCounted: preview.lettersCounted,
+        followed: preview.followed,
+        rebornRemotely: preview.hasRebornRemotely()
+            ? NomosWorkspaceRebirth.fromRuntime(preview.rebornRemotely)
+            : null,
+        changesCounted: preview.changesCounted,
+        unreadableReason: preview.hasLocalCopyUnreadable()
+            ? preview.localCopyUnreadable
+            : null,
+      );
+
+  final String workspace;
+
+  /// The exact local head a drop replaces; null when there is no local copy.
+  final String? localHead;
+
+  /// Local changes the provider never admitted.
+  final int unsyncedLocalChanges;
+
+  /// Refused local changes parked on this device.
+  final int parkedLocalChanges;
+
+  /// Cross-workspace letters not yet delivered.
+  final int undeliveredLetters;
+
+  /// False when [undeliveredLetters] is a lower bound.
+  final bool lettersCounted;
+
+  /// A provider exists to refetch from; [ReceptionLocalCopies.drop] refuses otherwise.
+  final bool followed;
+
+  final NomosWorkspaceRebirth? rebornRemotely;
+
+  /// False when Git could not determine the unsynced changes:
+  /// [unsyncedLocalChanges] then means "unknown", never "none".
+  final bool changesCounted;
+
+  /// Why this device's kernel cannot read the copy, when it cannot.
+  final String? unreadableReason;
+
+  /// Everything the drop would discard, summed.
+  int get changesLost =>
+      unsyncedLocalChanges + parkedLocalChanges + undeliveredLetters;
+
+  /// Whether dropping loses any work at all.
+  bool get losesWork => changesLost > 0 || !lettersCounted || !changesCounted;
+
+  /// Whether there is a local copy that can be dropped and refetched.
+  bool get canDrop => localHead != null && followed;
+}
+
+/// Fixed Reception capability over this device's local workspace copies. A
+/// local copy is a droppable cache of the provider's custody: dropping one
+/// replaces only that workspace's local custody, projections and indexes, then
+/// refetches it from the current provider. Device keys, credentials, the
+/// identity store and every other workspace are untouched.
+final class ReceptionLocalCopies {
+  const ReceptionLocalCopies({
+    required Future<nomos_protocol.RuntimeResponse> Function(
+            nomos_protocol.RuntimeRequest)
+        invoke,
+    required this.changes,
+    Stream<NomosPreservedLocalCopy> preservations = const Stream.empty(),
+    List<NomosPreservedLocalCopy> Function() recentPreservations = _none,
+    WorkspacePreparationReport? Function(String) preparationFor =
+        _noPreparation,
+    List<SyncStatus> Function(List<String>) statusesFor = _noStatuses,
+  })  : _invoke = invoke,
+        _preservations = preservations,
+        _recentPreservations = recentPreservations,
+        _preparationFor = preparationFor,
+        _statusesFor = statusesFor;
+
+  static List<NomosPreservedLocalCopy> _none() => const [];
+  static WorkspacePreparationReport? _noPreparation(String _) => null;
+  static List<SyncStatus> _noStatuses(List<String> _) => const [];
+
+  final Future<nomos_protocol.RuntimeResponse> Function(
+      nomos_protocol.RuntimeRequest) _invoke;
+
+  /// Fires whenever a workspace's sync status changes; re-read [list] then.
+  final Stream<void> changes;
+
+  final Stream<NomosPreservedLocalCopy> _preservations;
+  final List<NomosPreservedLocalCopy> Function() _recentPreservations;
+  final WorkspacePreparationReport? Function(String) _preparationFor;
+  final List<SyncStatus> Function(List<String>) _statusesFor;
+
+  /// Diagnostics log: each local copy replaced and kept aside, as it happens
+  /// (including the unreadable Home refetched by the application's own open).
+  Stream<NomosPreservedLocalCopy> get preservations => _preservations;
+
+  /// The preservations this Reception has observed so far, oldest first.
+  List<NomosPreservedLocalCopy> get recentPreservations =>
+      _recentPreservations();
+
+  /// Every workspace this device holds or follows, with its reborn state.
+  Future<List<NomosLocalWorkspaceCopy>> list() async {
+    final response = await _invoke(nomos_protocol.RuntimeRequest(
+      listWorkspaces: nomos_protocol.ListWorkspacesRequest(),
+    ));
+    if (!response.hasWorkspaceList()) {
+      throw StateError(
+          'Runtime v2 returned ${response.whichOutcome().name} for listWorkspaces');
+    }
+    return List.unmodifiable([
+      for (final summary in response.workspaceList.workspaces)
+        NomosLocalWorkspaceCopy.fromRuntime(
+          summary,
+          preparation: _preparationFor(summary.workspace),
+          sessionStatuses: _statusesFor(summary.sessions),
+        ),
+    ]);
+  }
+
+  /// What dropping [workspace]'s local copy would discard. Reads only.
+  Future<NomosLocalCopyDropPreview> preview(String workspace) async {
+    final response = await _invoke(nomos_protocol.RuntimeRequest(
+      previewLocalCopyDrop:
+          nomos_protocol.PreviewLocalCopyDropRequest(workspace: workspace),
+    ));
+    if (!response.hasLocalCopyDropPreview()) {
+      throw StateError('Runtime v2 returned ${response.whichOutcome().name} '
+          'for previewLocalCopyDrop');
+    }
+    return NomosLocalCopyDropPreview.fromRuntime(response.localCopyDropPreview);
+  }
+
+  /// Drop exactly the previewed local copy and refetch it from the provider.
+  /// Refused (thrown) when the copy changed since [preview], when there is no
+  /// local copy, or when no provider exists. The refetch runs in the
+  /// background; watch [list] until the workspace is no longer [NomosLocalWorkspaceCopy.dropPending].
+  Future<void> drop(NomosLocalCopyDropPreview preview) async {
+    final head = preview.localHead;
+    if (head == null) {
+      throw StateError('${preview.workspace} has no local copy to drop');
+    }
+    if (!preview.followed) {
+      throw StateError(
+          '${preview.workspace} has no provider to refetch it from');
+    }
+    final response = await _invoke(nomos_protocol.RuntimeRequest(
+      dropLocalCopy: nomos_protocol.DropLocalCopyRequest(
+        workspace: preview.workspace,
+        expectedLocalHead: head,
+      ),
+    ));
+    if (!response.hasLocalCopyDropScheduled()) {
+      throw StateError(
+          'Runtime v2 returned ${response.whichOutcome().name} for dropLocalCopy');
+    }
+  }
+}

package/dart/lib/src/reception/peer_office_connection.dart

@@ -0,0 +1,11 @@
+import '../runtime_v2_transport.dart'
+    show NomosRuntimeV2EventTransport, NomosRuntimeV2Transport;
+
+/// The typed connection Reception receives from a platform shell.
+///
+/// This is the entire physical boundary to Peer Office: correlated Runtime v2
+/// requests plus its asynchronous event lane. A conforming connection cannot
+/// silently omit subscriptions. It contains no application, custody, placement
+/// or authority semantics.
+abstract interface class PeerOfficeConnection
+    implements NomosRuntimeV2Transport, NomosRuntimeV2EventTransport {}