@githolon/dsl 0.114.0 → 0.115.0

package/dart/CHANGELOG.md

@@ -1,3 +1,43 @@
+## 0.69.0
+
+- The test cloud's partition proxy (`NomosTestCloud`) carries live sockets: each workspace's catch-up
+  stream and live offers pass through it while ONLINE, and going OFFLINE severs them too (CAP-826).
+
+Uses nomos_types 0.14.0; regenerate generated clients with this compiler.
+
+- Generated framework calls expose `domainRequirements` (CAP-666): for each application domain, the law unit and
+  the generated requirement identity this client was compiled against. `NomosApprovedModel` carries them to the
+  model-adoption desk, and the client inventory records them as the build's contract, so an application pinned
+  to one domain no longer goes stale when a rollout moves a domain it never touches.
+- One parent per node (CAP-788): the kernel refuses, with `[birth-child-already-parented]`, a business birth whose
+  child already records a different parent. Names are fixed at birth (CAP-803): `keyedBirthWorkspace` and the
+  generated `open` / `fetch` / `watchOpenProgress(key)` address a business child by
+  `workspaceNameForKey(namespace, key)`, exactly as 0.68.0 did, and send no parent. The parent-scoped naming
+  proposed with CAP-788 is withdrawn before release.
+- Birth keys are minted by default (CAP-804). A business birth with no `key` names its child by an id Nomos
+  mints inside the birth; generated applications open it with `openReference` / `fetchReference` / `mine()`
+  instead of `open(key)`. An encrypted `.owned()` birth reserves its minted key first (`session.mintId`). An
+  explicit key, `key: "<field>"`, must name a typed-id field and names children exactly as before. When a duplicate birth is refused on the losing peer
+  (`[birth-child-already-parented]`), the child's creation receipt completes with a `NomosOperationRefused`
+  error (new export; `NomosOperationStatus.refusal` / `isRefused`).
+- Birth keys are typed ids (CAP-804 follow-up): a generated client's branded-id fields are extension types in read
+  models and query keys, and `open(key)` / `fetch(key)` / `watchOpenProgress(key)` take the key's branded type. A
+  write that changes a birth key is refused (`birth-key-write-once`).
+- One console enrolment exchange is bounded at 20 s (`nomosConsoleEnrolmentTimeout`); a timeout is a retryable
+  transport failure, so a slow console no longer holds a person's write (CAP-807).
+- Nested record members, map values, list elements and union variants carry their protobuf wire allocation in the
+  generated compatibility requirement, and the kernel judges them recursively (CAP-681). A client whose nested
+  allocation differs from the installed law is refused with the member named, never decoded wrongly.
+- A reloaded app no longer sees an empty child list (CAP-824): `nomosFrameworkChildWorkspaces` (behind the
+  generated `mine()` / `available()`) waits out a retryable not-ready answer while the device is still preparing
+  its copy, as every other one-shot read does, so the caller gets the children or a real error. A write that meets
+  unfinished preparation is held and reported as `NomosWritePhase.preparing`, then completes; no client change.
+- Bundles the 0.115.0 runtime: the kernel-side release qualification (CAP-789), the per-domain adoption record
+  (CAP-666), one parent per node with names fixed at birth (CAP-788, CAP-803), minted birth keys and the losing
+  peer's typed birth refusal (CAP-804), the pack indexed in place (CAP-802), pack imports in bounded steps
+  that never hold up a person's work (CAP-806), one law version per identity named by its unit set (CAP-809), the
+  v2 command frontier (CAP-810) and claimed law versions (CAP-811).
+
 ## 0.68.0
 
 Breaking: regenerate generated Dart clients with this compiler.

package/dart/lib/src/application_framework_calls.dart

@@ -3,7 +3,7 @@
 import 'dart:convert' show utf8;
 import 'dart:typed_data' show Uint8List;
 import 'package:meta/meta.dart' show internal;
-import 'package:nomos_types/nomos_types.dart' show Sha256Digest;
+import 'package:nomos_types/nomos_types.dart' show NomosDomainRequirement, Sha256Digest;
 import 'package:nomos_types/nomos_kernel_protocol.dart' show BirthCertificate;
 
 import 'generated_call.dart';
