@githolon/dsl 0.108.7 → 0.110.0

package/dart/test/typed_query_watch_test.dart

@@ -0,0 +1,170 @@
+import 'dart:async';
+import 'dart:typed_data';
+
+import 'package:fixnum/fixnum.dart' as fixnum;
+import 'package:nomos_client/src/nms_generated_runtime.dart';
+import 'package:nomos_types/nomos_kernel_protocol.dart' as p;
+import 'package:nomos_types/src/proto/google/protobuf/any.pb.dart' as protobuf;
+import 'package:test/test.dart';
+
+// Exercise the real Reception boundary. A follow-up query is an unexpected
+// command, not a canned successful response that could conceal duplicate work.
+final class _Office implements PeerOfficeConnection {
+  final events = StreamController<p.RuntimeEvent>.broadcast(sync: true);
+  final calls = <p.RuntimeRequest>[];
+  int sequence = 0;
+
+  @override
+  Stream<p.RuntimeEvent> get runtimeEvents => events.stream;
+
+  @override
+  int nextRuntimeRequestId() => ++sequence;
+
+  @override
+  Future<p.RuntimeResponse> invokeRuntime(p.RuntimeRequest request) async {
+    calls.add(request.deepCopy());
+    final response = p.RuntimeResponse(
+      protocolVersion: 2,
+      requestId: request.requestId,
+    );
+    if (request.hasWatch()) {
+      response.watchStarted =
+          p.WatchStarted(subscriptionId: request.watch.subscriptionId);
+    } else if (request.hasUnwatch()) {
+      response.watchStopped =
+          p.WatchStopped(subscriptionId: request.unwatch.subscriptionId);
+    } else if (request.hasCloseRealm()) {
+      response.realmClosed = p.RealmClosed();
+    } else {
+      fail('Unexpected command: ${request.whichCommand()}');
+    }
+    return response;
+  }
+
+  void emit(p.WatchChanged changed) {
+    changed.subscriptionId =
+        calls.singleWhere((r) => r.hasWatch()).watch.subscriptionId;
+    events.add(p.RuntimeEvent(watchChanged: changed));
+  }
+}
+
+final _query = NmsInternalGeneratedQueries.create(
+  domain: 'estate',
+  query: 'canvasAssets',
+  protobufType: 'type.nomos.dev/estate.CanvasAssetsArgs',
+  protobufPayload: Uint8List.fromList([8, 1]),
+);
+const _resultType = 'type.nomos.dev/estate.CanvasAssetsResult';
+
+void main() {
+  late _Office office;
+  late DartReception reception;
+
+  setUp(() {
+    office = _Office();
+    reception = DartReception(office);
+  });
+  tearDown(() async {
+    await reception.dispose();
+    await office.events.close();
+  });
+
+  test('typed query watch delivers data and empty results without requerying',
+      () async {
+    final stream = reception.session('estate').nmsWatch(_query);
+    expect(office.calls, isEmpty, reason: 'an unobserved watch is lazy');
+    final values = StreamIterator(stream);
+    final first = values.moveNext();
+    final request = office.calls.single.watch;
+    expect(request.session, 'estate');
+    expect(request.query.resultFormat,
+        p.QueryResultFormat.QUERY_RESULT_FORMAT_APPLICATION_PROTOBUF);
+    expect(request.query.rows.id, 'canvasAssets');
+    expect(
+        request.query.rows.applicationArguments.typeUrl, _query.protobufType);
+    expect(request.query.rows.applicationArguments.value, [8, 1]);
+
+    office.emit(p.WatchChanged(
+        applicationResult: protobuf.Any(typeUrl: _resultType, value: [8, 9])));
+    expect(await first, isTrue);
+    expect(values.current.protobufType, _resultType);
+    expect(values.current.protobufPayload, [8, 9]);
+
+    final second = values.moveNext();
+    office.emit(
+        p.WatchChanged(applicationResult: protobuf.Any(typeUrl: _resultType)));
+    expect(await second, isTrue);
+    expect(values.current.protobufType, _resultType);
+    expect(values.current.protobufPayload, isEmpty,
+        reason: 'an empty Protobuf result is still a typed observation');
+    expect(office.calls, hasLength(1),
+        reason: 'events are data, not invalidations');
+
+    await values.cancel();
+    expect(office.calls.map((r) => r.whichCommand()),
+        [p.RuntimeRequest_Command.watch, p.RuntimeRequest_Command.unwatch]);
+  });
+
+  test('missing application result is observable, not silently requeried',
+      () async {
+    final result = reception.session('estate').nmsWatch(_query).first;
+    final check = expectLater(result, throwsStateError);
+    office.emit(p.WatchChanged(resultUsda: [1, 2]));
+    await check;
+    expect(office.calls.where((r) => r.hasKernelCall()), isEmpty);
+  });
+
+  test(
+      'count watch preserves zero and exact integers without transferring rows',
+      () async {
+    final values = StreamIterator(reception
+        .session('estate')
+        .nmsWatchCount('assetCountBySiteId', 'site'));
+    final first = values.moveNext();
+    final query = office.calls.single.watch.query;
+    expect(query.whichQuery(), p.QueryRequest_Query.count);
+    expect(query.count.id, 'assetCountBySiteId');
+    expect(query.count.groupKey, 'site');
+    office.emit(p.WatchChanged(integerValue: fixnum.Int64.ZERO));
+    expect(await first, isTrue);
+    expect(values.current, 0);
+    final second = values.moveNext();
+    office.emit(p.WatchChanged(integerValue: fixnum.Int64(9007199254740993)));
+    expect(await second, isTrue);
+    expect(values.current, 9007199254740993);
+    expect(office.calls, hasLength(1));
+    await values.cancel();
+  });
+
+  test('count watch rejects missing integer instead of treating it as zero',
+      () async {
+    final result =
+        reception.session('estate').nmsWatchCount('assetCount').first;
+    final check = expectLater(result, throwsStateError);
+    office.emit(p.WatchChanged());
+    await check;
+  });
+
+  test('invalid nominal result identity fails at the transport boundary',
+      () async {
+    final result = reception.session('estate').nmsWatch(_query).first;
+    final check = expectLater(result, throwsArgumentError);
+    office.emit(p.WatchChanged(
+        applicationResult: protobuf.Any(typeUrl: 'untyped', value: [1])));
+    await check;
+  });
+
+  test('watch refusal is delivered to the listener without starting a query',
+      () async {
+    final result = reception.session('estate').nmsWatch(_query).first;
+    final check = expectLater(
+        result,
+        throwsA(isA<NomosRuntimeError>()
+            .having((e) => e.info.code, 'code', 'invalid_credential')));
+    office.emit(p.WatchChanged(
+        failure: p.RuntimeFailure(
+            code: 'invalid_credential', message: 'Credential was rejected')));
+    await check;
+    expect(office.calls.where((r) => r.hasKernelCall()), isEmpty);
+  });
+}

