@githolon/dsl 0.108.7 → 0.110.0

package/dart/lib/src/sync_status_reducer.dart

@@ -0,0 +1,170 @@
+import 'package:nomos_types/nomos_kernel_protocol.dart' as protocol;
+
+import 'sync_status_projection.dart';
+
+/// Byte movement is not local admission or durable custody acceptance. Keep
+/// those semantic observations independent of the transient progress overlay.
+/// A read-only pull must never manufacture unsaved local work, and an inbound
+/// transfer must not erase a real pending admission or a reported refusal.
+SyncStatus reduceTransferProgress(
+        SyncStatus current, TransferProgress progress) =>
+    current.copyWith(
+      phase: current.phase == SyncPhase.idle ||
+              current.phase == SyncPhase.transferring
+          ? SyncPhase.checking
+          : current.phase,
+      clearCounts: current.phase == SyncPhase.idle,
+      transfer: progress,
+      clearTransfer: progress.done,
+    );
+
+/// Presentation only: no custody reads, network calls, clocks or retry state.
+/// A completed round is not necessarily convergence. The runtime tells us
+/// whether work remains; it does not currently report a total pending count.
+SyncStatus reduceSyncCompletion(
+  SyncStatus current,
+  protocol.SyncCompleted completed,
+  DateTime observedAt,
+) {
+  if (completed.hasFailure()) {
+    return current.copyWith(
+      phase: SyncPhase.error,
+      clearTransfer: true,
+      lastError: completed.failure.message,
+    );
+  }
+  if (!completed.hasResult()) {
+    return current.copyWith(
+      phase: SyncPhase.error,
+      clearTransfer: true,
+      lastError: 'Sync completed without a custody result.',
+    );
+  }
+  final result = completed.result;
+  final receiptIssue = _receiptIssue(result.offerReceipt);
+  final pending =
+      result.stillAhead || result.directOfferDeferred || result.deferred > 0;
+  final awaitingRemoteDurability = result.stillAhead &&
+      !result.directOfferDeferred &&
+      !result.reconnectRequired &&
+      result.deferred == 0 &&
+      result.currentHead.isNotEmpty &&
+      result.offerReceipt.hasAdmission() &&
+      result.offerReceipt.admission.main == result.currentHead &&
+      result.offerReceipt.admission.sealedMain != result.currentHead;
+  final failure = result.hasPushError()
+      ? result.pushError.message
+      : result.hasDiscoveryError()
+          ? result.discoveryError.message
+          : result.hasRemoteRefusal()
+              ? [
+                  if (result.remoteRefusal.hasCode()) result.remoteRefusal.code,
+                  result.remoteRefusal.reason,
+                  if (result.remoteRefusal.hasIntentId())
+                    'Intent: ${result.remoteRefusal.intentId}',
+                ].where((part) => part.isNotEmpty).join('\n')
+              // Re-founded remotely: the typed fact, and the fix, not a raw kernel reason.
+              : result.hasRebornRemotely()
+                  ? result.rebornRemotely.detail
+                  : result.hasCustodyDisagreement() && !result.custodyReplaced
+                      ? 'Custody disagreement: ${result.custodyDisagreement.reason}\n'
+                          'Local: ${result.custodyDisagreement.localHead}\n'
+                          'Remote: ${result.custodyDisagreement.candidateHead}'
+                      : receiptIssue;
+  final attention = result.pushFailed ||
+      result.hasPushError() ||
+      result.hasDiscoveryError() ||
+      result.hasRemoteRefusal() ||
+      receiptIssue != null ||
+      result.refused > 0 ||
+      (result.hasCustodyDisagreement() && !result.custodyReplaced);
+  final phase = result.offline
+      ? SyncPhase.offline
+      : attention
+          ? SyncPhase.error
+          : awaitingRemoteDurability
+              ? SyncPhase.awaitingRemoteDurability
+              : pending
+                  ? SyncPhase.syncing
+                  : result.localOnly ||
+                          result.reconnectRequired ||
+                          result.currentHead.isEmpty
+                      ? SyncPhase.checking
+                      : SyncPhase.idle;
+  final settled = phase == SyncPhase.idle;
+  return SyncStatus(
+    phase: phase,
+    ahead: settled ? 0 : null,
+    behind: settled ? 0 : null,
+    lastSyncedAt: settled ? observedAt : current.lastSyncedAt,
+    live: current.live,
+    followed: current.followed,
+    followsInSync: current.followsInSync,
+    lastResult: result.deepCopy()..freeze(),
+    lastError: failure ??
+        (attention ? 'Shared custody has not accepted these changes.' : null),
+  );
+}
+
+/// Preserve the receiving office's explanation, not just its aggregate count.
+String? _receiptIssue(protocol.CustodyOfferReceipt receipt) {
+  if (receipt.hasFailure()) return receipt.failure.message;
+  if (receipt.hasBlocked()) {
+    final blocked = receipt.blocked;
+    if (blocked.hasKernelResidency()) {
+      final required = blocked.kernelResidency;
+      return 'Sharing is waiting for ${required.workspace} to become resident.'
+          '${required.detail.isEmpty ? '' : ' ${required.detail}'}';
+    }
+    if (blocked.hasCustody()) {
+      return 'Sharing is waiting for custody of ${blocked.custody.workspace}.';
+    }
+    if (blocked.hasCandidateCustody()) {
+      return 'Sharing is waiting for ${blocked.candidateCustody.workspace} '
+          'to fetch ${blocked.candidateCustody.reference}.';
+    }
+    if (blocked.hasSiblings()) {
+      final workspaces = blocked.siblings.residencies
+          .map((residency) => residency.workspace)
+          .where((workspace) => workspace.isNotEmpty)
+          .join(', ');
+      return workspaces.isEmpty
+          ? 'Sharing is waiting for sibling workspaces.'
+          : 'Sharing is waiting for sibling workspaces: $workspaces.';
+    }
+    return 'Sharing is waiting on a remote dependency.';
+  }
+  if (!receipt.hasAdmission()) return null;
+  for (final session in receipt.admission.sessions) {
+    for (final intent in session.intents) {
+      final message = switch (intent.whichOutcome()) {
+        protocol.CustodyIntentAdmission_Outcome.refused =>
+          intent.refused.message,
+        protocol.CustodyIntentAdmission_Outcome.deadLettered =>
+          intent.deadLettered.message,
+        protocol.CustodyIntentAdmission_Outcome.blocked =>
+          intent.blocked.detail,
+        protocol.CustodyIntentAdmission_Outcome.quarantined =>
+          intent.quarantined.reason,
+        protocol.CustodyIntentAdmission_Outcome.admitted ||
+        protocol.CustodyIntentAdmission_Outcome.skipped ||
+        protocol.CustodyIntentAdmission_Outcome.notSet =>
+          null,
+      };
+      if (message != null) {
+        return message.isEmpty
+            ? 'Shared custody could not admit this change.'
+            : message;
+      }
+    }
+  }
+  return null;
+}
+
+/// A local admission invalidates the previous settled observation immediately.
+/// Counting callbacks cannot recover debt that predates this process.
+SyncStatus locallyAdmitted(SyncStatus current) => current.copyWith(
+      phase: SyncPhase.syncing,
+      clearCounts: true,
+      clearError: true,
+    );