@@ -244,6 +244,12 @@ abstract interface class NmsApplicationFrameworkCalls {
   /// model-adoption desk on a package-lane workspace. Package — not what a unit-lane workspace serves.
   String get lawPackageSha256;
 
+  /// THE PER-DOMAIN REQUIREMENTS (CAP-666), by application domain key: the exact law unit
+  /// (`domain:<key>` of the unit set) and the generated consumer requirement identity this
+  /// client was compiled against. An application pins its release by these beside [lawUnitSet];
+  /// the model-adoption desk and the client inventory carry them as this build's contract.
+  Map<String, NomosDomainRequirement> get domainRequirements;
+
   NmsGeneratedCall enrollFirstDevice({
     required String domain,
     required String workspace,

package/dart/lib/src/console_enrolment.dart

@@ -192,6 +192,13 @@ final class NomosConsoleEnrolmentRefused implements Exception {
   String toString() => 'console enrolment refused (HTTP $status): $message';
 }
 
+/// How long one console enrolment exchange may take before the shell reports
+/// it as a retryable transport failure. The console answers once the
+/// workspaces the device asked for admitted it (its fan-out follows in the
+/// background), so a healthy answer takes a few seconds; Peer Office asks
+/// again with a fresh token rather than holding a person's write.
+const Duration nomosConsoleEnrolmentTimeout = Duration(seconds: 20);
+
 /// One console exchange: status and raw body.
 final class NomosConsoleResponse {
   const NomosConsoleResponse({required this.status, required this.body});

package/dart/lib/src/console_http_io.dart

@@ -1,25 +1,32 @@
+import 'dart:async';
 import 'dart:convert';
 import 'dart:io';
 
-import 'console_enrolment.dart' show NomosConsoleResponse;
+import 'console_enrolment.dart'
+    show NomosConsoleResponse, nomosConsoleEnrolmentTimeout;
 
 /// The native shells' console transport: one JSON POST, the answer's status
 /// and body. No retry and no interpretation: Peer Office owns both.
-Future<NomosConsoleResponse> nomosDefaultConsolePost(
-    Uri url, String body) async {
-  final client = HttpClient()..connectionTimeout = const Duration(seconds: 30);
+///
+/// The whole exchange is bounded by [timeout] ([nomosConsoleEnrolmentTimeout]) (CAP-807:
+/// a slow console held a person's write for 53 s before this failed). A
+/// [TimeoutException] is a retryable transport failure: the console may still
+/// finish the enrolment, and the next attempt (a fresh token) finds it done.
+Future<NomosConsoleResponse> nomosDefaultConsolePost(Uri url, String body,
+    {Duration timeout = nomosConsoleEnrolmentTimeout}) async {
+  final client = HttpClient()..connectionTimeout = timeout;
   try {
-    final request = await client.postUrl(url);
-    request.headers
-      ..contentType = ContentType.json
-      ..set(HttpHeaders.acceptHeader, 'application/json');
-    request.add(utf8.encode(body));
-    final response = await request.close().timeout(const Duration(seconds: 60));
-    final text = await response
-        .transform(utf8.decoder)
-        .join()
-        .timeout(const Duration(seconds: 60));
-    return NomosConsoleResponse(status: response.statusCode, body: text);
+    return await () async {
+      final request = await client.postUrl(url);
+      request.headers
+        ..contentType = ContentType.json
+        ..set(HttpHeaders.acceptHeader, 'application/json');
+      request.add(utf8.encode(body));
+      final response = await request.close();
+      final text = await response.transform(utf8.decoder).join();
+      return NomosConsoleResponse(status: response.statusCode, body: text);
+    }()
+        .timeout(timeout);
   } finally {
     client.close(force: true);
   }

package/dart/lib/src/dev_cloud.dart

@@ -79,6 +79,10 @@ class NomosTestCloud {
   bool _online = true;
   bool _stopped = false;
 
+  /// Live sockets the proxy carries (each workspace's catch-up stream and live offers,
+  /// architecture/peer_catchup.md). Going OFFLINE severs them too, as a real link loss would.
+  final Set<WebSocket> _liveSockets = {};
+
   NomosTestCloud._(
     this._server,
     this._proxy,
@@ -98,6 +102,12 @@ class NomosTestCloud {
   /// cloud and peers converge. Deterministic: no timing races, the test decides exactly when the link exists.
   void setOnline(bool online) {
     _online = online;
+    if (!online) {
+      for (final socket in _liveSockets.toList()) {
+        socket.close(WebSocketStatus.goingAway, 'partitioned');
+      }
+      _liveSockets.clear();
+    }
     _log(
       'partition: ${online ? "ONLINE (link up)" : "OFFLINE (link severed)"}',
     );
@@ -350,6 +360,10 @@ class NomosTestCloud {
       } catch (_) {}
       return;
     }
+    if (WebSocketTransformer.isUpgradeRequest(req)) {
+      await _proxyLiveSocket(req);
+      return;
+    }
     try {
       final target = _upstream.replace(
         path: req.uri.path,
@@ -375,6 +389,50 @@ class NomosTestCloud {
     }
   }
 
+  /// A WebSocket through the partition: both ends piped frame for frame, both closed together.
+  Future<void> _proxyLiveSocket(HttpRequest req) async {
+    final WebSocket upstream;
+    try {
+      upstream = await WebSocket.connect(_upstream
+          .replace(
+            scheme: _upstream.scheme == 'https' ? 'wss' : 'ws',
+            path: req.uri.path,
+            query: req.uri.query.isEmpty ? null : req.uri.query,
+          )
+          .toString());
+    } catch (_) {
+      try {
+        req.response.statusCode = 502;
+        await req.response.close();
+      } catch (_) {}
+      return;
+    }
+    final WebSocket client;
+    try {
+      client = await WebSocketTransformer.upgrade(req);
+    } catch (_) {
+      await upstream.close();
+      return;
+    }
+    _liveSockets
+      ..add(client)
+      ..add(upstream);
+    void closeBoth() {
+      _liveSockets
+        ..remove(client)
+        ..remove(upstream);
+      client.close();
+      upstream.close();
+    }
+
+    upstream.listen((frame) {
+      if (_online) client.add(frame);
+    }, onDone: closeBoth, onError: (_) => closeBoth());
+    client.listen((frame) {
+      if (_online) upstream.add(frame);
+    }, onDone: closeBoth, onError: (_) => closeBoth());
+  }
+
   Future<Map<String, Object?>> _getJson(Uri url) async {
     final req = await _client.getUrl(url);
     final resp = await req.close();
@@ -394,6 +452,10 @@ class NomosTestCloud {
     if (_stopped) return;
     _stopped = true;
     _log('stopping');
+    for (final socket in _liveSockets.toList()) {
+      socket.close();
+    }
+    _liveSockets.clear();
     try {
       await _proxy.close(force: true);
     } catch (_) {}

package/dart/lib/src/operation_receipts.dart

@@ -8,15 +8,43 @@ enum NomosOperationPhase {
   converged,
 }
 
+/// Custody refused a write this device accepted locally: a terminal verdict, never retried.
+///
+/// Today the one such refusal Nomos reports is a duplicate birth: a workspace name is global to its
+/// namespace and fixed at birth, and another parent already owns this child's name, so the cloud
+/// refused this birth (`[birth-child-already-parented]`). The child's local copy is quarantined on this
+/// device — kept for inspection, never synced. The message names only this device's own workspaces.
+final class NomosOperationRefused implements Exception {
+  const NomosOperationRefused({
+    required this.code,
+    required this.message,
+    this.childWorkspace,
+  });
+
+  /// The typed refusal tag, e.g. `birth-child-already-parented`.
+  final String code;
+  final String message;
+
+  /// The quarantined local child, for a refused birth.
+  final String? childWorkspace;
+
+  @override
+  String toString() => 'NomosOperationRefused[$code]: $message';
+}
+
 /// Product-facing progress for one accepted write.
 final class NomosOperationStatus {
-  const NomosOperationStatus(this.phase, {this.updatedAt});
+  const NomosOperationStatus(this.phase, {this.updatedAt, this.refusal});
 
   final NomosOperationPhase phase;
   final DateTime? updatedAt;
 
+  /// Set when custody refused this write: terminal; [phase] stays [NomosOperationPhase.locallyAccepted].
+  final NomosOperationRefused? refusal;
+
   bool get isAdmitted => phase != NomosOperationPhase.locallyAccepted;
   bool get isConverged => phase == NomosOperationPhase.converged;
+  bool get isRefused => refusal != null;
 }
 
 /// Awaitable projection of typed peer-runtime receipts for one stable intent.
@@ -36,13 +64,36 @@ final class NomosOperationReceipt {
     yield* _changes.stream;
   }
 
-  Future<void> get admitted => _status.isAdmitted
-      ? Future<void>.value()
-      : watch().firstWhere((status) => status.isAdmitted).then((_) {});
+  /// Completes when remote custody admits this write; completes with a
+  /// [NomosOperationRefused] error when custody refuses it.
+  Future<void> get admitted => _settled((status) => status.isAdmitted);
+
+  /// Completes when this write has converged; completes with a
+  /// [NomosOperationRefused] error when custody refuses it.
+  Future<void> get converged => _settled((status) => status.isConverged);
+
+  Future<void> _settled(bool Function(NomosOperationStatus) reached) {
+    final refusal = _status.refusal;
+    if (refusal != null) return Future<void>.error(refusal);
+    if (reached(_status)) return Future<void>.value();
+    return watch()
+        .firstWhere((status) => status.isRefused || reached(status))
+        .then((status) {
+      final refused = status.refusal;
+      if (refused != null) throw refused;
+    });
+  }
 
-  Future<void> get converged => _status.isConverged
-      ? Future<void>.value()
-      : watch().firstWhere((status) => status.isConverged).then((_) {});
+  void _refuse(NomosOperationRefused refusal) {
+    if (_status.isRefused || _status.isAdmitted) return;
+    _status = NomosOperationStatus(
+      _status.phase,
+      updatedAt: DateTime.now(),
+      refusal: refusal,
+    );
+    if (!_changes.isClosed) _changes.add(_status);
+    unawaited(_changes.close());
+  }
 
   void _advance(NomosOperationPhase phase) {
     if (phase.index <= _status.phase.index) return;
@@ -81,6 +132,22 @@ final class NmsOperationReceiptProjection {
   NomosOperationReceipt? birthFor(String workspace) => _births[workspace];
 
   void advance(String workspace, nomos_protocol.SyncWorkspaceResponse result) {
+    // Custody refused one of this workspace's births (the child's name already has another parent):
+    // the creation receipt of that child reports the typed, terminal refusal (CAP-804).
+    for (final birth in result.birthOutcomes) {
+      if (birth.status !=
+              nomos_protocol.BirthOutcomeStatus.BIRTH_OUTCOME_STATUS_REFUSED ||
+          birth.code != 'birth-child-already-parented') {
+        continue;
+      }
+      final child =
+          birth.childWorkspace.isNotEmpty ? birth.childWorkspace : birth.workspace;
+      _births[child]?._refuse(NomosOperationRefused(
+        code: birth.code,
+        message: birth.hasRefusal() ? birth.refusal.message : birth.reason,
+        childWorkspace: child,
+      ));
+    }
     final pending = _pending[workspace];
     if (pending == null || pending.isEmpty) return;
 

package/dart/lib/src/reception/dart_reception.dart

@@ -94,7 +94,11 @@ export '../sync_status_projection.dart'
         WorkspaceFollowStatus,
         WorkspaceFollowPhase;
 export '../operation_receipts.dart'
-    show NomosOperationPhase, NomosOperationReceipt, NomosOperationStatus;
+    show
+        NomosOperationPhase,
+        NomosOperationReceipt,
+        NomosOperationRefused,
+        NomosOperationStatus;
 export 'progress_desk.dart'
     show
         KernelLawHydrationStep,
@@ -2128,15 +2132,23 @@ class DartReception {
 
   /// Framework-private organisational read used by generated `describe()`. The runner joins the parent
   /// ledger's verified birth witnesses and lifecycle facts; tenant code only receives safe child links.
+  ///
+  /// On a cold mount the office answers "not ready yet" while it prepares the parent's birth
+  /// records (CAP-824); this waits that out like every other one-shot read, so a caller sees the
+  /// children or a real error, never an empty list that fills in by itself a moment later.
   Future<List<nomos_protocol.ChildWorkspace>> nomosFrameworkChildWorkspaces(
       {String? namespace}) async {
-    final response = await _invokeRuntimeV2(
-      nomos_protocol.RuntimeRequest(
-        listChildWorkspaces: nomos_protocol.ListChildWorkspacesRequest(
-          session: _runtimeSession(),
-          namespace: namespace,
+    final session = _runtimeSession();
+    final response = await nmsUntilReplicaReady(
+      () => _invokeRuntimeV2(
+        nomos_protocol.RuntimeRequest(
+          listChildWorkspaces: nomos_protocol.ListChildWorkspacesRequest(
+            session: session,
+            namespace: namespace,
+          ),
         ),
       ),
+      synced: _eventPlane._events.workspacesSynced,
     );
     if (!response.hasChildWorkspaces()) {
       throw StateError(
@@ -4300,6 +4312,14 @@ class NomosSession extends DartReception {
           domainKeys: model.domainKeys,
           acceptanceReason: model.reason,
           dryRun: dryRun,
+          domainRequirements: [
+            for (final requirement in model.domainRequirements.values)
+              nomos_protocol.DomainUnitRequirement(
+                domainKey: requirement.domainKey,
+                unitSha256: requirement.unitSha256,
+                requirementSha256: requirement.requirementSha256,
+              ),
+          ],
         ),
       ),
     );