@githolon/dsl 0.108.6 → 0.110.0

package/dart/lib/src/testing/test_custody.dart

@@ -0,0 +1,66 @@
+@internal
+library;
+
+import 'dart:io';
+
+import 'package:meta/meta.dart' show internal;
+
+/// Physical custody owned by a test peer.
+///
+/// It is an ordinary directory containing bare Git repositories. The test
+/// harness may choose its lifetime, but never serializes the repositories into
+/// a private snapshot or asks Dart to interpret their contents.
+@internal
+final class NmsTestCustody {
+  NmsTestCustody._(this.directory);
+
+  final Directory directory;
+
+  static Future<NmsTestCustody> create(
+          [String prefix = 'nomos-test-peer-']) async =>
+      NmsTestCustody._(await Directory.systemTemp.createTemp(prefix));
+
+  List<String> processArguments(
+    String runtimeDirectory, {
+    String? trustRootPublicKey,
+  }) =>
+      <String>[
+        '--runtime-bundle=$runtimeDirectory',
+        if (trustRootPublicKey != null)
+          '--trust-root-public-key=$trustRootPublicKey',
+        '--custody=${directory.path}',
+        if (Platform.environment['NOMOS_TEST_DIAGNOSTICS'] == '1')
+          '--trace=frames',
+      ];
+
+  /// Provision the platform-owned empty Git custody into which the one
+  /// parentless genesis offer may write. This is fixture plumbing, not an
+  /// application/session lifecycle operation.
+  Future<void> provisionWorkspace(String workspace) async {
+    if (!RegExp(r'^[A-Za-z0-9._-]{1,160}$').hasMatch(workspace)) {
+      throw ArgumentError.value(workspace, 'workspace', 'is not a safe workspace name');
+    }
+    final repository = Directory('${directory.path}/custody/holon-$workspace.git');
+    if (await repository.exists()) return;
+    await repository.create(recursive: true);
+    Future<void> git(List<String> arguments) async {
+      final result = await Process.run('git', arguments);
+      if (result.exitCode != 0) {
+        throw StateError(
+          'git ${arguments.join(' ')} failed: ${result.stderr}',
+        );
+      }
+    }
+    await git(<String>['init', '--bare', '--quiet', repository.path]);
+    await git(<String>[
+      '--git-dir', repository.path, 'config', 'http.receivepack', 'true',
+    ]);
+    await git(<String>[
+      '--git-dir', repository.path, 'config', 'http.uploadpack', 'true',
+    ]);
+  }
+
+  Future<void> dispose() async {
+    if (await directory.exists()) await directory.delete(recursive: true);
+  }
+}

package/dart/lib/src/testing/test_peer.dart