package/dart/test/typed_watch_registry_test.dart

@@ -0,0 +1,249 @@
+import 'dart:async';
+import 'package:nomos_client/src/typed_watch_registry.dart';
+import 'package:nomos_types/nomos_kernel_protocol.dart' as protocol;
+import 'package:nomos_types/nomos_types.dart'
+    show NomosUnavailable, NomosUnavailableReason;
+import 'package:test/test.dart';
+
+void main() {
+  test(
+    'watch is lazy and retains the initial result during registration',
+    () async {
+      final registry = NmsTypedWatchRegistry();
+      var starts = 0;
+      var stops = 0;
+      final watch = registry.open(
+        session: 'estate',
+        decode: (event) => event.resultUsda,
+        start: (id) async {
+          starts++;
+          registry.deliver(
+            protocol.WatchChanged(subscriptionId: id, resultUsda: [1]),
+          );
+        },
+        stop: (_) async {
+          stops++;
+        },
+      );
+      expect(starts, 0);
+      expect(await watch.stream.first, [1]);
+      await Future<void>.delayed(Duration.zero);
+      expect(starts, 1);
+      expect(stops, 1);
+    },
+  );
+
+  test(
+    'cancel waits for registration before stopping the peer subscription',
+    () async {
+      final registry = NmsTypedWatchRegistry();
+      final registered = Completer<void>();
+      final order = <String>[];
+      final watch = registry.open(
+        session: 'estate',
+        decode: (event) => event.resultUsda,
+        start: (_) async {
+          order.add('start');
+          await registered.future;
+          order.add('registered');
+        },
+        stop: (_) async {
+          order.add('stop');
+        },
+      );
+      final sub = watch.stream.listen((_) {});
+      final canceled = sub.cancel();
+      expect(order, ['start']);
+      registered.complete();
+      await canceled;
+      expect(order, ['start', 'registered', 'stop']);
+      await registry.close();
+      await Future<void>.delayed(Duration.zero);
+      expect(order.where((e) => e == 'stop').length, 1);
+    },
+  );
+
+  test('paused listeners retain ordered observations', () async {
+    final registry = NmsTypedWatchRegistry();
+    final values = <List<int>>[];
+    final watch = registry.open(
+      session: 'estate',
+      decode: (event) => event.resultUsda,
+      start: (_) async {},
+      stop: (_) async {},
+    );
+    final sub = watch.stream.listen(values.add)..pause();
+    registry.deliver(
+      protocol.WatchChanged(subscriptionId: watch.id, resultUsda: [1]),
+    );
+    registry.deliver(
+      protocol.WatchChanged(subscriptionId: watch.id, resultUsda: [2]),
+    );
+    await Future<void>.delayed(Duration.zero);
+    expect(values, isEmpty);
+    sub.resume();
+    await Future<void>.delayed(Duration.zero);
+    expect(values, [
+      [1],
+      [2],
+    ]);
+    await sub.cancel();
+  });
+
+  test(
+    'a stream retained past Reception close cannot reopen a watch',
+    () async {
+      final registry = NmsTypedWatchRegistry();
+      var starts = 0;
+      var stops = 0;
+      final watch = registry.open(
+        session: 'estate',
+        decode: (event) => event.resultUsda,
+        start: (_) async {
+          starts++;
+        },
+        stop: (_) async {
+          stops++;
+        },
+      );
+      await registry.close();
+      await expectLater(watch.stream.first, throwsStateError);
+      expect(starts, 0);
+      expect(stops, 0);
+      expect(
+        () => registry.open(
+          session: 'late',
+          decode: (event) => event.resultUsda,
+          start: (_) async {},
+          stop: (_) async {},
+        ),
+        throwsStateError,
+      );
+    },
+  );
+
+  test(
+    'Reception close releases a paused watch locally without a per-watch stop',
+    () async {
+      // The reception closes the realm right after the registry; that one round
+      // trip releases every peer subscription. A per-watch unwatch at close
+      // would race the transport teardown (a registration still in flight
+      // completes only when the transport is disposed), so none is issued —
+      // not at close, and not when the retained listener cancels later.
+      final registry = NmsTypedWatchRegistry();
+      var stops = 0;
+      var done = false;
+      final watch = registry.open(
+        session: 'estate',
+        decode: (event) => event.resultUsda,
+        start: (_) async {},
+        stop: (_) async {
+          stops++;
+        },
+      );
+      final sub = watch.stream.listen((_) {}, onDone: () => done = true)
+        ..pause();
+      await registry.close();
+      await registry.close();
+      await Future<void>.delayed(Duration.zero);
+      expect(stops, 0);
+      await sub.cancel();
+      await Future<void>.delayed(Duration.zero);
+      expect(stops, 0);
+      expect(
+        done,
+        isFalse,
+        reason: 'a paused single-subscription stream cannot deliver done',
+      );
+    },
+  );
+
+  test('registration failure is delivered to the listener', () async {
+    final registry = NmsTypedWatchRegistry();
+    final watch = registry.open(
+      session: 'estate',
+      decode: (event) => event.resultUsda,
+      start: (_) async => throw StateError('refused'),
+      stop: (_) async {},
+    );
+    await expectLater(watch.stream.first, throwsStateError);
+    await registry.close();
+  });
+
+  test(
+    'a replica that is not ready yet delays registration, never ends the stream',
+    () async {
+      final registry = NmsTypedWatchRegistry();
+      var starts = 0;
+      final watch = registry.open(
+        session: 'estate',
+        decode: (event) => event.resultUsda,
+        start: (id) async {
+          if (++starts < 3) {
+            throw const NomosUnavailable(
+              reason: NomosUnavailableReason.localReplicaNotReady,
+              workspace: 'estate',
+              retryable: true,
+              retryAfter: Duration(milliseconds: 1),
+            );
+          }
+          registry.deliver(
+            protocol.WatchChanged(subscriptionId: id, resultUsda: [7]),
+          );
+        },
+        stop: (_) async {},
+      );
+      expect(await watch.stream.first, [7]);
+      expect(starts, 3);
+    },
+  );
+
+  test('a watch waiting for its copy registers the moment it syncs', () async {
+    final synced = StreamController<String>.broadcast();
+    final registry = NmsTypedWatchRegistry(synced: synced.stream);
+    final firstRefused = Completer<void>();
+    var starts = 0;
+    final watch = registry.open(
+      session: 'estate',
+      decode: (event) => event.resultUsda,
+      start: (id) async {
+        if (++starts == 1) {
+          firstRefused.complete();
+          // Only the sync event can end a pause this long.
+          throw const NomosUnavailable(
+            reason: NomosUnavailableReason.localReplicaNotReady,
+            workspace: 'estate',
+            retryable: true,
+            retryAfter: Duration(minutes: 1),
+          );
+        }
+        registry.deliver(
+          protocol.WatchChanged(subscriptionId: id, resultUsda: [7]),
+        );
+      },
+      stop: (_) async {},
+    );
+    final first = watch.stream.first;
+    await firstRefused.future;
+    await pumpEventQueue();
+    synced.add('estate');
+    expect(await first.timeout(const Duration(seconds: 1)), [7]);
+    expect(starts, 2);
+    await synced.close();
+  });
+
+  test('a refusal that is not retryable still ends the stream', () async {
+    final registry = NmsTypedWatchRegistry();
+    final watch = registry.open(
+      session: 'estate',
+      decode: (event) => event.resultUsda,
+      start: (_) async => throw const NomosUnavailable(
+        reason: NomosUnavailableReason.remoteOnlyOffline,
+        workspace: 'estate',
+        retryable: false,
+      ),
+      stop: (_) async {},
+    );
+    await expectLater(watch.stream.first, throwsA(isA<NomosUnavailable>()));
+  });
+}

