@githolon/dsl 0.113.4 → 0.114.0

package/dart/lib/src/sync_status_projection.dart

@@ -46,6 +46,73 @@ enum SyncPhase {
   error
 }
 
+/// The custodian is opening a workspace from verified custody — warming up after a restart,
+/// a cold container or a cloud roll. It is not an error: nothing was refused, nothing is lost,
+/// and the peer asks again at the custodian's own hint. A follow that carries this posture is
+/// "waking up", never "needs attention", until [isStalled] says the wait has run well past what
+/// the custodian promised.
+final class CustodianWarmingPosture {
+  const CustodianWarmingPosture({
+    required this.since,
+    required this.expectedReadyAt,
+    required this.stalledAfter,
+    this.stalled = false,
+  });
+
+  factory CustodianWarmingPosture.fromRuntime(
+    nomos_protocol.CustodianWarming warming,
+  ) =>
+      CustodianWarmingPosture(
+        since: DateTime.fromMillisecondsSinceEpoch(
+            warming.sinceUnixMillis.toInt()),
+        expectedReadyAt: DateTime.fromMillisecondsSinceEpoch(
+            warming.expectedReadyUnixMillis.toInt()),
+        stalledAfter: DateTime.fromMillisecondsSinceEpoch(
+            warming.stalledAfterUnixMillis.toInt()),
+        stalled: warming.stalled,
+      );
+
+  /// When this peer first met the custodian's opening answer in this warming spell.
+  final DateTime since;
+
+  /// When the custodian said it expects to be ready (its latest retry hint).
+  final DateTime expectedReadyAt;
+
+  /// After this moment the warming has run well past the promise and counts as stalled.
+  final DateTime stalledAfter;
+
+  /// The peer had already judged the warming stalled when it reported it.
+  final bool stalled;
+
+  /// Stalled warming should escalate exactly like any other attention state. Judged against
+  /// [now] as well as the peer's report, so a quiet report still escalates on time.
+  bool isStalled(DateTime now) => stalled || !now.isBefore(stalledAfter);
+
+  /// How long the custodian has been warming up.
+  Duration elapsed(DateTime now) {
+    final value = now.difference(since);
+    return value.isNegative ? Duration.zero : value;
+  }
+
+  /// How long until the custodian expects to be ready; zero once that time has passed.
+  Duration remaining(DateTime now) {
+    final value = expectedReadyAt.difference(now);
+    return value.isNegative ? Duration.zero : value;
+  }
+
+  @override
+  bool operator ==(Object other) =>
+      other is CustodianWarmingPosture &&
+      other.since == since &&
+      other.expectedReadyAt == expectedReadyAt &&
+      other.stalledAfter == stalledAfter &&
+      other.stalled == stalled;
+
+  @override
+  int get hashCode =>
+      Object.hash(since, expectedReadyAt, stalledAfter, stalled);
+}
+
 /// The durable Replica Follow's own state, observed without starting a round.
 enum WorkspaceFollowPhase {
   desired,
@@ -74,6 +141,7 @@ final class WorkspaceFollowStatus {
     this.activeEffect,
     this.unsent,
     this.unacknowledged,
+    this.custodianWarming,
   });
 
   factory WorkspaceFollowStatus.fromRuntime(
@@ -131,6 +199,9 @@ final class WorkspaceFollowStatus {
         unsent: report.hasUnsent() ? report.unsent : null,
         unacknowledged:
             report.hasUnacknowledged() ? report.unacknowledged : null,
+        custodianWarming: report.hasCustodianWarming()
+            ? CustodianWarmingPosture.fromRuntime(report.custodianWarming)
+            : null,
       );
 
   final String workspace;
@@ -146,7 +217,20 @@ final class WorkspaceFollowStatus {
   /// whose admission has not yet come back. Null when the live link is not streaming.
   final int? unsent;
   final int? unacknowledged;
+
+  /// Present while the custodian is opening this workspace from verified custody and that is
+  /// the only reason this follow is not yet current. Null for every ordinary error retry.
+  final CustodianWarmingPosture? custodianWarming;
+
   bool get current => phase == WorkspaceFollowPhase.settled && live;
+
+  /// The custodian is warming up and has not yet overrun its promise: calm, not an error.
+  bool isWarming(DateTime now) =>
+      !current && custodianWarming != null && !custodianWarming!.isStalled(now);
+
+  /// The custodian has been warming well past what it promised: escalate as attention.
+  bool isWarmingStalled(DateTime now) =>
+      !current && (custodianWarming?.isStalled(now) ?? false);
 }
 
 /// Disposable UI projection of typed peer-runtime sync observations.
@@ -192,6 +276,14 @@ final class SyncStatus {
   /// The peer's time for its most recent changed follow report.
   final DateTime? followReportAt;
 
+  /// Follows whose custodian is warming up within its promise: calm, not an error.
+  Iterable<WorkspaceFollowStatus> warmingFollows(DateTime now) =>
+      followStatuses.where((follow) => follow.isWarming(now));
+
+  /// Follows whose custodian has been warming well past its promise: attention.
+  Iterable<WorkspaceFollowStatus> stalledWarmingFollows(DateTime now) =>
+      followStatuses.where((follow) => follow.isWarmingStalled(now));
+
   /// Counts of Peer Office preparation observations, not inferred from sync.
   final int preparingWorkspaces;
   final int retryingWorkspaces;
@@ -298,7 +390,8 @@ bool _sameFollows(
         a.attempt != b.attempt ||
         a.activeEffect != b.activeEffect ||
         a.unsent != b.unsent ||
-        a.unacknowledged != b.unacknowledged) return false;
+        a.unacknowledged != b.unacknowledged ||
+        a.custodianWarming != b.custodianWarming) return false;
   }
   return true;
 }

