@githolon/dsl 0.108.7 → 0.110.1

package/dart/lib/src/signing_identity_kernel.dart

@@ -0,0 +1,84 @@
+@internal
+library;
+
+import 'dart:typed_data';
+
+import 'package:meta/meta.dart' show internal;
+import 'package:nomos_types/nomos_kernel_protocol.dart' as protocol;
+
+import 'runtime_v2_transport.dart' show NomosKernelCallTransport;
+
+/// The exact kernel-owned signing-identity capability.
+///
+/// This is deliberately not a generic command adapter. It carries one
+/// generated request to the kernel and accepts only its generated response.
+/// Platform code retains the returned secret; it does not implement key
+/// generation or public-key derivation itself.
+final class NmsSigningIdentityKernel {
+  const NmsSigningIdentityKernel({
+    required this.transport,
+    required this.session,
+  });
+
+  final NomosKernelCallTransport transport;
+  final String session;
+
+  Future<protocol.SigningKeyPair> generate({
+    required String requestId,
+  }) async {
+    final response = await _call(
+      requestId: requestId,
+      request: protocol.SigningIdentityRequest(
+        generate: protocol.GenerateSigningKeyPair(),
+      ),
+    );
+    if (!response.hasGenerated()) {
+      throw StateError(
+        'Kernel returned ${response.whichResult().name} for signing-key generation',
+      );
+    }
+    return response.generated;
+  }
+
+  Future<protocol.SigningPublicKey> derivePublic({
+    required String requestId,
+    required Uint8List secret,
+  }) async {
+    final response = await _call(
+      requestId: requestId,
+      request: protocol.SigningIdentityRequest(
+        derivePublic: protocol.DeriveSigningPublicKey(secret: secret),
+      ),
+    );
+    if (!response.hasDerivedPublic()) {
+      throw StateError(
+        'Kernel returned ${response.whichResult().name} for signing-public derivation',
+      );
+    }
+    return response.derivedPublic;
+  }
+
+  Future<protocol.SigningIdentityResponse> _call({
+    required String requestId,
+    required protocol.SigningIdentityRequest request,
+  }) async {
+    final response = await transport.callKernel(
+      session: session,
+      credentialUse: protocol.CredentialUse.CREDENTIAL_USE_NONE,
+      request: protocol.CallRequest(
+        protocolVersion: 1,
+        requestId: requestId,
+        signingIdentity: request,
+      ),
+    );
+    if (response.hasFailure()) {
+      throw StateError('${response.failure.code}: ${response.failure.message}');
+    }
+    if (!response.hasSigningIdentity()) {
+      throw StateError(
+        'Kernel returned ${response.whichOutcome().name} for a signing-identity request',
+      );
+    }
+    return response.signingIdentity;
+  }
+}

package/dart/lib/src/sync_status_projection.dart