@@ -0,0 +1,328 @@
+@internal
+library;
+
+import 'dart:io';
+import 'dart:convert' show base64Encode;
+import 'dart:math';
+import 'dart:typed_data';
+
+import 'package:fixnum/fixnum.dart' show Int64;
+import 'package:meta/meta.dart' show internal;
+import 'package:nomos_types/nomos_kernel_protocol.dart' as protocol;
+
+import '../node_runner_transport.dart';
+import '../reception/dart_reception.dart';
+import 'test_custody.dart';
+
+@internal
+final class NmsInstalledTestWorkspace {
+  const NmsInstalledTestWorkspace({
+    required this.workspace,
+    required this.controllerHash,
+    required this.lawHashes,
+    required this.deviceKey,
+    required this.domainKeys,
+  });
+
+  final String workspace;
+  final String controllerHash;
+  final List<String> lawHashes;
+  final protocol.SigningKeyPair deviceKey;
+  final Set<String> domainKeys;
+}
+
+/// A canonical Peer Office hosted by the Node test Platform Shell.
+///
+/// This class owns fixture setup only. Every operation crosses Runtime v2 and
+/// the kernel's generated Protobuf ABI; it contains no workspace lifecycle,
+/// USDA parser, generic payload map or alternate admission path.
+@internal
+final class NmsTestPeer {
+  NmsTestPeer._({
+    required this.transport,
+    required this.reception,
+    required this.custody,
+    required this.runtimeDirectory,
+    required String entry,
+    required String node,
+    String? resolveFrom,
+    void Function(String line)? onDiagnostic,
+  })  : _entry = entry,
+        _node = node,
+        _resolveFrom = resolveFrom,
+        _onDiagnostic = onDiagnostic;
+
+  /// The live process transport; replaced by [reboot].
+  NodeRunnerTransport transport;
+
+  /// Reception over [transport]; replaced by [reboot].
+  DartReception reception;
+  final NmsTestCustody custody;
+  final String runtimeDirectory;
+  final String _entry;
+  final String _node;
+  final String? _resolveFrom;
+  final void Function(String line)? _onDiagnostic;
+  final Random _random = Random.secure();
+  int _requestSequence = 0;
+  int _authoringSequence = 0;
+
+  static Future<NmsTestPeer> start({
+    required String entry,
+    required String runtimeDirectory,
+    String node = 'node',
+    String? resolveFrom,
+    void Function(String line)? onDiagnostic,
+  }) async {
+    final custody = await NmsTestCustody.create();
+    NodeRunnerTransport? transport;
+    try {
+      transport = await NodeRunnerTransport.start(
+        entry: entry,
+        resolveFrom: resolveFrom,
+        node: node,
+        arguments: custody.processArguments(runtimeDirectory),
+        onDiagnostic: onDiagnostic,
+      );
+      final reception = DartReception(transport);
+      await reception.ready;
+      return NmsTestPeer._(
+        transport: transport,
+        reception: reception,
+        custody: custody,
+        runtimeDirectory: runtimeDirectory,
+        entry: entry,
+        node: node,
+        resolveFrom: resolveFrom,
+        onDiagnostic: onDiagnostic,
+      );
+    } catch (_) {
+      await transport?.dispose();
+      await custody.dispose();
+      rethrow;
+    }
+  }
+
+  protocol.AuthoringOptions _authoring(String actor) {
+    _authoringSequence += 1;
+    return protocol.AuthoringOptions(
+      actor: actor,
+      rng: List<double>.generate(64, (_) => _random.nextDouble()),
+      deferProjection: false,
+      spans: true,
+      sequence: Int64(_authoringSequence),
+      clock: protocol.CapturedClock(
+        physicalMillis: Int64(DateTime.now().toUtc().millisecondsSinceEpoch),
+        logical: 0,
+        replica: Int64(7),
+      ),
+    );
+  }
+
+  Future<protocol.CallResponse> _kernel(
+    String session,
+    protocol.CallRequest request,
+  ) async {
+    final response = await transport.callKernel(
+      session: session,
+      request: request,
+      credentialUse: protocol.CredentialUse.CREDENTIAL_USE_NONE,
+    );
+    if (response.hasFailure()) {
+      throw StateError('${response.failure.code}: ${response.failure.message}');
+    }
+    return response;
+  }
+
+  Future<protocol.LawPackageInspection> _inspectLaw(
+    Uint8List bytes,
+    String label,
+  ) async {
+    final id = Int64(++_requestSequence);
+    final response = await transport.invokeRuntime(
+      protocol.RuntimeRequest(
+        protocolVersion: 2,
+        requestId: id,
+        inspectLawPackage: protocol.InspectLawPackageRequest(
+          lawUsdz: bytes,
+          label: label,
+        ),
+      ),
+    );
+    if (response.hasFailure()) {
+      throw StateError('${response.failure.code}: ${response.failure.message}');
+    }
+    if (!response.hasLawPackageInspection() ||
+        response.lawPackageInspection.identity.isEmpty) {
+      throw StateError(
+        'Peer Office returned ${response.whichOutcome().name} while inspecting $label',
+      );
+    }
+    return response.lawPackageInspection;
+  }
+
+  /// Mint a founding device key on a scratch session BEFORE any custody exists, so the peer can be
+  /// booted to trust it (typed boot configuration) ahead of the genesis it will sign.
+  Future<protocol.SigningKeyPair> mintFoundingDevice() async {
+    final scratch = 'nms-founder-${_random.nextInt(1 << 30).toRadixString(36)}';
+    await reception.bindSession(
+      workspace: scratch,
+      session: scratch,
+    );
+    return reception.session(scratch).authorKeygen();
+  }
+
+  Future<NmsInstalledTestWorkspace> installWorkspace({
+    required String workspace,
+    required List<String> lawUsdzPaths,
+    String installedBy = 'nomos-test-harness',
+    protocol.SigningKeyPair? deviceKey,
+  }) async {
+    if (lawUsdzPaths.isEmpty) {
+      throw ArgumentError.value(
+          lawUsdzPaths, 'lawUsdzPaths', 'must not be empty');
+    }
+    await custody.provisionWorkspace(workspace);
+    await reception.bindSession(
+      workspace: workspace,
+      session: workspace,
+    );
+    if (deviceKey != null) {
+      await reception.session(workspace).refreshCredentials(
+            authorSecret: base64Encode(deviceKey.secret),
+          );
+    }
+
+    final controller = File('$runtimeDirectory/nomos.law.usdz');
+    if (!controller.existsSync()) {
+      throw StateError('test runtime has no ${controller.path}');
+    }
+    final initialized = await _kernel(
+      workspace,
+      protocol.CallRequest(
+        protocolVersion: 1,
+        requestId: '$workspace:initialize:${++_requestSequence}',
+        offer: protocol.OfferRequest(
+          genesis: protocol.GenesisOffer(),
+          lawUsdz: await controller.readAsBytes(),
+          authoring: _authoring(installedBy),
+        ),
+      ),
+    );
+    if (!initialized.hasOffer() || !initialized.offer.hasAdmitted()) {
+      throw StateError(
+        'kernel returned ${initialized.whichOutcome().name} for workspace genesis',
+      );
+    }
+    final controllerHash = initialized.offer.admitted.installedLawHash;
+    if (controllerHash.isEmpty) {
+      throw StateError(
+          'genesis offer did not return its installed controller identity');
+    }
+
+    final hashes = <String>[];
+    final domainKeys = <String>{};
+    for (final path in lawUsdzPaths) {
+      final file = File(path);
+      if (!file.existsSync() || !path.endsWith('.law.usdz')) {
+        throw StateError('compiled law archive is missing: $path');
+      }
+      final bytes = await file.readAsBytes();
+      final inspection = await _inspectLaw(bytes, file.uri.pathSegments.last);
+      final offered = await _kernel(
+        workspace,
+        protocol.CallRequest(
+          protocolVersion: 1,
+          requestId: '$workspace:install:${++_requestSequence}',
+          offer: protocol.OfferRequest(
+            modelLifecycle: protocol.ModelLifecycleIntent(
+              operation: protocol
+                  .ModelLifecycleOperation.MODEL_LIFECYCLE_OPERATION_INSTALL,
+              installedBy: installedBy,
+            ),
+            authoring: _authoring(installedBy),
+            lawUsdz: bytes,
+            controllerLawHash: controllerHash,
+          ),
+        ),
+      );
+      if (!offered.hasOffer() || !offered.offer.hasAdmitted()) {
+        final outcome = offered.hasOffer()
+            ? offered.offer.whichOutcome().name
+            : offered.whichOutcome().name;
+        throw StateError('kernel refused installation of $path: $outcome');
+      }
+      hashes.add(inspection.identity);
+      domainKeys.addAll(inspection.domainKeys);
+    }
+
+    final founding =
+        deviceKey ?? await reception.session(workspace).authorKeygen();
+    await reception.session(workspace).refreshCredentials(
+          authorSecret: base64Encode(founding.secret),
+        );
+    return NmsInstalledTestWorkspace(
+      workspace: workspace,
+      controllerHash: controllerHash,
+      lawHashes: List.unmodifiable(hashes),
+      deviceKey: founding,
+      domainKeys: Set.unmodifiable(domainKeys),
+    );
+  }
+
+  /// Reboot the peer process on the SAME Git custody with [trustRootPublicKey] as its typed
+  /// boot configuration, then reopen every workspace this peer installed. The trust root is boot
+  /// configuration of the shell, never a kernel variant: a ceremony that signs with a founding
+  /// device key first boots the peer to trust that key.
+  Future<void> reboot({
+    required List<int> trustRootPublicKey,
+    Map<String, String> authorSecrets = const {},
+    Future<void> Function()? arrangeStoppedCustody,
+  }) async {
+    if (trustRootPublicKey.length != 32) {
+      throw ArgumentError.value(
+        trustRootPublicKey.length,
+        'trustRootPublicKey',
+        'must be a 32-byte public key',
+      );
+    }
+    await reception.dispose();
+    await transport.dispose();
+    await arrangeStoppedCustody?.call();
+    final restarted = await NodeRunnerTransport.start(
+      entry: _entry,
+      resolveFrom: _resolveFrom,
+      node: _node,
+      arguments: custody.processArguments(
+        runtimeDirectory,
+        trustRootPublicKey: base64Encode(trustRootPublicKey),
+      ),
+      onDiagnostic: _onDiagnostic,
+    );
+    final reopened = DartReception(restarted);
+    await reopened.ready;
+    transport = restarted;
+    reception = reopened;
+    for (final entry in authorSecrets.entries) {
+      await reception.bindSession(
+        workspace: entry.key,
+        session: entry.key,
+      );
+      await reception.session(entry.key).refreshCredentials(
+            authorSecret: entry.value,
+          );
+    }
+  }
+
+  Future<void> dispose() async {
+    try {
+      await reception.dispose();
+    } finally {
+      try {
+        await transport.dispose();
+      } finally {
+        await custody.dispose();
+      }
+    }
+  }
+}

