@githolon/dsl 0.117.0 → 0.119.9

package/dart/lib/src/replica_readiness.dart

@@ -1,82 +1,220 @@
-/// One-shot reads wait out a local copy that is not ready yet.
+/// Reads answer at once from what is on this device. They never wait for the network.
 ///
-/// 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.
+/// Jack's rule (11 Oct 2026): sync is a background effect, and every read answers immediately
+/// from the device. A workspace this peer has never fetched, is fetching or refetching with
+/// nothing servable yet, or is still opening, answers a read with a retryable
+/// [NomosUnavailable] whose reason is `localReplicaNotReady` or `workspaceOpening`; a copy whose
+/// read index is being rebuilt under a law its head adopted (and which this application cannot
+/// decode) answers `readIndexRefreshing`. None of these is a failure, and none is waited out
+/// here any more. An application data read (rows, a page, by-id or by-type rows, a count or a
+/// sum) answers EMPTY at once, and the session's [SyncStatus.localCopy] says the copy is
+/// [LocalCopyReadiness.arriving] or [LocalCopyReadiness.updating], so a presentation shows what it
+/// has beside "downloading". A watch emits that empty result at once and emits again when the copy
+/// arrives ([NmsTypedWatchRegistry]). A framework read with no empty form (child workspaces,
+/// authentication posture, …) reports the typed [NomosUnavailable] at once.
+///
+/// The download itself is the peer's work: the answer that a copy is not ready marks that
+/// workspace urgent in the peer's background queue (NativeBackgroundRouter.applicationWaitsOn),
+/// and a watch asking again keeps it urgent while someone is looking.
+///
+/// Before this rule `nmsUntilReplicaReady` re-asked every such read for up to ten minutes. On
+/// Jack's iPhone (TestFlight 1334, 11 Oct 2026 10:07 UTC) the Lippold catalogue panel's read of a
+/// never-fetched data profile was held 11 s, until its download finished, behind a full-panel
+/// spinner.
 @internal
 library;
 
 import 'dart:async';
+import 'dart:convert' show utf8;
 
+import 'package:fixnum/fixnum.dart' show Int64;
 import 'package:meta/meta.dart' show internal, visibleForTesting;
+import 'package:nomos_types/nomos_kernel_protocol.dart' as nomos_protocol;
 import 'package:nomos_types/nomos_types.dart'
     show NomosUnavailable, NomosUnavailableReason;
+import 'package:nomos_types/src/proto/google/protobuf/any.pb.dart'
+    as google_protobuf;
 
-/// 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);
+import 'sync_status_projection.dart'
+    show LocalCopyReadiness, SyncStatus, nmsSaysCopyDamaged;
 
-/// 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).
+/// First pause between a watch's registration attempts when the runtime gives no `retryAfter`.
+/// It doubles per attempt, up to 16 times this value. Only a watch asks again: by then it has
+/// already emitted what is on the device, so nobody waits on these asks.
 @visibleForTesting
 Duration nmsReplicaReadyFirstDelay = const Duration(milliseconds: 250);
 
-/// True for an unavailable answer that means "this copy is not ready yet".
+/// True for an unavailable answer that means "this copy is not readable here yet": still
+/// fetching or opening, or its read index being rebuilt under a law its head has just adopted
+/// (CAP-900: that answer reached the app as an error on Jack's phone).
 bool nmsIsReplicaNotReady(Object error) =>
     error is NomosUnavailable &&
     error.retryable &&
     (error.reason == NomosUnavailableReason.localReplicaNotReady ||
-        error.reason == NomosUnavailableReason.workspaceOpening);
+        error.reason == NomosUnavailableReason.workspaceOpening ||
+        error.reason == NomosUnavailableReason.readIndexRefreshing ||
+        error.reason == NomosUnavailableReason.firstDownload);
 
