@githolon/dsl 0.108.7 → 0.110.0

package/dart/lib/src/reception/workspace_preparation_report.dart

@@ -0,0 +1,126 @@
+import 'package:nomos_types/nomos_kernel_protocol.dart' as protocol;
+
+import 'progress_desk.dart';
+
+/// A disposable, read-only projection of work reported by the Peer Office.
+/// Absence means unobserved, not ready. No application action is driven by it.
+enum WorkspacePreparationStep {
+  restoringHistory,
+  installingLaw,
+  preparingReads,
+  preparingWrites,
+  preparingCustody,
+  preparingWorkspace,
+  complete,
+}
+
+final class WorkspacePreparationReport {
+  const WorkspacePreparationReport({
+    required this.step,
+    required this.active,
+    this.gitFrontier,
+    this.readFrontier,
+    this.sqliteFrontier,
+    this.retryAfterMillis,
+    this.stopped = false,
+  });
+
+  final WorkspacePreparationStep step;
+  final bool active;
+  final String? gitFrontier;
+  final String? readFrontier;
+  final String? sqliteFrontier;
+  final int? retryAfterMillis;
+  final bool stopped;
+  bool get retrying => retryAfterMillis != null;
+
+  /// Exact equality of reported frontiers, rather than a guess from residency.
+  bool? get sqliteCurrent {
+    if (readFrontier == null || sqliteFrontier == null) return null;
+    return readFrontier == sqliteFrontier;
+  }
+
+  static WorkspacePreparationReport fromMaintenance(
+    protocol.ReadMaintenanceProgress progress, {
+    WorkspacePreparationReport? previous,
+  }) {
+    final kernel = progress.hasKernel() ? progress.kernel : null;
+    final retry =
+        progress.hasRetryAfterMillis() ? progress.retryAfterMillis : null;
+    final step = progress.satisfiedByRead
+        ? WorkspacePreparationStep.complete
+        : kernel == null
+            ? switch (progress.cause) {
+                protocol.ReadMaintenanceCause
+                      .READ_MAINTENANCE_CAUSE_DOMAIN_PREPARATION =>
+                  WorkspacePreparationStep.preparingWrites,
+                protocol.ReadMaintenanceCause.READ_MAINTENANCE_CAUSE_OPEN ||
+                protocol
+                    .ReadMaintenanceCause.READ_MAINTENANCE_CAUSE_READ_DEBT ||
+                protocol
+                      .ReadMaintenanceCause.READ_MAINTENANCE_CAUSE_RESIDENCY =>
+                  WorkspacePreparationStep.preparingReads,
+                _ => WorkspacePreparationStep.preparingWorkspace,
+              }
+            : switch (kernel.phase) {
+                protocol.MaintenancePhase.MAINTENANCE_PHASE_READ_DOCUMENTS ||
+                protocol.MaintenancePhase.MAINTENANCE_PHASE_SQLITE_INDEX ||
+                protocol.MaintenancePhase.MAINTENANCE_PHASE_READ_INDEX_CACHE =>
+                  WorkspacePreparationStep.preparingReads,
+                protocol.MaintenancePhase.MAINTENANCE_PHASE_COMMAND_FRONTIER ||
+                protocol.MaintenancePhase.MAINTENANCE_PHASE_COMMAND_ROUTE =>
+                  WorkspacePreparationStep.preparingWrites,
+                protocol.MaintenancePhase.MAINTENANCE_PHASE_GIT_CUSTODY =>
+                  WorkspacePreparationStep.preparingCustody,
+                protocol.MaintenancePhase.MAINTENANCE_PHASE_COMPLETE =>
+                  WorkspacePreparationStep.complete,
+                _ => WorkspacePreparationStep.preparingWorkspace,
+              };
+    return WorkspacePreparationReport(
+      step: step,
+      active: retry == null &&
+          !progress.stopped &&
+          !progress.satisfiedByRead &&
+          (kernel == null || kernel.maintenancePending),
+      retryAfterMillis: retry,
+      stopped: progress.stopped,
+      // A new demand may target a newer frontier. Never carry old readiness
+      // across its scheduled observation before the kernel reports a result.
+      gitFrontier: kernel == null
+          ? null
+          : kernel.hasGitFrontier()
+              ? kernel.gitFrontier
+              : previous?.gitFrontier,
+      readFrontier: kernel == null
+          ? null
+          : kernel.hasReadFrontier()
+              ? kernel.readFrontier
+              : previous?.readFrontier,
+      sqliteFrontier: kernel == null
+          ? null
+          : kernel.hasSqliteFrontier()
+              ? kernel.sqliteFrontier
+              : previous?.sqliteFrontier,
+    );
+  }
+
+  static WorkspacePreparationReport fromRestore(KernelProgress progress) =>
+      WorkspacePreparationReport(
+        step: switch (progress.phase) {
+          KernelProgressPhase.readChain ||
+          KernelProgressPhase.readTimeline ||
+          KernelProgressPhase.verifyIntents =>
+            WorkspacePreparationStep.restoringHistory,
+          KernelProgressPhase.hydrateLaw =>
+            WorkspacePreparationStep.installingLaw,
+          KernelProgressPhase.complete => WorkspacePreparationStep.complete,
+          _ => WorkspacePreparationStep.preparingWorkspace,
+        },
+        active: !progress.terminal,
+        // Restore may target a new frontier. Earlier accelerator observations
+        // cannot establish readiness for it.
+        gitFrontier: null,
+        readFrontier: null,
+        sqliteFrontier: null,
+      );
+}