@@ -0,0 +1,550 @@
+import 'dart:async';
+
+import 'package:nomos_types/nomos_kernel_protocol.dart' as nomos_protocol;
+
+import 'application_model_adoption.dart' show NomosModelAdoptionProgress;
+
+/// Live byte progress reported by the peer runtime for one custody transfer.
+final class TransferProgress {
+  const TransferProgress({
+    required this.received,
+    this.total,
+    this.kind = 'delta',
+  });
+
+  final int received;
+  final int? total;
+  final String kind;
+
+  double? get fraction => (total == null || total == 0)
+      ? null
+      : (received / total!).clamp(0.0, 1.0);
+  bool get done => total != null && received >= total!;
+
+  factory TransferProgress.fromRuntime(
+    nomos_protocol.TransferProgress progress,
+  ) =>
+      TransferProgress(
+        received: progress.receivedBytes.toInt(),
+        total: progress.hasTotalBytes() ? progress.totalBytes.toInt() : null,
+        kind: switch (progress.kind) {
+          nomos_protocol.TransferKind.TRANSFER_KIND_FULL => 'full',
+          nomos_protocol.TransferKind.TRANSFER_KIND_PUSH => 'push',
+          _ => 'delta',
+        },
+      );
+}
+
+enum SyncPhase {
+  checking,
+  idle,
+  syncing,
+  awaitingRemoteDurability,
+  transferring,
+  behind,
+  offline,
+  error
+}
+
+/// The durable Replica Follow's own state, observed without starting a round.
+enum WorkspaceFollowPhase {
+  desired,
+  due,
+  running,
+  settled,
+  awaitingDependency,
+  offline,
+  invalidCredential,
+  backoff,
+  rebornRemotely,
+  replacingLocal,
+  localCopyUnreadable,
+  unknown,
+}
+
+final class WorkspaceFollowStatus {
+  const WorkspaceFollowStatus({
+    required this.workspace,
+    required this.phase,
+    required this.live,
+    this.detail,
+    this.retryAt,
+    this.dueAt,
+    this.attempt,
+    this.activeEffect,
+  });
+
+  factory WorkspaceFollowStatus.fromRuntime(
+    nomos_protocol.FollowObservation report,
+  ) =>
+      WorkspaceFollowStatus(
+        workspace: report.workspace,
+        phase: switch (report.phase) {
+          nomos_protocol
+                .FollowObservationPhase.FOLLOW_OBSERVATION_PHASE_DESIRED =>
+            WorkspaceFollowPhase.desired,
+          nomos_protocol.FollowObservationPhase.FOLLOW_OBSERVATION_PHASE_DUE =>
+            WorkspaceFollowPhase.due,
+          nomos_protocol
+                .FollowObservationPhase.FOLLOW_OBSERVATION_PHASE_RUNNING =>
+            WorkspaceFollowPhase.running,
+          nomos_protocol
+                .FollowObservationPhase.FOLLOW_OBSERVATION_PHASE_SETTLED =>
+            WorkspaceFollowPhase.settled,
+          nomos_protocol.FollowObservationPhase
+                .FOLLOW_OBSERVATION_PHASE_AWAITING_DEPENDENCY =>
+            WorkspaceFollowPhase.awaitingDependency,
+          nomos_protocol
+                .FollowObservationPhase.FOLLOW_OBSERVATION_PHASE_OFFLINE =>
+            WorkspaceFollowPhase.offline,
+          nomos_protocol.FollowObservationPhase
+                .FOLLOW_OBSERVATION_PHASE_INVALID_CREDENTIAL =>
+            WorkspaceFollowPhase.invalidCredential,
+          nomos_protocol
+                .FollowObservationPhase.FOLLOW_OBSERVATION_PHASE_BACKOFF =>
+            WorkspaceFollowPhase.backoff,
+          nomos_protocol.FollowObservationPhase
+                .FOLLOW_OBSERVATION_PHASE_REBORN_REMOTELY =>
+            WorkspaceFollowPhase.rebornRemotely,
+          nomos_protocol.FollowObservationPhase
+                .FOLLOW_OBSERVATION_PHASE_REPLACING_LOCAL =>
+            WorkspaceFollowPhase.replacingLocal,
+          nomos_protocol.FollowObservationPhase
+                .FOLLOW_OBSERVATION_PHASE_LOCAL_COPY_UNREADABLE =>
+            WorkspaceFollowPhase.localCopyUnreadable,
+          _ => WorkspaceFollowPhase.unknown,
+        },
+        live: report.live,
+        detail: report.hasDetail() ? report.detail : null,
+        retryAt: report.hasRetryAtUnixMillis()
+            ? DateTime.fromMillisecondsSinceEpoch(
+                report.retryAtUnixMillis.toInt())
+            : null,
+        dueAt: report.hasDueAtUnixMillis()
+            ? DateTime.fromMillisecondsSinceEpoch(
+                report.dueAtUnixMillis.toInt())
+            : null,
+        attempt: report.hasAttempt() ? report.attempt : null,
+        activeEffect: report.hasActiveEffect() ? report.activeEffect : null,
+      );
+
+  final String workspace;
+  final WorkspaceFollowPhase phase;
+  final bool live;
+  final String? detail;
+  final DateTime? retryAt;
+  final DateTime? dueAt;
+  final int? attempt;
+  final String? activeEffect;
+  bool get current => phase == WorkspaceFollowPhase.settled && live;
+}
+
+/// Disposable UI projection of typed peer-runtime sync observations.
+final class SyncStatus {
+  const SyncStatus({
+    this.phase = SyncPhase.checking,
+    this.ahead,
+    this.behind,
+    this.saved,
+    this.onMain,
+    this.deadLetters,
+    this.transfer,
+    this.lastSyncedAt,
+    this.lastError,
+    this.lastResult,
+    this.modelAdoption,
+    this.live = false,
+    this.followed,
+    this.followsInSync,
+    this.followsLive,
+    this.followStatuses = const [],
+    this.followReportAt,
+    this.preparingWorkspaces = 0,
+    this.retryingWorkspaces = 0,
+    this.preparationActivity,
+  });
+
+  final SyncPhase phase;
+
+  /// The live link to this workspace's upstream is open, so a settled status is current NOW:
+  /// the upstream pushes every new frontier and an idle follow runs no round. On the
+  /// application status: every connected workspace is settled and live.
+  final bool live;
+
+  /// Application status only: the replica follows this peer keeps up with in the background,
+  /// and how many of them are in sync (settled at their exact local head). Null until the
+  /// runtime has reported its follow inventory.
+  final int? followed;
+  final int? followsInSync;
+  final int? followsLive;
+  final List<WorkspaceFollowStatus> followStatuses;
+
+  /// The peer's time for its most recent changed follow report.
+  final DateTime? followReportAt;
+
+  /// Counts of Peer Office preparation observations, not inferred from sync.
+  final int preparingWorkspaces;
+  final int retryingWorkspaces;
+  final String? preparationActivity;
+
+  /// Physical progress overlays the semantic custody observation; finishing a
+  /// transfer reveals that observation instead of inventing a saving state.
+  SyncPhase get presentationPhase =>
+      transfer != null && phase != SyncPhase.error && phase != SyncPhase.offline
+          ? SyncPhase.transferring
+          : phase;
+  // null means not reported, never zero. Counts are observations, not a
+  // running total of writes seen by this Reception process.
+  final int? ahead;
+  final int? behind;
+  final int? saved;
+  final int? onMain;
+  final int? deadLetters;
+  final TransferProgress? transfer;
+  final DateTime? lastSyncedAt;
+  final String? lastError;
+
+  /// Exact last runtime receipt, not counters reconstructed from callbacks.
+  final nomos_protocol.SyncWorkspaceResponse? lastResult;
+
+  /// The model-adoption desk's latest observation for this workspace: progress
+  /// while it brings the workspace onto the application's approved law, then
+  /// the terminal outcome (`current`, `adopted`, a typed `deferred`).
+  final NomosModelAdoptionProgress? modelAdoption;
+
+  SyncStatus copyWith({
+    SyncPhase? phase,
+    int? ahead,
+    int? behind,
+    int? saved,
+    int? onMain,
+    int? deadLetters,
+    TransferProgress? transfer,
+    bool clearTransfer = false,
+    DateTime? lastSyncedAt,
+    String? lastError,
+    bool clearError = false,
+    bool clearCounts = false,
+    nomos_protocol.SyncWorkspaceResponse? lastResult,
+    NomosModelAdoptionProgress? modelAdoption,
+    bool? live,
+    int? followed,
+    int? followsInSync,
+    int? followsLive,
+    List<WorkspaceFollowStatus>? followStatuses,
+    DateTime? followReportAt,
+    int? preparingWorkspaces,
+    int? retryingWorkspaces,
+    String? preparationActivity,
+    bool clearPreparationActivity = false,
+  }) =>
+      SyncStatus(
+        phase: phase ?? this.phase,
+        ahead: ahead ?? (clearCounts ? null : this.ahead),
+        behind: behind ?? (clearCounts ? null : this.behind),
+        saved: saved ?? (clearCounts ? null : this.saved),
+        onMain: onMain ?? (clearCounts ? null : this.onMain),
+        deadLetters: deadLetters ?? (clearCounts ? null : this.deadLetters),
+        transfer: clearTransfer ? null : (transfer ?? this.transfer),
+        lastSyncedAt: lastSyncedAt ?? this.lastSyncedAt,
+        lastError: clearError ? null : (lastError ?? this.lastError),
+        lastResult: lastResult ?? this.lastResult,
+        modelAdoption: modelAdoption ?? this.modelAdoption,
+        live: live ?? this.live,
+        followed: followed ?? this.followed,
+        followsInSync: followsInSync ?? this.followsInSync,
+        followsLive: followsLive ?? this.followsLive,
+        followStatuses: followStatuses ?? this.followStatuses,
+        followReportAt: followReportAt ?? this.followReportAt,
+        preparingWorkspaces: preparingWorkspaces ?? this.preparingWorkspaces,
+        retryingWorkspaces: retryingWorkspaces ?? this.retryingWorkspaces,
+        preparationActivity: clearPreparationActivity
+            ? null
+            : preparationActivity ?? this.preparationActivity,
+      );
+}
+
+bool _sameTransfer(TransferProgress? left, TransferProgress? right) =>
+    identical(left, right) ||
+    (left != null &&
+        right != null &&
+        left.received == right.received &&
+        left.total == right.total &&
+        left.kind == right.kind);
+
+bool _sameFollows(
+    List<WorkspaceFollowStatus> left, List<WorkspaceFollowStatus> right) {
+  if (identical(left, right)) return true;
+  if (left.length != right.length) return false;
+  for (var i = 0; i < left.length; i++) {
+    final a = left[i];
+    final b = right[i];
+    if (a.workspace != b.workspace ||
+        a.phase != b.phase ||
+        a.live != b.live ||
+        a.detail != b.detail ||
+        a.retryAt != b.retryAt ||
+        a.dueAt != b.dueAt ||
+        a.attempt != b.attempt ||
+        a.activeEffect != b.activeEffect) return false;
+  }
+  return true;
+}
+
+bool _sameStatus(SyncStatus left, SyncStatus right) =>
+    left.phase == right.phase &&
+    left.ahead == right.ahead &&
+    left.behind == right.behind &&
+    left.saved == right.saved &&
+    left.onMain == right.onMain &&
+    left.deadLetters == right.deadLetters &&
+    _sameTransfer(left.transfer, right.transfer) &&
+    left.lastSyncedAt == right.lastSyncedAt &&
+    left.lastError == right.lastError &&
+    identical(left.lastResult, right.lastResult) &&
+    identical(left.modelAdoption, right.modelAdoption) &&
+    left.live == right.live &&
+    left.followed == right.followed &&
+    left.followsInSync == right.followsInSync &&
+    left.followsLive == right.followsLive &&
+    _sameFollows(left.followStatuses, right.followStatuses) &&
+    left.followReportAt == right.followReportAt &&
+    left.preparingWorkspaces == right.preparingWorkspaces &&
+    left.retryingWorkspaces == right.retryingWorkspaces &&
+    left.preparationActivity == right.preparationActivity;
+
+/// One projection owner for application-wide and per-session sync status.
+/// It has no timers, networking, retries, credentials, or custody authority.
+final class NmsSyncStatusProjection {
+  final _changes = StreamController<void>.broadcast();
+
+  /// Invalidates views even when two workspace changes leave the total unchanged.
+  Stream<void> get changes => _changes.stream;
+  late final StreamController<SyncStatus> _application =
+      StreamController<SyncStatus>.broadcast(onListen: _seedApplication);
+  final Map<String, SyncStatus> _bySession = {};
+  final Map<String, StreamController<SyncStatus>> _sessionStreams = {};
+  SyncStatus _current = const SyncStatus();
+  int? _followed;
+  int? _followsInSync;
+  int? _followsLive;
+  List<WorkspaceFollowStatus> _followStatuses = const [];
+  DateTime? _followReportAt;
+  int _preparingWorkspaces = 0;
+  int _retryingWorkspaces = 0;
+  String? _preparationActivity;
+
+  Stream<SyncStatus> get applicationStream => _application.stream;
+  SyncStatus get applicationStatus => _current;
+
+  Stream<SyncStatus> sessionStream(String session) => _sessionStreams
+      .putIfAbsent(
+        session,
+        () => StreamController<SyncStatus>.broadcast(
+          onListen: () => _seedSession(session),
+        ),
+      )
+      .stream;
+
+  SyncStatus statusFor(String session) =>
+      _bySession[session] ?? const SyncStatus();
+
+  void ensureSession(String session, SyncStatus initial) {
+    if (_bySession.containsKey(session)) return;
+    _bySession[session] = initial;
+    if (!_changes.isClosed) _changes.add(null);
+  }
+
+  /// The runtime's application-wide follow inventory (`FollowsSummary`).
+  void updateFollows(int followed, int inSync,
+      {int? live,
+      List<WorkspaceFollowStatus> statuses = const [],
+      DateTime? observedAt}) {
+    _followed = followed;
+    _followsInSync = inSync;
+    _followsLive = live;
+    _followStatuses = List.unmodifiable(statuses);
+    _followReportAt = observedAt;
+    _pushApplication(
+      _current.copyWith(
+          followed: followed,
+          followsInSync: inSync,
+          followsLive: live,
+          followStatuses: _followStatuses,
+          followReportAt: _followReportAt),
+    );
+  }
+
+  /// Fold the peer's disposable preparation report into the existing status
+  /// stream. No lifecycle decision, read or maintenance request occurs here.
+  void updatePreparationCounts(int preparing, int retrying,
+      {String? activity}) {
+    _preparingWorkspaces = preparing;
+    _retryingWorkspaces = retrying;
+    _preparationActivity = activity;
+    _pushApplication(_current.copyWith(
+      preparingWorkspaces: preparing,
+      retryingWorkspaces: retrying,
+      preparationActivity: activity,
+      clearPreparationActivity: activity == null,
+    ));
+  }
+
+  void update({
+    required String? session,
+    required Iterable<String> connectedSessions,
+    required SyncStatus Function(SyncStatus current) change,
+  }) {
+    if (session == null || session.isEmpty) {
+      _pushApplication(change(_current));
+      return;
+    }
+    pushSession(session, change(statusFor(session)));
+    foldApplication(connectedSessions);
+  }
+
+  void pushSession(String session, SyncStatus status) {
+    final previous = _bySession[session];
+    if (previous != null && _sameStatus(previous, status)) return;
+    _bySession[session] = status;
+    if (!_changes.isClosed) _changes.add(null);
+    final controller = _sessionStreams[session];
+    if (controller != null && !controller.isClosed) controller.add(status);
+  }
+
+  void foldApplication(Iterable<String> connectedSessions) {
+    final statuses =
+        connectedSessions.toSet().map(statusFor).toList(growable: false);
+    if (statuses.isEmpty) {
+      _pushApplication(
+        SyncStatus(
+          followed: _followed,
+          followsInSync: _followsInSync,
+          followsLive: _followsLive,
+          followStatuses: _followStatuses,
+          followReportAt: _followReportAt,
+          preparingWorkspaces: _preparingWorkspaces,
+          retryingWorkspaces: _retryingWorkspaces,
+          preparationActivity: _preparationActivity,
+        ),
+      );
+      return;
+    }
+
+    final phase = statuses.any((status) => status.phase == SyncPhase.error)
+        ? SyncPhase.error
+        : statuses.any((status) => status.phase == SyncPhase.offline)
+            ? SyncPhase.offline
+            : statuses.any(
+                (status) => status.presentationPhase == SyncPhase.transferring,
+              )
+                ? SyncPhase.transferring
+                : statuses.any(
+                    (status) =>
+                        status.phase == SyncPhase.behind ||
+                        (status.behind ?? 0) > 0,
+                  )
+                    ? SyncPhase.behind
+                    : statuses.any(
+                        (status) =>
+                            status.phase == SyncPhase.syncing ||
+                            (status.ahead ?? 0) > 0,
+                      )
+                        ? SyncPhase.syncing
+                        : statuses.any((status) =>
+                                status.phase ==
+                                SyncPhase.awaitingRemoteDurability)
+                            ? SyncPhase.awaitingRemoteDurability
+                            : statuses.any((status) =>
+                                    status.phase == SyncPhase.checking)
+                                ? SyncPhase.checking
+                                : SyncPhase.idle;
+
+    int? total(int? Function(SyncStatus status) read) {
+      var sum = 0;
+      for (final status in statuses) {
+        final count = read(status);
+        if (count == null) return null;
+        sum += count;
+      }
+      return sum;
+    }
+
+    // "Last confirmed" is the oldest moment any connected workspace was KNOWN current. A settled
+    // workspace whose live link is open is current now (its upstream pushes every change), so it
+    // never holds the answer back; the rest contribute their last settled round.
+    bool liveNow(SyncStatus status) =>
+        status.live && status.phase == SyncPhase.idle;
+    final allLive = statuses.every(liveNow);
+    DateTime? lastSynced;
+    String? error;
+    TransferProgress? transfer;
+    for (final status in statuses) {
+      final at = status.lastSyncedAt;
+      if (!liveNow(status) &&
+          at != null &&
+          (lastSynced == null || at.isBefore(lastSynced))) {
+        lastSynced = at;
+      }
+      error ??= status.lastError;
+      transfer ??= status.transfer;
+    }
+    if (statuses
+        .any((status) => !liveNow(status) && status.lastSyncedAt == null)) {
+      lastSynced = null;
+    }
+    if (allLive) lastSynced = DateTime.now();
+
+    _pushApplication(
+      SyncStatus(
+        phase: phase,
+        ahead: total((status) => status.ahead),
+        behind: total((status) => status.behind),
+        saved: total((status) => status.saved),
+        onMain: total((status) => status.onMain),
+        deadLetters: total((status) => status.deadLetters),
+        transfer: transfer,
+        lastSyncedAt: lastSynced,
+        lastError: error,
+        live: allLive,
+        followed: _followed,
+        followsInSync: _followsInSync,
+        followsLive: _followsLive,
+        followStatuses: _followStatuses,
+        followReportAt: _followReportAt,
+        preparingWorkspaces: _preparingWorkspaces,
+        retryingWorkspaces: _retryingWorkspaces,
+        preparationActivity: _preparationActivity,
+      ),
+    );
+  }
+
+  void _pushApplication(SyncStatus status) {
+    if (_sameStatus(_current, status)) return;
+    _current = status;
+    if (!_application.isClosed) _application.add(status);
+  }
+
+  void _seedApplication() {
+    if (!_application.isClosed) _application.add(_current);
+  }
+
+  void _seedSession(String session) {
+    final controller = _sessionStreams[session];
+    if (controller != null && !controller.isClosed) {
+      controller.add(statusFor(session));
+    }
+  }
+
+  Future<void> close() async {
+    if (!_changes.isClosed) unawaited(_changes.close());
+    final streams = _sessionStreams.values.toList(growable: false);
+    _sessionStreams.clear();
+    for (final stream in streams) {
+      if (!stream.isClosed) unawaited(stream.close());
+    }
+    // A paused UI subscriber may not process the done event until it resumes.
+    // Closing this broadcast stream must not hold reception teardown open.
+    if (!_application.isClosed) unawaited(_application.close());
+  }
+}