-/// 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).
+/// The [LocalCopyReadiness] a "not readable here yet" answer reports. A copy that is HERE but
+/// damaged (`localReplicaNotReady` whose detail says its local Git history is incomplete, it cannot
+/// be read, or it is being refetched) is [LocalCopyReadiness.repairing], never "arriving": on
+/// Jack's iPad (TestFlight 1338, 11 Oct 2026) such an estate read as arriving while its rounds
+/// "completed", and the app said every workspace was in sync while every edit failed.
+@internal
+LocalCopyReadiness nmsLocalCopyReadiness(NomosUnavailable unavailable) =>
+    switch (unavailable.reason) {
+      NomosUnavailableReason.readIndexRefreshing => LocalCopyReadiness.updating,
+      NomosUnavailableReason.firstDownload => LocalCopyReadiness.firstDownload,
+      NomosUnavailableReason.localReplicaNotReady
+          when nmsSaysCopyDamaged(unavailable.detail) =>
+        LocalCopyReadiness.repairing,
+      _ => LocalCopyReadiness.arriving,
+    };
+
+/// Where a read reports what it found of its workspace's local copy: the reception records it on
+/// the session's [SyncStatus.localCopy].
+@internal
+typedef NmsLocalCopyReport = void Function(LocalCopyReadiness readiness);
+
+/// Runs [read] ONCE and answers at once.
 ///
-/// Any other error, including a non-retryable or remote-side unavailability,
-/// is rethrown at once, as is the last not-ready answer after
-/// [nmsReplicaReadyGiveUpAfter].
+/// A "not readable here yet" answer ([nmsIsReplicaNotReady]) is reported to [report] and turned
+/// into [pending]'s empty answer; when [pending] has none (returns null) the typed
+/// [NomosUnavailable] is rethrown at once. An answer reports [LocalCopyReadiness.ready]. Any other
+/// error is rethrown at once and reports nothing. There is no retry, sleep or wait here.
 @internal
-Future<T> nmsUntilReplicaReady<T>(
+Future<T> nmsReadNow<T>(
   Future<T> Function() read, {
-  Stream<String>? synced,
+  required T? Function(NomosUnavailable unavailable) pending,
+  NmsLocalCopyReport? report,
 }) async {
-  final waited = Stopwatch()..start();
-  final wake = NmsReplicaWake(synced);
+  final T answer;
   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);
+    answer = await read();
+  } on NomosUnavailable catch (unavailable) {
+    if (!nmsIsReplicaNotReady(unavailable)) {
+      // A damaged copy no refetch is under way for still says so on its status.
+      if (unavailable.reason == NomosUnavailableReason.localReplicaNotReady &&
+          nmsSaysCopyDamaged(unavailable.detail)) {
+        report?.call(LocalCopyReadiness.repairing);
       }
+      rethrow;
+    }
+    report?.call(nmsLocalCopyReadiness(unavailable));
+    final empty = pending(unavailable);
+    if (empty == null) rethrow;
+    return empty;
+  }
+  report?.call(LocalCopyReadiness.ready);
+  return answer;
+}
+
+/// The nominal USDA of a read result with no rows: what an application data read answers while
+/// its copy is not readable here yet.
+@internal
+final List<int> nmsEmptyReadResultUsda = utf8.encode('''#usda 1.0
+(
+    defaultPrim = "Result"
+)
+
+def NomosReadResult "Result"
+{
+    custom uniform bool nomos:done = true
+
+    def NomosListValue "Rows"
+    {
     }
-  } finally {
-    await wake.close();
+}
+''');
+
+const String _queryTypePrefix = 'type.nomos.dev/nomos.operation.v1.Query_';
+const String _queryResultTypePrefix =
+    'type.nomos.dev/nomos.operation.v1.QueryResult_';
+
+/// The generated result type of a declared application query: `Query_<sid>` arguments answer
+/// `QueryResult_<sid>` (codegen_query_proto.ts / codegen_result_proto.ts). Null when [arguments]
+/// is not a generated query's arguments.
+String? _resultTypeOf(google_protobuf.Any arguments) {
+  final type = arguments.typeUrl;
+  if (!type.startsWith(_queryTypePrefix)) return null;
+  final sid = type.substring(_queryTypePrefix.length);
+  return sid.isEmpty ? null : '$_queryResultTypePrefix$sid';
+}
+
+/// The empty answer of an application data read whose copy is not readable here yet, in the
+/// result arm and format [query] asked for: no rows (the generated `QueryResult_<sid>` with no
+/// rows, or a nominal USDA result with none), or a zero tally. Null for a query with no empty
+/// form: a framework read, or a format this read does not answer in.
+@internal
+nomos_protocol.QueryResponse? nmsPendingQueryResponse(
+  nomos_protocol.QueryRequest query,
+) {
+  final format = query.resultFormat;
+  switch (query.whichQuery()) {
+    case nomos_protocol.QueryRequest_Query.rows:
+    case nomos_protocol.QueryRequest_Query.page:
+      if (format ==
+          nomos_protocol
+              .QueryResultFormat.QUERY_RESULT_FORMAT_APPLICATION_PROTOBUF) {
+        final resultType = _resultTypeOf(
+          query.hasRows()
+              ? query.rows.applicationArguments
+              : query.page.applicationArguments,
+        );
+        if (resultType == null) return null;
+        return nomos_protocol.QueryResponse(
+          applicationResult: google_protobuf.Any(typeUrl: resultType),
+        );
+      }
+      return _emptyUsda(format);
+    case nomos_protocol.QueryRequest_Query.byId:
+    case nomos_protocol.QueryRequest_Query.byType:
+    case nomos_protocol.QueryRequest_Query.spatial:
+      return _emptyUsda(format);
+    case nomos_protocol.QueryRequest_Query.count:
+    case nomos_protocol.QueryRequest_Query.sum:
+      return nomos_protocol.QueryResponse(integerValue: Int64.ZERO);
+    default:
+      return null;
   }
 }
 
