@githolon/dsl 0.113.4 → 0.114.0

package/dart/test/rows_watch_test.dart

@@ -0,0 +1,331 @@
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:nomos_client/src/generated_call.dart' show NmsGeneratedResult;
+import 'package:nomos_client/src/rows_watch.dart';
+import 'package:nomos_types/nomos_kernel_protocol.dart' as nomos_protocol;
+import 'package:nomos_types/src/proto/google/protobuf/any.pb.dart'
+    as google_protobuf;
+import 'package:test/test.dart';
+
+const _type = 'type.nomos.dev/nomos.operation.v1.QueryResult_q';
+
+/// A generated row stand-in: value equality like the generated models, so
+/// identity is observable separately.
+final class Row {
+  Row(this.id, this.value);
+  final String id;
+  final int value;
+  @override
+  bool operator ==(Object other) =>
+      other is Row && other.id == id && other.value == value;
+  @override
+  int get hashCode => Object.hash(id, value);
+  @override
+  String toString() => '$id=$value';
+}
+
+/// The test's "generated decoder": `id=value` pairs separated by `;`.
+List<Row> _decode(NmsGeneratedResult result) {
+  expect(result.protobufType, _type);
+  final text = utf8.decode(result.protobufPayload);
+  if (text.isEmpty) return const [];
+  return [
+    for (final pair in text.split(';'))
+      Row(pair.split('=')[0], int.parse(pair.split('=')[1])),
+  ];
+}
+
+google_protobuf.Any _rows(Map<String, int> rows) => google_protobuf.Any(
+      typeUrl: _type,
+      value:
+          utf8.encode(rows.entries.map((e) => '${e.key}=${e.value}').join(';')),
+    );
+
+nomos_protocol.WatchChanged _full(String frontier, Map<String, int> rows) =>
+    nomos_protocol.WatchChanged(
+      subscriptionId: 'w',
+      applicationResult: _rows(rows),
+      resultFrontier: frontier,
+    );
+
+nomos_protocol.WatchChanged _delta(
+  String base,
+  String frontier,
+  Map<String, int> rows, [
+  List<String> removed = const [],
+]) =>
+    nomos_protocol.WatchChanged(
+      subscriptionId: 'w',
+      applicationDelta: nomos_protocol.ApplicationResultDelta(
+        baseFrontier: base,
+        frontier: frontier,
+        changedRows: _rows(rows),
+        removedIds: removed,
+      ),
+    );
+
+NmsRowsMerge<Row> _merge() =>
+    NmsRowsMerge<Row>(decode: _decode, idOf: (row) => row.id);
+
+void main() {
+  test(
+      'a delta patches the complete result in id order; untouched rows keep identity',
+      () {
+    final merge = _merge();
+    final first = merge.apply(_full('f1', {'b': 2, 'a': 1, 'c': 3}))!;
+    expect(first.map((row) => row.id), ['a', 'b', 'c']);
+
+    final second = merge.apply(_delta('f1', 'f2', {'b': 20, 'd': 4}, ['c']))!;
+    expect(second, [Row('a', 1), Row('b', 20), Row('d', 4)]);
+    expect(identical(second[0], first[0]), isTrue,
+        reason: 'row a was not touched');
+
+    // A changed row that decodes equal keeps the held object and emits nothing.
+    expect(merge.apply(_delta('f2', 'f3', {'a': 1})), isNull);
+    final third = merge.apply(_delta('f3', 'f4', {'e': 5}))!;
+    expect(identical(third[0], first[0]), isTrue);
+  });
+
+  test(
+      'a complete result equal to the held rows emits nothing and keeps identity',
+      () {
+    final merge = _merge();
+    final first = merge.apply(_full('f1', {'a': 1, 'b': 2}))!;
+    expect(merge.apply(_full('f2', {'a': 1, 'b': 2})), isNull);
+    final next = merge.apply(_full('f3', {'a': 1, 'b': 3}))!;
+    expect(identical(next[0], first[0]), isTrue);
+    expect(next[1], Row('b', 3));
+    // Fewer rows is a change even when every remaining row is equal.
+    expect(merge.apply(_full('f4', {'a': 1})), [Row('a', 1)]);
+    // The position moved with the complete result.
+    expect(merge.apply(_delta('f4', 'f5', {'z': 26})),
+        [Row('a', 1), Row('z', 26)]);
+  });
+
+  test('ids order by code point, as the kernel orders them', () {
+    final merge = _merge();
+    final ids = ['\u{1F600}', '～', 'a', 'B'];
+    final rows = merge.apply(_full('f1', {for (final id in ids) id: 0}))!;
+    expect(rows.map((row) => row.id), ['B', 'a', '～', '\u{1F600}']);
+    expect(compareCodePoints('～', '\u{1F600}'), lessThan(0));
+    expect('～'.compareTo('\u{1F600}'), greaterThan(0),
+        reason: 'UTF-16 order differs, which is why the merge does not use it');
+  });
+
+  test('a delta from another position ends the watch with a typed error',
+      () async {
+    final source = StreamController<nomos_protocol.WatchChanged>();
+    final events = <Object>[];
+    final done = Completer<void>();
+    nmsMergeRows(source.stream, _merge()).listen(
+      events.add,
+      onError: events.add,
+      onDone: done.complete,
+    );
+    source.add(_full('f1', {'a': 1}));
+    source.add(_delta('elsewhere', 'f2', {'a': 2}));
+    await done.future;
+    expect(events, hasLength(2));
+    final mismatch = events[1] as NomosWatchPositionMismatch;
+    expect(mismatch.held, 'f1');
+    expect(mismatch.base, 'elsewhere');
+    expect(source.hasListener, isFalse,
+        reason: 'the peer subscription is released');
+  });
+
+  test(
+      'a delivered failure resets the rows; only a complete result restores them',
+      () async {
+    final source = StreamController<nomos_protocol.WatchChanged>();
+    final events = <Object>[];
+    final done = Completer<void>();
+    nmsMergeRows(source.stream, _merge()).listen(
+      events.add,
+      onError: events.add,
+      onDone: done.complete,
+    );
+    source.add(_full('f1', {'a': 1}));
+    source.addError(StateError('kernel unavailable'));
+    source.add(_full('f2', {'a': 1}));
+    source.add(_delta('f2', 'f3', {'b': 2}));
+    await source.close();
+    await done.future;
+    expect(events[0], [Row('a', 1)]);
+    expect(events[1], isA<StateError>());
+    expect(events[2], [Row('a', 1)],
+        reason: 'after a failure the complete rows are delivered again');
+    expect(events[3], [Row('a', 1), Row('b', 2)]);
+
+    // Without a complete result after the failure, a delta has no position.
+    final merge = _merge()..apply(_full('f1', {'a': 1}));
+    merge.reset();
+    expect(() => merge.apply(_delta('f1', 'f2', {})),
+        throwsA(isA<NomosWatchPositionMismatch>()));
+  });
+
+  test('each emission names the rows it changed and removed (CAP-751)', () {
+    final merge = _merge();
+    final first = merge.apply(_full('f1', {'a': 1, 'b': 2, 'c': 3}))!;
+    expect(first.complete, isTrue);
+    expect(first.changedIds, {'a', 'b', 'c'});
+    expect(first.removedIds, isEmpty);
+
+    final second = merge.apply(_delta('f1', 'f2', {'b': 20, 'd': 4}, ['c']))!;
+    expect(second.complete, isFalse);
+    expect(second.changedIds, {'b', 'd'});
+    expect(second.removedIds, {'c'});
+    for (final row in second) {
+      if (!second.changedIds.contains(row.id)) {
+        expect(first.contains(row), isTrue);
+        expect(identical(row, first.firstWhere((r) => r.id == row.id)), isTrue,
+            reason: 'a row outside changedIds is the object emitted before');
+      }
+    }
+
+    // Removed and re-added in one delta is a replacement.
+    final third = merge.apply(_delta('f2', 'f3', {'a': 10}, ['a']))!;
+    expect(third.changedIds, {'a'});
+    expect(third.removedIds, isEmpty);
+
+    // A complete result reports exactly what differs from the held rows.
+    final fourth = merge.apply(_full('f4', {'a': 10, 'b': 20, 'e': 5}))!;
+    expect(fourth.complete, isTrue);
+    expect(fourth.changedIds, {'e'});
+    expect(fourth.removedIds, {'d'});
+    expect(() => (fourth as List<Row>).add(Row('x', 0)),
+        throwsUnsupportedError);
+  });
+
+  group('NomosRowProjection', () {
+    test('projects only rows it has not seen, keeping earlier projections', () {
+      final merge = _merge();
+      var calls = 0;
+      final projection = NomosRowProjection<Row, String>((row) {
+        calls += 1;
+        return '${row.id}:${row.value}';
+      });
+      final first = projection.apply(merge.apply(_full('f1', {
+        for (var i = 0; i < 100; i += 1) 'r${i.toString().padLeft(3, '0')}': i,
+      }))!);
+      expect(calls, 100);
+      final second =
+          projection.apply(merge.apply(_delta('f1', 'f2', {'r050': -1}))!);
+      expect(calls, 101, reason: 'one changed row, one projection');
+      expect(second[50], 'r050:-1');
+      expect(identical(second[49], first[49]), isTrue);
+      expect(second.length, 100);
+      // The same rows again: the identical output.
+      final rows = merge.apply(_delta('f2', 'f3', {'r999': 9}))!;
+      final third = projection.apply(rows);
+      expect(identical(projection.apply(rows), third), isTrue);
+      expect(calls, 102);
+    });
+
+    test('an order is kept by merging new projections into the previous order',
+        () {
+      final merge = _merge();
+      var calls = 0;
+      int byValueThenId(Row a, Row b) {
+        final byValue = a.value.compareTo(b.value);
+        return byValue != 0 ? byValue : a.id.compareTo(b.id);
+      }
+
+      final projection = NomosRowProjection<Row, Row>((row) {
+        calls += 1;
+        return row.value < 0 ? null : row; // negative values are left out
+      }, order: byValueThenId);
+      final values = {for (var i = 0; i < 50; i += 1) 'r$i': (i * 37) % 50};
+      final first = projection.apply(merge.apply(_full('f1', values))!);
+      expect(first, [...first]..sort(byValueThenId));
+      expect(first.length, 50);
+
+      var frontier = 1;
+      List<Row> step(Map<String, int> rows, [List<String> removed = const []]) {
+        final emitted =
+            merge.apply(_delta('f$frontier', 'f${frontier + 1}', rows, removed))!;
+        frontier += 1;
+        return projection.apply(emitted);
+      }
+
+      var out = step({'r3': 1000, 'r7': -5, 'new': 25}, ['r9']);
+      final expected = [
+        for (final row in _merge().apply(_full('check', {
+          for (final e in values.entries)
+            if (e.key != 'r9') e.key: e.value,
+          'r3': 1000,
+          'r7': -5,
+          'new': 25,
+        }))!)
+          if (row.value >= 0) row,
+      ]..sort(byValueThenId);
+      expect(out, expected);
+      expect(calls, 53, reason: 'only the three rows the delta carried');
+
+      // Leaving a row out anew changes the output; filtering it again does not.
+      out = step({'r7': -6});
+      expect(out, expected);
+      calls = 0;
+      projection.invalidate();
+      expect(projection.apply(out), expected);
+      expect(calls, expected.length);
+    });
+
+    test('projectRows forwards only changed outputs, one projection per listener',
+        () async {
+      final source = StreamController<List<Row>>.broadcast(sync: true);
+      var calls = 0;
+      final projected = source.stream.projectRows<String>((row) {
+        calls += 1;
+        return row.value.isEven ? row.id : null;
+      });
+      final a = <List<String>>[];
+      final b = <List<String>>[];
+      final subA = projected.listen(a.add);
+      final subB = projected.listen(b.add);
+      final r1 = Row('a', 2);
+      final r2 = Row('b', 3);
+      source.add([r1, r2]);
+      source.add([r1, r2]); // identical rows: nothing new to forward
+      source.add([r1, Row('b', 4)]);
+      await pumpEventQueue();
+      expect(a, [
+        ['a'],
+        ['a', 'b'],
+      ]);
+      expect(b, a);
+      expect(calls, 6, reason: 'two listeners, three distinct rows each');
+      await subA.cancel();
+      await subB.cancel();
+      await source.close();
+    });
+
+    test('a thousand rows and single-row deltas cost one projection per delta',
+        () async {
+      final source = StreamController<nomos_protocol.WatchChanged>();
+      var calls = 0;
+      final outputs = <List<String>>[];
+      final sub = nmsMergeRows(source.stream, _merge())
+          .projectRows<String>((row) {
+        calls += 1;
+        return 'p${row.value}';
+      }, order: (x, y) => x.compareTo(y)).listen(outputs.add);
+      source.add(_full('f0', {
+        for (var i = 0; i < 1000; i += 1) 'r${i.toString().padLeft(4, '0')}': i,
+      }));
+      for (var i = 0; i < 50; i += 1) {
+        source.add(_delta('f$i', 'f${i + 1}',
+            {'r${(i * 7).toString().padLeft(4, '0')}': 10000 + i}));
+      }
+      await pumpEventQueue();
+      expect(outputs, hasLength(51));
+      expect(calls, 1000 + 50);
+      final last = outputs.last;
+      expect(last, [...last]..sort());
+      expect(last.length, 1000);
+      await sub.cancel();
+      await source.close();
+    });
+  });
+}
+