package/dart/lib/src/replica_readiness.dart

@@ -0,0 +1,123 @@
+/// One-shot reads wait out a local copy that is not ready yet.
+///
+/// A workspace this peer is still fetching, refetching, opening or indexing
+/// answers a read with a retryable [NomosUnavailable] whose reason is
+/// `localReplicaNotReady` or `workspaceOpening`. That is "not yet", not a
+/// failure. [NmsTypedWatchRegistry] already waits it out before registering a
+/// watch; this is the same rule for every one-shot read (queries, pages, counts,
+/// sums, by-id and by-type USDA, historic queries), applied once where they all
+/// reach the kernel. Callers therefore see either an answer or a real error.
+/// They never see a state that passes by itself a moment later.
+@internal
+library;
+
+import 'dart:async';
+
+import 'package:meta/meta.dart' show internal, visibleForTesting;
+import 'package:nomos_types/nomos_types.dart'
+    show NomosUnavailable, NomosUnavailableReason;
+
+/// How long one read keeps asking before it reports the copy as unavailable.
+/// A first sync of a large workspace at cutover takes minutes, not hours.
+@visibleForTesting
+Duration nmsReplicaReadyGiveUpAfter = const Duration(minutes: 10);
+
+/// First pause between asks when the runtime gives no `retryAfter`. It doubles
+/// per attempt, up to 16 times this value (the watch registry's schedule).
+@visibleForTesting
+Duration nmsReplicaReadyFirstDelay = const Duration(milliseconds: 250);
+
+/// True for an unavailable answer that means "this copy is not ready yet".
+bool nmsIsReplicaNotReady(Object error) =>
+    error is NomosUnavailable &&
+    error.retryable &&
+    (error.reason == NomosUnavailableReason.localReplicaNotReady ||
+        error.reason == NomosUnavailableReason.workspaceOpening);
+
+/// Runs [read], asking again while it answers [nmsIsReplicaNotReady].
+///
+/// [synced] names each workspace whose sync round just completed; the office
+/// emits it the moment a copy it was fetching or opening is ready. A read
+/// waiting on that workspace asks again at once instead of sleeping out its
+/// `retryAfter`, which stays only as the fallback for a copy that becomes ready
+/// without a sync (an index built in the background).
+///
+/// Any other error, including a non-retryable or remote-side unavailability,
+/// is rethrown at once, as is the last not-ready answer after
+/// [nmsReplicaReadyGiveUpAfter].
+@internal
+Future<T> nmsUntilReplicaReady<T>(
+  Future<T> Function() read, {
+  Stream<String>? synced,
+}) async {
+  final waited = Stopwatch()..start();
+  final wake = NmsReplicaWake(synced);
+  try {
+    for (var attempt = 0;; attempt++) {
+      wake.asking();
+      try {
+        return await read();
+      } on NomosUnavailable catch (unavailable) {
+        if (!nmsIsReplicaNotReady(unavailable) ||
+            waited.elapsed >= nmsReplicaReadyGiveUpAfter) {
+          rethrow;
+        }
+        await wake.wait(unavailable, attempt);
+      }
+    }
+  } finally {
+    await wake.close();
+  }
+}
+
+/// The pause after a "not ready yet" answer: the runtime's `retryAfter` (or
+/// [nmsReplicaReadyFirstDelay]), doubling per attempt up to 16 times, cut short
+/// the moment the workspace's sync completes.
+///
+/// It listens from construction, so a sync that completes between the ask and
+/// the wait is not missed: [asking] marks the start of each ask, and a wait for
+/// a workspace that synced since then returns at once.
+@internal
+final class NmsReplicaWake {
+  NmsReplicaWake(Stream<String>? synced) {
+    _subscription = synced?.listen(_synced);
+  }
+
+  StreamSubscription<String>? _subscription;
+  final Set<String> _syncedSinceAsk = {};
+  String? _waitingOn;
+  Completer<void>? _woken;
+
+  void asking() => _syncedSinceAsk.clear();
+
+  Future<void> wait(NomosUnavailable unavailable, int attempt) async {
+    final workspace = unavailable.workspace;
+    if (_syncedSinceAsk.contains(workspace) ||
+        (workspace.isEmpty && _syncedSinceAsk.isNotEmpty)) {
+      return;
+    }
+    final base = unavailable.retryAfter ?? nmsReplicaReadyFirstDelay;
+    final woken = _woken = Completer<void>();
+    _waitingOn = workspace;
+    final timer = Timer(base * (1 << (attempt < 4 ? attempt : 4)), () {
+      if (!woken.isCompleted) woken.complete();
+    });
+    try {
+      await woken.future;
+    } finally {
+      timer.cancel();
+      _woken = null;
+      _waitingOn = null;
+    }
+  }
+
+  void _synced(String workspace) {
+    _syncedSinceAsk.add(workspace);
+    final woken = _woken;
+    final waitingOn = _waitingOn;
+    if (woken == null || woken.isCompleted || waitingOn == null) return;
+    if (waitingOn.isEmpty || waitingOn == workspace) woken.complete();
+  }
+
+  Future<void> close() async => _subscription?.cancel();
+}