-/// 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.
+nomos_protocol.QueryResponse? _emptyUsda(
+  nomos_protocol.QueryResultFormat format,
+) =>
+    format == nomos_protocol.QueryResultFormat.QUERY_RESULT_FORMAT_NOMINAL_USDA
+        ? nomos_protocol.QueryResponse(resultUsda: nmsEmptyReadResultUsda)
+        : null;
+
+/// The first emission of a watch on [query] whose copy is not readable here yet: the same empty
+/// answer as [nmsPendingQueryResponse], as the watch event its decoder reads. Null when the query
+/// has no empty form.
+@internal
+nomos_protocol.WatchChanged? nmsPendingWatchChanged(
+  nomos_protocol.QueryRequest query,
+  String subscriptionId,
+) {
+  final empty = nmsPendingQueryResponse(query);
+  if (empty == null) return null;
+  final changed = nomos_protocol.WatchChanged(subscriptionId: subscriptionId);
+  if (empty.hasApplicationResult()) {
+    changed.applicationResult = empty.applicationResult;
+  } else if (empty.hasResultUsda()) {
+    changed.resultUsda = empty.resultUsda;
+  } else if (empty.hasIntegerValue()) {
+    changed.integerValue = empty.integerValue;
+  }
+  return changed;
+}
+
+/// The pause before a watch asks again 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. The watch has already emitted what is on the device,
+/// so this pause holds nobody up; it only paces the re-registration.
 ///
-/// 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.
+/// 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) {
@@ -97,9 +235,15 @@ final class NmsReplicaWake {
       return;
     }
     final base = unavailable.retryAfter ?? nmsReplicaReadyFirstDelay;
+    // A rebuild under a new law finishes without any sync to wake this wait, so its
+    // re-ask stays near the runtime's retryAfter (at most twice it), never 16 times it.
+    final growth =
+        unavailable.reason == NomosUnavailableReason.readIndexRefreshing
+            ? (attempt < 1 ? attempt : 1)
+            : (attempt < 4 ? attempt : 4);
     final woken = _woken = Completer<void>();
     _waitingOn = workspace;
-    final timer = Timer(base * (1 << (attempt < 4 ? attempt : 4)), () {
+    final timer = Timer(base * (1 << growth), () {
       if (!woken.isCompleted) woken.complete();
     });
     try {
@@ -111,6 +255,12 @@ final class NmsReplicaWake {
     }
   }
 
+  /// Ends a wait in progress now (the watch it paces was cancelled or already delivers).
+  void wakeNow() {
+    final woken = _woken;
+    if (woken != null && !woken.isCompleted) woken.complete();
+  }
+
   void _synced(String workspace) {
     _syncedSinceAsk.add(workspace);
     final woken = _woken;