package/dart/test/test_peer_host_selection_test.dart

@@ -0,0 +1,49 @@
+// The canonical test peer's host is DECLARED by NOMOS_TEST_PEER_HOST: unset/node is the Node
+// peer, native is the Apple native host the caller registered. A value naming no host, or native
+// selected without a registered host, is refused loudly — never quietly run on Node.
+@TestOn('vm')
+library;
+
+import 'package:nomos_client/src/testing/test_peer_host.dart';
+import 'package:test/test.dart';
+
+void main() {
+  test('unset or node selects the Node peer', () {
+    expect(NmsTestPeerHostKind.selected(const {}), NmsTestPeerHostKind.node);
+    expect(
+      NmsTestPeerHostKind.selected(const {nmsTestPeerHostVariable: 'node'}),
+      NmsTestPeerHostKind.node,
+    );
+  });
+
+  test('native selects the Apple native host', () {
+    expect(
+      NmsTestPeerHostKind.selected(const {nmsTestPeerHostVariable: 'native'}),
+      NmsTestPeerHostKind.native,
+    );
+  });
+
+  test('a value naming no host is refused, not defaulted to Node', () {
+    expect(
+      () => NmsTestPeerHostKind.selected(
+          const {nmsTestPeerHostVariable: 'nativ'}),
+      throwsA(isA<StateError>().having(
+        (error) => error.message,
+        'message',
+        contains('names no test peer host'),
+      )),
+    );
+  });
+
+  test('native selected without a registered host is refused with the remedy',
+      () {
+    expect(
+      NmsTestPeerHosts.requireNative,
+      throwsA(isA<StateError>().having(
+        (error) => error.message,
+        'message',
+        contains('registerNomosNativeTestPeerHost()'),
+      )),
+    );
+  });
+}