package/dart_lints/README.md

@@ -0,0 +1,18 @@
+# Nomos reference checks
+
+Add `nomos_lints` and `custom_lint` as development dependencies and enable the
+`custom_lint` analyzer plugin. An existing lint plugin can instead register
+`NomosReferenceIdentityRule` in its rule list (as CO2's `layer_lints` does).
+
+The `nomos_reference_identity` rule supplements generated argument types where
+Dart accepts `Object`: equality and map indexing. Keep the complete typed
+reference for identity; use `.id` for display and `.address` for serialization.
+
+Run `dart run custom_lint` in CI as well as using the IDE diagnostics. The
+default command treats findings as failures. The rule recognizes Nomos's actual
+reference type, not unrelated classes that happen to have the same name.
+
+The focused test uses the Dart analyzer on deliberately invalid consumers:
+wrong aggregate and raw string arguments fail compilation; erased comparisons
+and map indices produce the additional lint. This is not a whole-program
+taint analysis of arbitrary intermediate strings.

package/dart_lints/lib/nomos_lints.dart

@@ -0,0 +1,70 @@
+import 'package:analyzer/dart/ast/ast.dart';
+import 'package:analyzer/dart/element/type.dart';
+import 'package:analyzer/error/listener.dart';
+import 'package:custom_lint_builder/custom_lint_builder.dart';
+
+PluginBase createPlugin() => _NomosLints();
+
+class _NomosLints extends PluginBase {
+  @override
+  List<LintRule> getLintRules(CustomLintConfigs configs) =>
+      [NomosReferenceIdentityRule()];
+}
+
+/// Dart equality and Map.operator[] accept Object, so generic parameter types
+/// alone cannot catch identity erased into a string at these two boundaries.
+class NomosReferenceIdentityRule extends DartLintRule {
+  NomosReferenceIdentityRule() : super(code: _code);
+  static const _code = LintCode(
+    name: 'nomos_reference_identity',
+    problemMessage:
+        'Keep the NomosRef when comparing or indexing record identity. '
+        'An extracted id loses its workspace and aggregate type.',
+  );
+
+  @override
+  void run(CustomLintResolver resolver, ErrorReporter reporter,
+      CustomLintContext context) {
+    context.registry.addBinaryExpression((node) {
+      if (violatesReferenceEquality(node)) reporter.atNode(node, _code);
+    });
+    context.registry.addIndexExpression((node) {
+      if (extractsReferenceId(node.index)) reporter.atNode(node.index, _code);
+    });
+  }
+}
+
+bool _isReference(DartType? type) =>
+    type is InterfaceType &&
+    // Analyzer 7.6 deprecates the old element API in favor of this model.
+    // ignore: experimental_member_use
+    type.element3.name3 == 'NomosRef' &&
+    // ignore: experimental_member_use
+    type.element3.library2.uri.toString().startsWith('package:nomos_types/');
+
+bool extractsReferenceId(Expression expression) {
+  if (expression is ParenthesizedExpression)
+    return extractsReferenceId(expression.expression);
+  if (expression is PropertyAccess) {
+    return expression.propertyName.name == 'id' &&
+        _isReference(expression.realTarget.staticType);
+  }
+  return expression is PrefixedIdentifier &&
+      expression.identifier.name == 'id' &&
+      _isReference(expression.prefix.staticType);
+}
+
+bool violatesReferenceEquality(BinaryExpression expression) {
+  if (expression.operator.lexeme != '==' && expression.operator.lexeme != '!=')
+    return false;
+  final left = expression.leftOperand, right = expression.rightOperand;
+  if (left is NullLiteral || right is NullLiteral) return false;
+  if (extractsReferenceId(left) || extractsReferenceId(right)) return true;
+  if (_isReference(left.staticType) && _isReference(right.staticType)) {
+    // Different aggregate parameters should never be reconciled by Object.==.
+    return left.staticType != right.staticType &&
+        (left.staticType as InterfaceType).typeArguments.single !=
+            (right.staticType as InterfaceType).typeArguments.single;
+  }
+  return _isReference(left.staticType) != _isReference(right.staticType);
+}