package/dart/lib/src/sync_status_reducer.dart

@@ -42,8 +42,11 @@ SyncStatus reduceSyncCompletion(
   }
   final result = completed.result;
   final receiptIssue = _receiptIssue(result.offerReceipt);
-  final pending =
-      result.stillAhead || result.directOfferDeferred || result.deferred > 0;
+  // A custodian warming up judged nothing: the round is still owed, never settled or failed.
+  final pending = result.stillAhead ||
+      result.directOfferDeferred ||
+      result.deferred > 0 ||
+      result.hasCustodianWarmingRetryAfterMillis();
   final awaitingRemoteDurability = result.stillAhead &&
       !result.directOfferDeferred &&
       !result.reconnectRequired &&

package/dart/lib/src/test_harness.dart

@@ -53,7 +53,10 @@ import 'runtime_v2_transport.dart';
 import 'session_bound.dart' show DomainNotInstalledForSession;
 import 'reception/dart_reception.dart'
     show DartReception, NomosBoundInteraction, NomosSession;
+import 'reception/peer_office_connection.dart' show PeerOfficeConnection;
 import 'testing/test_peer.dart' show NmsTestPeer;
+import 'testing/test_peer_host.dart'
+    show NmsTestPeerHostKind, nmsTestPeerHostVariable;
 
 enum _KernelRuntimeArtifact {
   executable('holon.wasm'),
@@ -325,7 +328,9 @@ class NomosTestHarness {
   /// The local workspace name the law was installed into.
   final String workspace;
 
-  NodeRunnerTransport _transport;
+  /// The Peer Office connection under [reception]: the Node runner, or the Apple native
+  /// host when the local test peer runs there (`NOMOS_TEST_PEER_HOST=native`).
+  PeerOfficeConnection _transport;
   final Directory _workdir;
   final void Function(String line)? _onDiagnostic;
   bool _disposed = false;
@@ -541,14 +546,15 @@ class NomosTestHarness {
         'no lawUsdzPaths — pass the build/<name>.law.usdz `npx githolon compile` emits',
       );
     }
-    final entry = nodeEntry ??
-        await _resolveTestEntry(node, resolveFrom ?? Directory.current.path);
-    final effectiveRuntimeDir = runtimeDir ??
-        Platform.environment['NOMOS_CANDIDATE_RUNTIME'] ??
-        Platform.environment['NOMOS_DART_RUNTIME'] ??
-        Platform.environment['NOMOS_OFFLINE_RUNTIME'] ??
-        await _sourceCandidateRuntime(entry) ??
-        '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+    final hostKind = NmsTestPeerHostKind.selected();
+    final (:entry, :runtimeDirectory) = await _localPeerInputs(
+      hostKind: hostKind,
+      nodeEntry: nodeEntry,
+      runtimeDir: runtimeDir,
+      node: node,
+      resolveFrom: resolveFrom,
+    );
+    final effectiveRuntimeDir = runtimeDirectory;
     final owner = ownerSubject?.trim();
     // THE CALLER DECLARES ITS LANE. Naming an owner IS the application-home lane;
     // the harness no longer re-derives a receiving-group name to recognise one by
@@ -574,18 +580,19 @@ class NomosTestHarness {
         ? 'nms-app-${DateTime.now().microsecondsSinceEpoch.toRadixString(36)}'
         : (workspace ?? 'test-ws');
 
-    Directory? workdir;
-    NodeRunnerTransport? transport;
+    NmsTestPeer? startedPeer;
     final phase = (String m) {
       if (onDiagnostic != null) onDiagnostic('[nomos-test-harness] $m');
     };
+    phase('test peer host: ${hostKind.name} ($nmsTestPeerHostVariable)');
     try {
-      final peer = await _phased(
+      final NmsTestPeer peer = await _phased(
         phase: '1/2: open canonical test peer',
         awaiting: 'Peer Office + filesystem Git custody',
         timeout: phaseTimeout ?? _kSpawnDeadline,
         onDiagnostic: onDiagnostic,
         run: () => NmsTestPeer.start(
+          kind: hostKind,
           entry: entry,
           runtimeDirectory: effectiveRuntimeDir,
           resolveFrom: resolveFrom,
@@ -593,25 +600,26 @@ class NomosTestHarness {
           onDiagnostic: onDiagnostic,
         ),
       );
-      transport = peer.transport;
-      workdir = peer.custody.directory;
+      startedPeer = peer;
+      final workdir = peer.custodyDirectory;
       var plane = peer.reception;
       // An application home is warranted by certificates the founding device signs, so that key is
-      // minted FIRST and the peer is booted to trust it (typed boot configuration) before genesis.
+      // minted FIRST and the peer is made to trust it (typed boot configuration) before genesis.
       protocol.SigningKeyPair? founder;
       if (birthsApplicationHome) {
         founder = await _phased(
-          phase: '1b/2: mint the founding device and boot the peer to trust it',
-          awaiting: 'authorKeygen + peer reboot with --trust-root-public-key',
+          phase: '1b/2: mint the founding device and make the peer trust it',
+          awaiting: hostKind == NmsTestPeerHostKind.node
+              ? 'authorKeygen + peer reboot with --trust-root-public-key'
+              : 'authorKeygen + resident kernel trust-root configuration',
           timeout: phaseTimeout ?? _kSpawnDeadline,
           onDiagnostic: onDiagnostic,
           run: () async {
             final key = await peer.mintFoundingDevice();
-            await peer.reboot(trustRootPublicKey: key.publicKey);
+            await peer.trustFoundingRoot(key.publicKey);
             return key;
           },
         );
-        transport = peer.transport;
         plane = peer.reception;
       }
       // THE OFFICE NAMES THE APPLICATION HOME. The harness holds no copy of the
@@ -1008,7 +1016,7 @@ class NomosTestHarness {
       final harness = NomosTestHarness._(
         plane.session(openWorkspace),
         openWorkspace,
-        transport,
+        peer.transport,
         workdir,
         onDiagnostic,
         [openWorkspace],
@@ -1042,18 +1050,46 @@ class NomosTestHarness {
       return harness;
     } catch (_) {
       // Setup failed — tear down deterministically so nothing is left running or on disk.
-      if (transport != null) {
-        try {
-          await transport.dispose();
-        } catch (_) {}
-      }
       try {
-        await workdir?.delete(recursive: true);
+        await startedPeer?.dispose();
       } catch (_) {}
       rethrow;
     }
   }
 
+  /// The local test peer's inputs for [hostKind]. The Node host needs its runner entry (and may
+  /// take the source checkout's coordinated candidate runtime from it); the native host runs no
+  /// Node, so no entry is resolved for it. Both read the framework controller law from the
+  /// runtime directory.
+  static Future<({String? entry, String runtimeDirectory})> _localPeerInputs({
+    required NmsTestPeerHostKind hostKind,
+    required String? nodeEntry,
+    required String? runtimeDir,
+    required String node,
+    required String? resolveFrom,
+  }) async {
+    final explicitRuntime = runtimeDir ??
+        Platform.environment['NOMOS_CANDIDATE_RUNTIME'] ??
+        Platform.environment['NOMOS_DART_RUNTIME'] ??
+        Platform.environment['NOMOS_OFFLINE_RUNTIME'];
+    final defaultRuntime =
+        '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+    switch (hostKind) {
+      case NmsTestPeerHostKind.node:
+        final entry = nodeEntry ??
+            await _resolveTestEntry(
+                node, resolveFrom ?? Directory.current.path);
+        return (
+          entry: entry,
+          runtimeDirectory: explicitRuntime ??
+              await _sourceCandidateRuntime(entry) ??
+              defaultRuntime,
+        );
+      case NmsTestPeerHostKind.native:
+        return (entry: null, runtimeDirectory: explicitRuntime ?? defaultRuntime);
+    }
+  }
+
   /// A COLOCATED TEST CLUSTER — install MANY workspaces' law offline and connect one SESSION per workspace on
   /// ONE kernel host (one runner, one transport, one [reception]), so a cross-workspace scenario (attested
   /// reads, foreign-source imports) runs in-process with ZERO network. Each workspace has separate real Git
@@ -1101,14 +1137,18 @@ class NomosTestHarness {
         );
       }
     }
-    final entry = nodeEntry ??
-        await _resolveTestEntry(node, resolveFrom ?? Directory.current.path);
-    final effectiveRuntimeDir = runtimeDir ??
-        Platform.environment['NOMOS_CANDIDATE_RUNTIME'] ??
-        Platform.environment['NOMOS_DART_RUNTIME'] ??
-        Platform.environment['NOMOS_OFFLINE_RUNTIME'] ??
-        await _sourceCandidateRuntime(entry) ??
-        '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+    final hostKind = NmsTestPeerHostKind.selected();
+    final (:entry, :runtimeDirectory) = await _localPeerInputs(
+      hostKind: hostKind,
+      nodeEntry: nodeEntry,
+      runtimeDir: runtimeDir,
+      node: node,
+      resolveFrom: resolveFrom,
+    );
+    final effectiveRuntimeDir = runtimeDirectory;
+    onDiagnostic?.call(
+      '[nomos-test-harness] test peer host: ${hostKind.name} ($nmsTestPeerHostVariable)',
+    );
     NmsTestPeer? peer;
     try {
       peer = await _phased(
@@ -1117,6 +1157,7 @@ class NomosTestHarness {
         timeout: phaseTimeout ?? _kSpawnDeadline,
         onDiagnostic: onDiagnostic,
         run: () => NmsTestPeer.start(
+          kind: hostKind,
           entry: entry,
           runtimeDirectory: effectiveRuntimeDir,
           resolveFrom: resolveFrom,
@@ -1153,7 +1194,7 @@ class NomosTestHarness {
         peer!.reception,
         names.first,
         peer.transport,
-        peer.custody.directory,
+        peer.custodyDirectory,
         onDiagnostic,
         names,
         devicePublics: devicePublics,
@@ -1230,6 +1271,14 @@ class NomosTestHarness {
         'NmsApplicationFrameworkCalls; raw framework directive transport is not supported',
       );
     }
+    // The cloud-bound device is the Node peer talking to a test cloud; there is no native lane
+    // for it. Selecting native here is refused, never quietly run on Node.
+    if (NmsTestPeerHostKind.selected() != NmsTestPeerHostKind.node) {
+      throw NomosTestHarnessException(
+        'cloudBound runs only on the Node test peer: unset $nmsTestPeerHostVariable '
+        '(the native host serves the offline ephemeral and cluster harnesses)',
+      );
+    }
     final entry = nodeEntry ??
         await _resolveEntry(node, resolveFrom ?? Directory.current.path);
     final bareUid =
@@ -2069,8 +2118,7 @@ class NomosTestHarness {
                 if (!RegExp(r'^[A-Za-z0-9_-]+$').hasMatch(fixture.workspace)) {
                   throw StateError('Invalid fixture workspace');
                 }
-                final repo =
-                    '${peer.custody.directory.path}/custody/holon-${fixture.workspace}.git';
+                final repo = peer.host.workspaceGitDirectory(fixture.workspace);
                 // `update-ref <new> <old>` is a compare-and-swap, and git reads an
                 // EMPTY <old> as "the ref must not exist". `prior` comes from the
                 // plane's workspace status, which answers '' whenever the workspace
@@ -2170,7 +2218,7 @@ class NomosTestHarness {
     final targets = _applicationConnectedSessions();
     if (targets.remove(home)) targets.insert(0, home);
     await _plane.dispose();
-    await _transport.dispose();
+    await _stopTransport();
 
     _transport = await NodeRunnerTransport.start(
       entry: lane.entry,
@@ -2245,13 +2293,13 @@ class NomosTestHarness {
       );
     }
     try {
-      await _transport.dispose().timeout(
+      await _stopTransport().timeout(
             _phaseTimeout ?? _kOtherDeadline,
             onTimeout: () => throw HarnessPhaseTimeout(
-              phase: 'dispose: stop the node runner',
+              phase: 'dispose: stop the peer host',
               workspace: workspace,
               elapsed: _phaseTimeout ?? _kOtherDeadline,
-              awaiting: 'NodeRunnerTransport.dispose',
+              awaiting: 'test peer host stop',
             ),
           );
     } catch (e) {
@@ -2267,6 +2315,24 @@ class NomosTestHarness {
     if (f != null) f('[nomos-test-harness] phase dispose done');
   }
 
+  /// Stop whatever hosts [_transport]: the local test peer's host when this harness owns one
+  /// (its connection may have been replaced by a restart), otherwise the cloud-bound Node runner.
+  Future<void> _stopTransport() async {
+    final peer = _testPeer;
+    if (peer != null && identical(peer.transport, _transport)) {
+      await peer.host.stop();
+      return;
+    }
+    final transport = _transport;
+    if (transport is NodeRunnerTransport) {
+      await transport.dispose();
+      return;
+    }
+    throw StateError(
+      'the harness connection ${transport.runtimeType} has no owner to stop it',
+    );
+  }
+
   void _diag(String line) {
     final f = _onDiagnostic;
     if (f != null) {