package/dart_types/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 0.13.0
+
+- `NomosApprovedModel` requires `unitSet`: the law a release approves is its unit set identity (the generated
+  `frameworkCalls.lawUnitSet`); `lawSha256` names the package closure. `AdoptApplicationModelRequest` carries
+  `unit_set`. `ApplicationBirthContract` is retired: a Home is born under the law its platform serves (CAP-773).
+- Live link frames: `LiveLinkClosure` and `PeerSocketClosure` record how a live connection closed (who ended it,
+  code, reason, duration and what it carried) (CAP-683, CAP-684).
+- Rows watches can receive only the rows that changed: `ApplicationResultDelta` and `FullResultReason` (CAP-731).
+  `OfferStateChange` names the aggregate types an offer changed, so a local offer re-reads only the watches it
+  can change (CAP-760).
+- `CustodianWarming` reports a custodian warming up as its own posture, not an error retry (CAP-769).
+- `ReadAccessPreparation` reports a device enrolled just in time for a granted read (CAP-740).
+- Carry the current generated kernel and Runtime v2 Protobuf contracts, including per-offer phase timings
+  (CAP-756) and residency rows (CAP-754).
+
 ## 0.12.0
 
 - Add the `LiveAdmission` live-link frame: the custodian's admission of a live batch, returned over the link (CAP-656).

