@githolon/dsl 0.108.6 → 0.110.0

package/dart/lib/src/reception/progress_desk.dart

@@ -0,0 +1,267 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:typed_data';
+
+import 'package:nomos_types/nomos_kernel_protocol.dart' as nomos_protocol;
+
+import '../sync_status_projection.dart' show TransferProgress;
+
+/// One typed, authority-free observation of peer work.
+enum NomosSpanPhase { begin, end }
+
+final class NomosSpanEvent {
+  const NomosSpanEvent({
+    required this.phase,
+    required this.id,
+    required this.name,
+    this.traceId,
+    this.session,
+    this.workspace,
+    this.track,
+    this.kind,
+    this.startedAtMillis,
+    this.endedAtMillis,
+    this.head,
+    this.attempt,
+    this.elapsedMillis,
+    this.retryAfterMillis,
+    this.attributes = const [],
+  });
+
+  factory NomosSpanEvent.fromRuntime(
+    nomos_protocol.RuntimeSpan span, {
+    String? session,
+  }) {
+    Object? attribute(String name) {
+      for (final value in span.attributes) {
+        if (value.name != name) continue;
+        return switch (value.whichValue()) {
+          nomos_protocol.DiagnosticAttribute_Value.stringValue =>
+            value.stringValue,
+          nomos_protocol.DiagnosticAttribute_Value.integerValue =>
+            value.integerValue.toInt(),
+          nomos_protocol.DiagnosticAttribute_Value.doubleValue =>
+            value.doubleValue,
+          nomos_protocol.DiagnosticAttribute_Value.booleanValue =>
+            value.booleanValue,
+          nomos_protocol.DiagnosticAttribute_Value.bytesValue =>
+            Uint8List.fromList(value.bytesValue),
+          nomos_protocol.DiagnosticAttribute_Value.notSet => null,
+        };
+      }
+      return null;
+    }
+
+    String? text(String name) {
+      final value = attribute(name);
+      return value == null ? null : value.toString();
+    }
+
+    int? integer(String name) {
+      final value = attribute(name);
+      return value is num
+          ? value.toInt()
+          : int.tryParse(value?.toString() ?? '');
+    }
+
+    final started = span.startedUnixNanos.toInt() ~/ 1000000;
+    final duration = span.durationNanos.toInt() ~/ 1000000;
+    return NomosSpanEvent(
+      phase: NomosSpanPhase.end,
+      id: text('id') ?? base64Url.encode(span.spanId).replaceAll('=', ''),
+      name: span.name,
+      traceId: span.traceId
+          .map((byte) => byte.toRadixString(16).padLeft(2, '0'))
+          .join(),
+      session: session,
+      workspace: text('workspace') ?? session,
+      track: text('track'),
+      kind: text('kind'),
+      startedAtMillis: started,
+      endedAtMillis: started + duration,
+      head: text('head'),
+      attempt: integer('attempt'),
+      elapsedMillis: integer('elapsedMs'),
+      retryAfterMillis: integer('retryAfterMs'),
+      attributes: List.unmodifiable(span.attributes),
+    );
+  }
+
+  final NomosSpanPhase phase;
+  final String id;
+  final String name;
+
+  /// The peer's causal trace identity. It is metadata, never a custody identity.
+  final String? traceId;
+  final String? session;
+  final String? workspace;
+  final String? track;
+  final String? kind;
+  final int? startedAtMillis;
+  final int? endedAtMillis;
+  final String? head;
+  final int? attempt;
+  final int? elapsedMillis;
+  final int? retryAfterMillis;
+  final List<nomos_protocol.DiagnosticAttribute> attributes;
+}
+
+enum KernelProgressOperation { unspecified, restoreMain }
+
+enum KernelProgressPhase {
+  unspecified,
+  checkCustody,
+  readChain,
+  initializeEngine,
+  readTimeline,
+  hydrateLaw,
+  recoveryPrescan,
+  verifyIntents,
+  promoteCustody,
+  rebuildFrontier,
+  complete,
+}
+
+enum KernelProgressUnit { unspecified, intent, lawPackage }
+
+enum KernelLawHydrationStep {
+  unspecified,
+  readClosure,
+  composeStage,
+  deriveSchemas,
+  loadPolicyShell,
+  packageComplete,
+}
+
+/// Typed, authority-free progress from a long-running kernel operation.
+final class KernelProgress {
+  const KernelProgress({
+    required this.sequence,
+    required this.operation,
+    required this.phase,
+    required this.completed,
+    required this.total,
+    required this.unit,
+    required this.terminal,
+    required this.lawHydrationStep,
+    required this.lawPackageSha256,
+    required this.hostObservedElapsedMicros,
+    required this.hostObservedPhaseElapsedMicros,
+    required this.kernelAllocatorLiveBytes,
+    required this.kernelAllocatorPeakBytes,
+    required this.processResidentBytes,
+    required this.processPeakResidentBytes,
+  });
+
+  final int sequence;
+  final KernelProgressOperation operation;
+  final KernelProgressPhase phase;
+  final int completed;
+  final int total;
+  final KernelProgressUnit unit;
+  final bool terminal;
+  final KernelLawHydrationStep lawHydrationStep;
+  final String lawPackageSha256;
+  final int hostObservedElapsedMicros;
+  final int hostObservedPhaseElapsedMicros;
+  final int kernelAllocatorLiveBytes;
+  final int kernelAllocatorPeakBytes;
+  final int processResidentBytes;
+  final int processPeakResidentBytes;
+
+  int get unaccountedResidentBytes {
+    final remainder = processResidentBytes - kernelAllocatorLiveBytes;
+    return remainder > 0 ? remainder : 0;
+  }
+
+  double? get fraction =>
+      (total <= 0) ? null : (completed / total).clamp(0.0, 1.0);
+
+  factory KernelProgress.fromRuntime(
+    nomos_protocol.KernelProgressObserved observed,
+  ) {
+    final snapshot = observed.snapshot;
+    return KernelProgress(
+      sequence: snapshot.sequence.toInt(),
+      operation: snapshot.operation.value == 1
+          ? KernelProgressOperation.restoreMain
+          : KernelProgressOperation.unspecified,
+      phase: switch (snapshot.phase.value) {
+        1 => KernelProgressPhase.checkCustody,
+        2 => KernelProgressPhase.readChain,
+        3 => KernelProgressPhase.initializeEngine,
+        4 => KernelProgressPhase.readTimeline,
+        5 => KernelProgressPhase.hydrateLaw,
+        6 => KernelProgressPhase.recoveryPrescan,
+        7 => KernelProgressPhase.verifyIntents,
+        8 => KernelProgressPhase.promoteCustody,
+        9 => KernelProgressPhase.rebuildFrontier,
+        10 => KernelProgressPhase.complete,
+        _ => KernelProgressPhase.unspecified,
+      },
+      completed: snapshot.completedUnits.toInt(),
+      total: snapshot.totalUnits.toInt(),
+      unit: switch (snapshot.unit.value) {
+        1 => KernelProgressUnit.intent,
+        2 => KernelProgressUnit.lawPackage,
+        _ => KernelProgressUnit.unspecified,
+      },
+      terminal: snapshot.terminal,
+      lawHydrationStep: switch (snapshot.lawHydrationStep.value) {
+        1 => KernelLawHydrationStep.readClosure,
+        2 => KernelLawHydrationStep.composeStage,
+        3 => KernelLawHydrationStep.deriveSchemas,
+        4 => KernelLawHydrationStep.loadPolicyShell,
+        5 => KernelLawHydrationStep.packageComplete,
+        _ => KernelLawHydrationStep.unspecified,
+      },
+      lawPackageSha256: snapshot.lawPackageSha256,
+      hostObservedElapsedMicros: observed.hostObservedElapsedMicros.toInt(),
+      hostObservedPhaseElapsedMicros:
+          observed.hostObservedPhaseElapsedMicros.toInt(),
+      kernelAllocatorLiveBytes: snapshot.allocatorLiveBytes.toInt(),
+      kernelAllocatorPeakBytes: snapshot.allocatorPeakBytes.toInt(),
+      processResidentBytes: observed.processResidentBytes.toInt(),
+      processPeakResidentBytes: observed.processPeakResidentBytes.toInt(),
+    );
+  }
+}
+
+/// Reception's observability desk. It owns only ephemeral subscriptions and a
+/// bounded recent-span cache; no custody, authority, or application state.
+final class ReceptionProgressDesk {
+  final StreamController<NomosSpanEvent> _spans =
+      StreamController<NomosSpanEvent>.broadcast();
+  final StreamController<TransferProgress> _transfers =
+      StreamController<TransferProgress>.broadcast();
+  final StreamController<KernelProgress> _kernel =
+      StreamController<KernelProgress>.broadcast();
+  final List<NomosSpanEvent> _recentSpans = [];
+
+  Stream<NomosSpanEvent> get spans => _spans.stream;
+  Stream<TransferProgress> get transfers => _transfers.stream;
+  Stream<KernelProgress> get kernel => _kernel.stream;
+  List<NomosSpanEvent> get recentSpans => List.unmodifiable(_recentSpans);
+
+  void observeSpan(NomosSpanEvent event) {
+    _recentSpans.add(event);
+    if (_recentSpans.length > 400) {
+      _recentSpans.removeRange(0, _recentSpans.length - 400);
+    }
+    if (!_spans.isClosed) _spans.add(event);
+  }
+
+  void observeTransfer(TransferProgress event) {
+    if (!_transfers.isClosed) _transfers.add(event);
+  }
+
+  void observeKernel(KernelProgress event) {
+    if (!_kernel.isClosed) _kernel.add(event);
+  }
+
+  Future<void> close() async {
+    if (!_spans.isClosed) await _spans.close();
+    if (!_transfers.isClosed) await _transfers.close();
+    if (!_kernel.isClosed) await _kernel.close();
+  }
+}