package/dart/lib/src/typed_watch_registry.dart

@@ -0,0 +1,169 @@
+import 'dart:async';
+
+import 'package:nomos_types/nomos_kernel_protocol.dart' as nomos_protocol;
+import 'package:nomos_types/nomos_types.dart'
+    show NomosErrorInfo, NomosUnavailable, nomosErrorFromInfo;
+
+import 'replica_readiness.dart' show NmsReplicaWake;
+
+final class NmsTypedWatchHandle<T> {
+  const NmsTypedWatchHandle({required this.id, required this.stream});
+
+  final String id;
+  final Stream<T> stream;
+}
+
+/// Correlates generated Runtime v2 watch events with Dart stream listeners.
+/// It neither polls nor evaluates a query; the peer runtime owns both.
+final class NmsTypedWatchRegistry {
+  /// [synced] names each workspace whose sync round just completed; a watch
+  /// waiting for its copy registers at that moment rather than after a sleep.
+  NmsTypedWatchRegistry({Stream<String>? synced}) : _synced = synced;
+
+  final Stream<String>? _synced;
+  final Map<String, _RegisteredWatch> _watches = {};
+  int _sequence = 0;
+  bool _closed = false;
+
+  NmsTypedWatchHandle<T> open<T>({
+    required String session,
+    required T Function(nomos_protocol.WatchChanged) decode,
+    required Future<void> Function(String subscriptionId) start,
+    required Future<void> Function(String subscriptionId) stop,
+  }) {
+    if (_closed) throw StateError('Reception watch registry is closed');
+    final id = '$session:watch:${++_sequence}';
+    late final _TypedWatch<T> watch;
+    watch = _TypedWatch<T>(
+      synced: _synced,
+      decode: decode,
+      start: () {
+        if (_closed) throw StateError('Reception watch registry is closed');
+        _watches[id] = watch;
+        return start(id);
+      },
+      stop: () {
+        // After close() the realm close (or the host's transport disposal)
+        // releases every peer subscription; a late per-watch unwatch would
+        // only race that teardown.
+        if (_closed) return Future<void>.value();
+        if (_watches.remove(id) == null) return Future<void>.value();
+        return stop(id);
+      },
+    );
+    return NmsTypedWatchHandle<T>(id: id, stream: watch.controller.stream);
+  }
+
+  void deliver(nomos_protocol.WatchChanged changed) {
+    _watches[changed.subscriptionId]?.deliver(changed);
+  }
+
+  /// Close every watch locally. The reception closes the realm right after,
+  /// which releases the peer subscriptions in one round trip; no watch issues
+  /// its own unwatch once the registry is closed, so a registration still in
+  /// flight at teardown cannot surface as a late "transport is disposed".
+  Future<void> close() async {
+    if (_closed) return;
+    _closed = true;
+    final watches = _watches.values.toList(growable: false);
+    _watches.clear();
+    for (final watch in watches) {
+      unawaited(watch.close());
+    }
+  }
+}
+
+abstract interface class _RegisteredWatch {
+  void deliver(nomos_protocol.WatchChanged changed);
+  Future<void> close();
+}
+
+/// One listener owns one peer subscription. Register only after the listener
+/// exists, and order cancellation after registration even when it is in flight.
+/// A single-subscription controller buffers the initial response and pauses.
+final class _TypedWatch<T> implements _RegisteredWatch {
+  final Stream<String>? _synced;
+  final T Function(nomos_protocol.WatchChanged) _decode;
+  final Future<void> Function() _start;
+  final Future<void> Function() _stop;
+  late final StreamController<T> controller;
+  Future<void>? _starting;
+  Future<void>? _stopping;
+
+  _TypedWatch({
+    required Stream<String>? synced,
+    required T Function(nomos_protocol.WatchChanged) decode,
+    required Future<void> Function() start,
+    required Future<void> Function() stop,
+  })  : _synced = synced,
+        _decode = decode,
+        _start = start,
+        _stop = stop {
+    controller = StreamController<T>(
+      onListen: () {
+        _starting = _startWhenReady().catchError(
+          (Object error, StackTrace stack) {
+            if (!controller.isClosed) controller.addError(error, stack);
+          },
+        );
+      },
+      onCancel: _cancel,
+    );
+  }
+
+  /// A workspace that is still opening, syncing or building its read index answers a
+  /// retryable [NomosUnavailable]. That is a wait, not a result: the watch registers once
+  /// the replica is ready instead of ending its stream on a state that has already passed.
+  Future<void> _startWhenReady() async {
+    final wake = NmsReplicaWake(_synced);
+    try {
+      for (var attempt = 0;; attempt++) {
+        wake.asking();
+        try {
+          return await _start();
+        } on NomosUnavailable catch (unavailable) {
+          if (!unavailable.retryable) rethrow;
+          await wake.wait(unavailable, attempt);
+          if (controller.isClosed || _stopping != null) return;
+        }
+      }
+    } finally {
+      await wake.close();
+    }
+  }
+
+  @override
+  void deliver(nomos_protocol.WatchChanged changed) {
+    if (controller.isClosed) return;
+    if (changed.hasFailure()) {
+      controller.addError(
+        nomosErrorFromInfo(NomosErrorInfo(
+          code: changed.failure.code,
+          message: changed.failure.message,
+          component: changed.failure.component,
+          operation: 'watch',
+        )),
+      );
+      return;
+    }
+    try {
+      controller.add(_decode(changed));
+    } catch (error, stackTrace) {
+      controller.addError(error, stackTrace);
+    }
+  }
+
+  Future<void> _cancel() => _stopping ??= () async {
+        if (_starting == null) return;
+        await _starting;
+        await _stop();
+      }();
+
+  @override
+  Future<void> close() async {
+    // Closing a paused controller may wait for its listener; remote cleanup
+    // must not depend on that listener resuming.
+    unawaited(controller.close());
+    await _cancel();
+  }
+}