package/dart_types/lib/src/approved_model.dart

@@ -14,21 +14,29 @@ final RegExp _lowerHex64 = RegExp(r'^[0-9a-f]{64}$');
 
 /// The law model an application release approves, supplied once at the
 /// application's Reception. Every field is required: the office refuses to
-/// adopt without the package identity, the domain keys it observes, the
-/// attributed reason the kernel's transition demands, or the package bytes a
-/// child must stage — none of them can be invented later.
+/// adopt without the law (its unit set), the package identity, the domain keys
+/// it observes, the attributed reason the kernel's transition demands, or the
+/// package bytes a child must stage — none of them can be invented later.
 final class NomosApprovedModel {
   NomosApprovedModel({
+    required this.unitSet,
     required this.lawSha256,
     required this.reason,
     required List<String> domainKeys,
     required this.loadPackage,
   }) : domainKeys = List.unmodifiable(domainKeys) {
+    if (!_lowerHex64.hasMatch(unitSet)) {
+      throw ArgumentError.value(
+        unitSet,
+        'unitSet',
+        'must be the unit set identity of the compiled build/<name>.units (64 lowercase hex)',
+      );
+    }
     if (!_lowerHex64.hasMatch(lawSha256)) {
       throw ArgumentError.value(
         lawSha256,
         'lawSha256',
-        'must be the kernel-derived identity of the compiled law package (64 lowercase hex)',
+        'must be the identity of the compiled package closure (64 lowercase hex)',
       );
     }
     if (reason.trim().isEmpty) {
@@ -48,7 +56,16 @@ final class NomosApprovedModel {
     }
   }
 
-  /// The kernel-derived identity of the compiled `.law.usdz` closure.
+  /// THE LAW this release approves (CAP-773): the unit set identity of the
+  /// compiled `build/<name>.units` (the generated `frameworkCalls.lawUnitSet`).
+  /// A workspace is on it when the closure it serves is composed from exactly
+  /// these units, whatever its kernel's composer.
+  final String unitSet;
+
+  /// The compiled package closure (`.law.usdz`, the generated
+  /// `frameworkCalls.lawPackageSha256`): the bytes [loadPackage] supplies when a
+  /// package-lane workspace must stage them. Package — not what a unit-lane
+  /// workspace serves.
   final String lawSha256;
 
   /// The attributed approval text. The kernel's transition demands it whenever