package/dart/lib/src/reception/reception_contract.dart

@@ -0,0 +1,11 @@
+import '../application_framework_calls.dart' show NmsApplicationFrameworkCalls;
+import 'reception_session.dart' show NmsReceptionSession;
+
+/// The static, compiler-generated vocabulary Reception needs to expose one
+/// tenant application. It owns no kernel, custody, credentials, timers, sync,
+/// placement, or mutable application state.
+abstract interface class NmsReceptionContract<TApplication> {
+  NmsApplicationFrameworkCalls get frameworkCalls;
+
+  Future<TApplication> receive(NmsReceptionSession session);
+}

package/dart/lib/src/reception/reception_session.dart

@@ -0,0 +1,284 @@
+import '../application_framework_calls.dart' show NmsApplicationFrameworkCalls;
+import '../application_status.dart'
+    show ApplicationStatus, ApplicationStatusPhase;
+import '../nms_generated_runtime.dart'
+    show
+        Invitation,
+        NmsInternalInvitations,
+        DartReception,
+        NomosOperationReceipt,
+        NomosSession,
+        Recipient,
+        SyncPhase,
+        SyncStatus;
+import '../peer_application_streams.dart'
+    show NmsPeerApplicationStreams, NmsPeerApplicationStreamView;
+import '../workspace_open_progress.dart' show ApplicationWorkspaceOpenProgress;
+
+/// Identity already established by Peer Office for a Reception session.
+final class NmsReceptionUser {
+  const NmsReceptionUser({
+    required this.actor,
+    required this.identityId,
+    required this.identityAddress,
+  });
+
+  final String actor;
+  final String identityId;
+  final String identityAddress;
+}
+
+/// One generated invitation route. Generated code supplies only typed law
+/// identities and queries; Peer Office owns the ceremony.
+final class NmsReceptionInvitationPolicy {
+  const NmsReceptionInvitationPolicy({
+    required this.domain,
+    required this.domainHash,
+    required this.redeem,
+    required this.pending,
+  });
+
+  final String domain;
+  final String domainHash;
+  final String redeem;
+  final Future<List<NmsReceptionInvitationMatch>> Function(String address)
+      pending;
+}
+
+final class NmsReceptionInvitationMatch {
+  const NmsReceptionInvitationMatch({
+    required this.orderId,
+    required this.object,
+    required this.relation,
+  });
+
+  final String orderId;
+  final String object;
+  final String relation;
+}
+
+/// The complete Reception session generated Dart facades may receive.
+/// It contains no cloud URL, credential store, custody store, kernel,
+/// placement policy, sync scheduler, recovery policy, or law lifecycle.
+abstract interface class NmsReceptionSession {
+  NomosSession get desk;
+  NmsReceptionUser get user;
+  NmsPeerApplicationStreams get streams;
+
+  ApplicationStatus get currentStatus;
+  Future<void> whenCurrent({required Duration timeout});
+
+  ApplicationStatus get applicationStatus;
+  Future<void> whenApplicationCurrent({required Duration timeout});
+
+  NomosOperationReceipt? get creationReceipt;
+
+  Recipient<TSubject> recipient<TSubject>(String uid);
+  Future<Invitation<TSubject>> createInvitation<TSubject>();
+  Future<void> redeemInvitation<TSubject>({
+    required String link,
+    required List<NmsReceptionInvitationPolicy> policies,
+    required NmsApplicationFrameworkCalls frameworkCalls,
+  });
+
+  /// The workspace a keyed birth addresses, as THE OFFICE names it. Generated
+  /// facades ask; they never hash `(namespace, key)` themselves — that function
+  /// is law, and a client-local copy of it drifts silently.
+  Future<String> keyedBirthWorkspace({
+    required String namespace,
+    required String key,
+  });
+
+  Future<List<String>> activeChildWorkspaces({required String namespace});
+
+  /// Fetch [workspace] onto this device now, reading and opening nothing: the
+  /// office names its placement and that placement's Replica Follow mounts the
+  /// provider's head in the background. Completes once the follow exists.
+  Future<void> fetchWorkspace(String workspace);
+
+  Future<NmsReceptionSession> follow(String workspace);
+  Future<void> close();
+}
+
+typedef NmsCreateInvitation = Future<Invitation<T>> Function<T>(
+  NomosSession session,
+);
+typedef NmsRedeemInvitation = Future<void> Function<T>(
+  NomosSession session, {
+  required NmsReceptionUser user,
+  required String link,
+  required List<NmsReceptionInvitationPolicy> policies,
+  required NmsApplicationFrameworkCalls frameworkCalls,
+});
+
+/// A thin view over a Peer Office session. It owns no lifecycle state: status,
+/// lineage and child handles are read from the supplied session, while optional
+/// ceremonies are injected as desk capabilities by the platform composition
+/// root.
+final class NmsReceptionSessionView implements NmsReceptionSession {
+  NmsReceptionSessionView({
+    required NomosSession desk,
+    required this.user,
+    this.createInvitationCapability,
+    this.redeemInvitationCapability,
+    this.watchOpenProgressCapability,
+    this.closeCapability,
+  })  : desk = desk,
+        streams = NmsPeerApplicationStreamView(
+          session: desk,
+          statusProjection: _applicationStatus,
+          workspaceOpenProgressSource: watchOpenProgressCapability,
+        );
+
+  @override
+  final NomosSession desk;
+  @override
+  final NmsReceptionUser user;
+  @override
+  final NmsPeerApplicationStreams streams;
+  final NmsCreateInvitation? createInvitationCapability;
+  final NmsRedeemInvitation? redeemInvitationCapability;
+  final Stream<ApplicationWorkspaceOpenProgress> Function(String workspace)?
+      watchOpenProgressCapability;
+  final Future<void> Function()? closeCapability;
+
+  @override
+  ApplicationStatus get currentStatus => _applicationStatus(desk.currentStatus);
+
+  @override
+  Future<void> whenCurrent({required Duration timeout}) =>
+      _whenCurrent(desk, timeout);
+
+  @override
+  ApplicationStatus get applicationStatus =>
+      _applicationStatus(desk.parent.currentStatus);
+
+  @override
+  Future<void> whenApplicationCurrent({required Duration timeout}) =>
+      _whenCurrent(desk.parent, timeout);
+
+  @override
+  NomosOperationReceipt? get creationReceipt =>
+      desk.nomosInternalWorkspaceCreationReceipt();
+
+  @override
+  Recipient<TSubject> recipient<TSubject>(String uid) {
+    final value = uid.trim();
+    if (value.isEmpty) {
+      throw ArgumentError.value(uid, 'uid', 'must not be empty');
+    }
+    return NmsInternalInvitations.recipient<TSubject>('user:$value');
+  }
+
+  @override
+  Future<Invitation<TSubject>> createInvitation<TSubject>() {
+    final capability = createInvitationCapability;
+    if (capability == null) {
+      throw UnsupportedError('This Reception session has no invitation desk');
+    }
+    return capability<TSubject>(desk);
+  }
+
+  @override
+  Future<void> redeemInvitation<TSubject>({
+    required String link,
+    required List<NmsReceptionInvitationPolicy> policies,
+    required NmsApplicationFrameworkCalls frameworkCalls,
+  }) {
+    final capability = redeemInvitationCapability;
+    if (capability == null) {
+      throw UnsupportedError('This Reception session has no invitation desk');
+    }
+    return capability<TSubject>(
+      desk,
+      user: user,
+      link: link,
+      policies: policies,
+      frameworkCalls: frameworkCalls,
+    );
+  }
+
+  @override
+  Future<String> keyedBirthWorkspace({
+    required String namespace,
+    required String key,
+  }) =>
+      desk.nmsKeyedBirthWorkspace(namespace: namespace, key: key);
+
+  @override
+  Future<void> fetchWorkspace(String workspace) =>
+      desk.nmsFetchWorkspace(workspace);
+
+  @override
+  Future<List<String>> activeChildWorkspaces(
+      {required String namespace}) async {
+    // The namespace rides the paper: the office owns the namespace-to-workspace-name
+    // relation and selects the active children itself. Reading a `<namespace>-`
+    // prefix here would be a second, client-local copy of that law fact.
+    final children =
+        await desk.nomosFrameworkChildWorkspaces(namespace: namespace);
+    return children.map((child) => child.workspace).toList(growable: false);
+  }
+
+  @override
+  Future<NmsReceptionSession> follow(String workspace) async {
+    final child = await desk.bindWorkspace(workspace);
+    return NmsReceptionSessionView(
+      desk: child,
+      user: user,
+      createInvitationCapability: createInvitationCapability,
+      redeemInvitationCapability: redeemInvitationCapability,
+      watchOpenProgressCapability: watchOpenProgressCapability,
+      closeCapability: closeCapability,
+    );
+  }
+
+  @override
+  Future<void> close() => closeCapability?.call() ?? Future<void>.value();
+}
+
+ApplicationStatus _applicationStatus(SyncStatus status) => ApplicationStatus(
+      phase: switch (status.presentationPhase) {
+        SyncPhase.checking => ApplicationStatusPhase.checking,
+        SyncPhase.idle => ApplicationStatusPhase.current,
+        SyncPhase.syncing => ApplicationStatusPhase.saving,
+        SyncPhase.awaitingRemoteDurability =>
+          ApplicationStatusPhase.awaitingRemoteDurability,
+        SyncPhase.transferring => ApplicationStatusPhase.receiving,
+        SyncPhase.behind => ApplicationStatusPhase.catchingUp,
+        SyncPhase.offline => ApplicationStatusPhase.offline,
+        SyncPhase.error => ApplicationStatusPhase.attention,
+      },
+      localChanges: status.ahead,
+      availableChanges: status.behind,
+      savedChanges: status.saved,
+      acceptedChanges: status.onMain,
+      decisionsNeeded: status.deadLetters,
+      receivedBytes: status.transfer?.received,
+      totalBytes: status.transfer?.total,
+      lastUpdatedAt: status.lastSyncedAt,
+      message: status.lastError,
+      live: status.live,
+      followedWorkspaces: status.followed,
+      workspacesInSync: status.followsInSync,
+      workspacesLive: status.followsLive,
+      workspaceFollows: status.followStatuses,
+      followReportAt: status.followReportAt,
+      preparingWorkspaces: status.preparingWorkspaces,
+      retryingWorkspaces: status.retryingWorkspaces,
+      preparationActivity: status.preparationActivity,
+    );
+
+Future<void> _whenCurrent(DartReception application, Duration timeout) async {
+  final initial = _applicationStatus(application.currentStatus);
+  if (initial.isCurrent) return;
+  if (initial.phase == ApplicationStatusPhase.attention) {
+    throw StateError(initial.message ?? 'This workspace needs attention');
+  }
+  await application.syncStatus.map(_applicationStatus).firstWhere((status) {
+    if (status.phase == ApplicationStatusPhase.attention) {
+      throw StateError(status.message ?? 'This workspace needs attention');
+    }
+    return status.isCurrent;
+  }).timeout(timeout);
+}

package/dart/lib/src/reception/sync_diagnostics.dart

@@ -0,0 +1,26 @@
+import '../sync_status_projection.dart';
+
+/// A view of an existing session, not an inventory of all local Git custody.
+final class WorkspaceSyncObservation {
+  const WorkspaceSyncObservation({
+    required this.session,
+    required this.workspace,
+    required this.status,
+  });
+
+  final String session;
+  final String workspace;
+  final SyncStatus status;
+}
+
+/// Fixed Reception capability. No generated facade, timer, workspace opening,
+/// credentials, or independently maintained status map belongs here.
+final class ReceptionSyncDiagnostics {
+  const ReceptionSyncDiagnostics({
+    required this.read,
+    required this.changes,
+  });
+
+  final List<WorkspaceSyncObservation> Function() read;
+  final Stream<void> changes;
+}