package/dart/lib/src/workspace_open_progress.dart

@@ -0,0 +1,27 @@
+import 'reception/dart_reception.dart' show KernelProgress;
+
+/// Read-only Peer Office telemetry for opening one workspace.
+///
+/// This is presentation state. It cannot enter custody, affect authority, or
+/// choose any lifecycle transition.
+final class ApplicationWorkspaceOpenProgress {
+  const ApplicationWorkspaceOpenProgress({
+    required this.workspace,
+    required this.activeWorkspace,
+    required this.operation,
+    required this.openOperations,
+    required this.startedAt,
+    required this.observedAt,
+    required this.complete,
+    this.kernelProgress,
+  });
+
+  final String workspace;
+  final String activeWorkspace;
+  final String operation;
+  final int openOperations;
+  final DateTime startedAt;
+  final DateTime observedAt;
+  final bool complete;
+  final KernelProgress? kernelProgress;
+}

package/dart/pubspec.lock

@@ -9,6 +9,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "100.0.0"
+  adaptive_number:
+    dependency: transitive
+    description:
+      name: adaptive_number
+      sha256: "3a567544e9b5c9c803006f51140ad544aedc79604fd4f3f2c1380003f97c1d77"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.0.0"
   analyzer:
     dependency: transitive
     description:
@@ -81,6 +89,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "3.0.7"
+  ed25519_edwards:
+    dependency: "direct main"
+    description:
+      name: ed25519_edwards
+      sha256: f3c3b109a0e470ee35f6346a155cab290578660852237fce10df6bbd92758534
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.3.2"
   file:
     dependency: transitive
     description:
@@ -193,13 +209,20 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "2.0.2"
+  nomos_peer_host:
+    dependency: "direct main"
+    description:
+      path: "../../nomos_peer_host"
+      relative: true
+    source: path
+    version: "0.1.0"
   nomos_types:
     dependency: "direct main"
     description:
       path: "../dart_types"
       relative: true
     source: path
-    version: "0.10.0"
+    version: "0.11.2"
   package_config:
     dependency: "direct main"
     description:

package/dart/pubspec.yaml

@@ -7,19 +7,24 @@ repository: https://github.com/Captain-App/nomos2
 description: >-
   Nomos 2 Dart client — generated domain values, intent payloads and application
   lifecycle types over the typed Nomos kernel protocol and USDA custody model.
-version: 0.65.3
+version: 0.66.5
 
 environment:
   sdk: ^3.5.0
 
 dependencies:
+  # Runtime-to-platform capability ports. Contains no runtime implementation.
+  nomos_peer_host: ^0.1.0
   # The pure-data core (wire types, offer codec, NomosReads, schema validation, error
   # info). nomos_client depends on and re-exports it, so existing imports are unchanged.
   # For local monorepo dev, pubspec_overrides.yaml points this at ../dart_types.
-  nomos_types: ^0.10.1
+  nomos_types: ^0.11.2
   fixnum: ^1.1.1
   json_schema: ^5.2.2
   crypto: ^3.0.0
+  # Pure-Dart RFC 8032 Ed25519: the shell signs the console enrolment request
+  # with the device key it already holds (console_enrolment.dart).
+  ed25519_edwards: ^0.3.1
   package_config: ^2.1.0
   meta: ^1.12.0
 

package/dart/pubspec_overrides.yaml

@@ -3,5 +3,7 @@
 # repo. Once nomos_types is published, consumers outside the repo resolve the hosted ^0.1.0;
 # this file only affects in-repo development.
 dependency_overrides:
+  nomos_peer_host:
+    path: ../../nomos_peer_host
   nomos_types:
     path: ../dart_types