@githolon/dsl 0.108.7 → 0.110.0

package/dart_types/lib/src/proto/nomos/runtime/v2/sealing_desk.pbenum.dart

@@ -0,0 +1,46 @@
+// This is a generated file - do not edit.
+//
+// Generated from nomos/runtime/v2/sealing_desk.proto.
+
+// @dart = 3.3
+
+// ignore_for_file: annotate_overrides, camel_case_types, comment_references
+// ignore_for_file: constant_identifier_names
+// ignore_for_file: curly_braces_in_flow_control_structures
+// ignore_for_file: deprecated_member_use_from_same_package, library_prefixes
+// ignore_for_file: non_constant_identifier_names
+
+import 'dart:core' as $core;
+
+import 'package:protobuf/protobuf.dart' as $pb;
+
+class OwnedRecordAction extends $pb.ProtobufEnum {
+  static const OwnedRecordAction OWNED_RECORD_ACTION_UNSPECIFIED =
+      OwnedRecordAction._(
+          0, _omitEnumNames ? '' : 'OWNED_RECORD_ACTION_UNSPECIFIED');
+  static const OwnedRecordAction OWNED_RECORD_ACTION_SHARE =
+      OwnedRecordAction._(1, _omitEnumNames ? '' : 'OWNED_RECORD_ACTION_SHARE');
+  static const OwnedRecordAction OWNED_RECORD_ACTION_UNSHARE =
+      OwnedRecordAction._(
+          2, _omitEnumNames ? '' : 'OWNED_RECORD_ACTION_UNSHARE');
+  static const OwnedRecordAction OWNED_RECORD_ACTION_TRANSFER =
+      OwnedRecordAction._(
+          3, _omitEnumNames ? '' : 'OWNED_RECORD_ACTION_TRANSFER');
+
+  static const $core.List<OwnedRecordAction> values = <OwnedRecordAction>[
+    OWNED_RECORD_ACTION_UNSPECIFIED,
+    OWNED_RECORD_ACTION_SHARE,
+    OWNED_RECORD_ACTION_UNSHARE,
+    OWNED_RECORD_ACTION_TRANSFER,
+  ];
+
+  static final $core.List<OwnedRecordAction?> _byValue =
+      $pb.ProtobufEnum.$_initByValueList(values, 3);
+  static OwnedRecordAction? valueOf($core.int value) =>
+      value < 0 || value >= _byValue.length ? null : _byValue[value];
+
+  const OwnedRecordAction._(super.value, super.name);
+}
+
+const $core.bool _omitEnumNames =
+    $core.bool.fromEnvironment('protobuf.omit_enum_names');

package/dart_types/lib/src/runtime_outcome.dart

@@ -0,0 +1,133 @@
+/// Closed, presentation-safe terminal outcomes from the Peer Runtime.
+///
+/// These are facts, not repair procedures. A frontend can exhaustively project
+/// them into its own state vocabulary without parsing diagnostics or taking
+/// ownership of workspace, custody, replica-follow or retry lifecycles.
+library;
+
+import 'proto/nomos/runtime/v2/observability_desk.pb.dart'
+    show RuntimeUnavailable;
+import 'proto/nomos/runtime/v2/observability_desk.pbenum.dart'
+    show RuntimeUnavailableReason;
+
+enum NomosUnavailableReason {
+  remoteOnlyOffline,
+  remoteUnreachable,
+  remoteTimeout,
+  localReplicaNotReady,
+  credentialUnavailable,
+  workspaceOpening,
+  unknown,
+}
+
+final class NomosUnavailable implements Exception {
+  const NomosUnavailable({
+    required this.reason,
+    required this.workspace,
+    required this.retryable,
+    this.retryAfter,
+    this.detail = '',
+  });
+
+  final NomosUnavailableReason reason;
+  final String workspace;
+  final bool retryable;
+  final Duration? retryAfter;
+
+  /// Diagnostic prose for logs/support. Application control flow uses
+  /// [reason], [retryable] and [retryAfter], never this value.
+  final String detail;
+
+  /// The one translation of the generated `unavailable` arm, for every transport.
+  factory NomosUnavailable.fromRuntime(RuntimeUnavailable unavailable) =>
+      NomosUnavailable(
+        reason: switch (unavailable.reason) {
+          RuntimeUnavailableReason
+                .RUNTIME_UNAVAILABLE_REASON_REMOTE_ONLY_OFFLINE =>
+            NomosUnavailableReason.remoteOnlyOffline,
+          RuntimeUnavailableReason
+                .RUNTIME_UNAVAILABLE_REASON_REMOTE_UNREACHABLE =>
+            NomosUnavailableReason.remoteUnreachable,
+          RuntimeUnavailableReason.RUNTIME_UNAVAILABLE_REASON_REMOTE_TIMEOUT =>
+            NomosUnavailableReason.remoteTimeout,
+          RuntimeUnavailableReason
+                .RUNTIME_UNAVAILABLE_REASON_LOCAL_REPLICA_NOT_READY =>
+            NomosUnavailableReason.localReplicaNotReady,
+          RuntimeUnavailableReason
+                .RUNTIME_UNAVAILABLE_REASON_CREDENTIAL_UNAVAILABLE =>
+            NomosUnavailableReason.credentialUnavailable,
+          RuntimeUnavailableReason
+                .RUNTIME_UNAVAILABLE_REASON_WORKSPACE_OPENING =>
+            NomosUnavailableReason.workspaceOpening,
+          _ => NomosUnavailableReason.unknown,
+        },
+        workspace: unavailable.workspace,
+        retryable: unavailable.retryable,
+        retryAfter: unavailable.hasRetryAfterMillis()
+            ? Duration(milliseconds: unavailable.retryAfterMillis)
+            : null,
+        detail: unavailable.detail,
+      );
+
+  @override
+  String toString() =>
+      'NomosUnavailable(${reason.name}, workspace: $workspace, retryable: $retryable'
+      '${detail.isEmpty ? '' : ', detail: $detail'})';
+}
+
+enum NomosRefusalReason {
+  invalidCredential,
+  accessDenied,
+  placementPolicy,
+  sessionUnbound,
+  unknown,
+}
+
+final class NomosRefused implements Exception {
+  const NomosRefused({
+    required this.reason,
+    required this.workspace,
+    required this.retryable,
+    this.detail = '',
+  });
+
+  final NomosRefusalReason reason;
+  final String workspace;
+  final bool retryable;
+
+  /// Diagnostic prose only; [reason] is the exhaustive control value.
+  final String detail;
+
+  @override
+  String toString() =>
+      'NomosRefused(${reason.name}, workspace: $workspace, retryable: $retryable)';
+}
+
+enum NomosRuntimeFailureKind {
+  internal,
+  protocol,
+  integrity,
+  unsupported,
+  unknown,
+}
+
+final class NomosRuntimeFailure implements Exception {
+  const NomosRuntimeFailure({
+    required this.kind,
+    required this.code,
+    required this.message,
+    required this.component,
+    this.workspace,
+  });
+
+  final NomosRuntimeFailureKind kind;
+  final String code;
+  final String message;
+  final String component;
+  final String? workspace;
+
+  @override
+  String toString() =>
+      'NomosRuntimeFailure(${kind.name}, $code, component: $component'
+      '${message.isEmpty ? '' : ', message: $message'})';
+}

package/dart_types/lib/src/subscriptions.dart

@@ -95,15 +95,23 @@ class NomosReads {
 
   /// The maintained-count seam (`client.count`). Reads ONE maintained counter
   /// by `(countId, groupKey)` — O(1) PK lookup, never a scan. Threads in from the
-  /// app's host client (Slice 1). When null, `readCount`/`watchCount` return 0
-  /// (no count seam provided — useful in tests that don't exercise counts).
+  /// app's host client. A missing callback is unsupported, not an empty group.
   final Counter? counter;
 
   /// The maintained-sum seam (`client.sum`). Reads ONE maintained sum by
   /// `(sumId, groupKey)` — O(1) PK lookup, never a scan. Threads in from the
-  /// app's host client (Slice 1). When null, `readSum`/`watchSum` return 0.
+  /// app's host client. A missing callback is unsupported, not a zero sum.
   final Summer? summer;
 
+  /// Snapshot read callbacks for declared extrema. Missing support refuses; it
+  /// must not masquerade as an empty group. Live clients use async Reception.
+  final int? Function(String id, String groupKey)? minimum;
+  final int? Function(String id, String groupKey)? maximum;
+
+  /// Ordered snapshot rows, already selected under installed law and authority.
+  /// No caller-supplied limit/order goes to this callback. Live clients use Reception.
+  final String Function(String id)? ordered;
+
   /// The "projection changed" tick. When null, every accessor is a ONE-SHOT read
   /// (a single current value, no further updates) — used in tests / pure snapshots.
   final ReadTick? tick;
@@ -113,6 +121,9 @@ class NomosReads {
     required this.queryById,
     this.counter,
     this.summer,
+    this.minimum,
+    this.maximum,
+    this.ordered,
     this.tick,
   });
 
@@ -131,7 +142,8 @@ class NomosReads {
   ) {
     final decoded = jsonDecode(rowsJson);
     if (decoded is! List) {
-      throw FormatException('read rows must be a JSON array, got ${decoded.runtimeType}');
+      throw FormatException(
+          'read rows must be a JSON array, got ${decoded.runtimeType}');
     }
     final out = <T>[];
     for (final row in decoded) {
@@ -192,27 +204,97 @@ class NomosReads {
 
   // ---- maintained count/sum seams (Slice 1) ----
 
+  T? readFirst<T>(
+      String id, T Function(Map<String, dynamic>, String) fromJson) {
+    final rows = readTake(id, 1, fromJson);
+    return rows.isEmpty ? null : rows.single;
+  }
+
+  /// [limit] validates the generated result contract; it never selects rows locally.
+  List<T> readTake<T>(
+      String id, int limit, T Function(Map<String, dynamic>, String) fromJson) {
+    final read = ordered;
+    if (read == null)
+      throw UnsupportedError('Declared ordered reads are not bound');
+    if (limit < 1) throw ArgumentError.value(limit, 'limit');
+    final rows = jsonDecode(read(id));
+    if (rows is! List || rows.length > limit)
+      throw const FormatException(
+          'Ordered result violates its declared cardinality');
+    return rows.map((row) {
+      if (row is! Map<String, dynamic> ||
+          row['data'] is! Map<String, dynamic> ||
+          row['id'] is! String)
+        throw const FormatException('Ordered result contains a malformed row');
+      return fromJson(row['data'] as Map<String, dynamic>, row['id'] as String);
+    }).toList(growable: false);
+  }
+
+  Stream<T?> watchFirst<T>(
+          String id, T Function(Map<String, dynamic>, String) fromJson) =>
+      _reactive(() => readFirst(id, fromJson));
+
+  Stream<List<T>> watchTake<T>(String id, int limit,
+          T Function(Map<String, dynamic>, String) fromJson) =>
+      _reactive(() => readTake(id, limit, fromJson));
+
   /// Read the current maintained counter for [countId] + [groupKey] NOW. Returns 0
   /// when no entry exists (either truly zero, or no group for this key). O(1) PK
-  /// lookup in the `counts` table — never a scan. Returns 0 when [counter] is null
-  /// (no count seam provided — useful in tests).
-  int readCount(String countId, String groupKey) => counter?.call(countId, groupKey) ?? 0;
+  /// lookup in the `counts` table — never a scan. Missing support refuses.
+  int readCount(String countId, String groupKey) {
+    final read = counter;
+    if (read == null)
+      throw UnsupportedError('Declared count reads are not bound');
+    final count = read(countId, groupKey);
+    if (count < 0) throw StateError('Negative membership count');
+    return count;
+  }
+
+  /// Existence uses the same maintained count; a zero-valued member still exists.
+  bool readExists(String id, String groupKey) => readCount(id, groupKey) > 0;
+
+  Stream<bool> watchExists(String id, String groupKey) =>
+      _reactive(() => readExists(id, groupKey));
 
   /// Subscribe to the maintained counter for [countId] + [groupKey] as a
   /// `Stream<int>`. Emits the current count immediately, then re-emits on every
-  /// [tick]. Returns 0 when [counter] is null.
+  /// [tick]. Missing support refuses.
   Stream<int> watchCount(String countId, String groupKey) =>
       _reactive(() => readCount(countId, groupKey));
 
   /// Read the current maintained sum for [sumId] + [groupKey] NOW. Returns 0 when
   /// no entry exists (a group pruned at 0 is indistinguishable from absent —
   /// documented Slice-1 caveat). O(1) PK lookup in the `sums` table — never a scan.
-  /// Returns 0 when [summer] is null.
-  int readSum(String sumId, String groupKey) => summer?.call(sumId, groupKey) ?? 0;
+  /// Missing support refuses.
+  int readSum(String sumId, String groupKey) {
+    final read = summer;
+    if (read == null)
+      throw UnsupportedError('Declared sum reads are not bound');
+    return read(sumId, groupKey);
+  }
+
+  int? readMin(String id, String groupKey) {
+    final read = minimum;
+    if (read == null)
+      throw UnsupportedError('Declared min reads are not bound');
+    return read(id, groupKey);
+  }
+
+  int? readMax(String id, String groupKey) {
+    final read = maximum;
+    if (read == null)
+      throw UnsupportedError('Declared max reads are not bound');
+    return read(id, groupKey);
+  }
+
+  Stream<int?> watchMin(String id, String groupKey) =>
+      _reactive(() => readMin(id, groupKey));
+
+  Stream<int?> watchMax(String id, String groupKey) =>
+      _reactive(() => readMax(id, groupKey));
 
   /// Subscribe to the maintained sum for [sumId] + [groupKey] as a `Stream<int>`.
-  /// Emits the current total immediately, then re-emits on every [tick]. Returns 0
-  /// when [summer] is null.
+  /// Emits the current total immediately, then re-emits on every [tick].
   Stream<int> watchSum(String sumId, String groupKey) =>
       _reactive(() => readSum(sumId, groupKey));
 
@@ -281,21 +363,24 @@ int readInt(Map<String, dynamic> data, String aggregate, String field) {
     final n = int.tryParse(v);
     if (n != null) return n;
   }
-  throw FormatException('$aggregate.$field: expected int, got ${v.runtimeType}');
+  throw FormatException(
+      '$aggregate.$field: expected int, got ${v.runtimeType}');
 }
 
 /// Read a `set`-kind field as a `Set<String>` (the projection emits a JSON array).
 Set<String> readSet(Map<String, dynamic> data, String aggregate, String field) {
   final v = _required(data, aggregate, field);
   if (v is List) return v.map((e) => e.toString()).toSet();
-  throw FormatException('$aggregate.$field: expected a set/array, got ${v.runtimeType}');
+  throw FormatException(
+      '$aggregate.$field: expected a set/array, got ${v.runtimeType}');
 }
 
 /// Read a `map`-kind field as a `Map<String, String>`. The projection may emit it
 /// as a flat `{k:v}` object (the loss-less author path) OR — if it folded through a
 /// kernel `Value::Map` — as the structural `{"Map":{k:{value:{Str:v},…}}}` serde
 /// form; both are reduced to `{k:v}` so the aggregate's typed map is stable.
-Map<String, String> readStrMap(Map<String, dynamic> data, String aggregate, String field) {
+Map<String, String> readStrMap(
+    Map<String, dynamic> data, String aggregate, String field) {
   final v = _required(data, aggregate, field);
   if (v is Map) {
     // Structural kernel `Value::Map` form: `{"Map": {k: {value:{Str:..},stamp:..}}}`.
@@ -308,7 +393,8 @@ Map<String, String> readStrMap(Map<String, dynamic> data, String aggregate, Stri
       return out;
     }
   }
-  throw FormatException('$aggregate.$field: expected a map/object, got ${v.runtimeType}');
+  throw FormatException(
+      '$aggregate.$field: expected a map/object, got ${v.runtimeType}');
 }
 
 /// Reduce one map entry value to a String, peeling the kernel `{value:{Str:..}}`
@@ -317,8 +403,10 @@ String _flattenMapValue(Object? val) {
   if (val is String) return val;
   if (val is Map) {
     final value = val['value'];
-    if (value is Map && value.containsKey('Str')) return value['Str'].toString();
-    if (value is Map && value.containsKey('Int')) return value['Int'].toString();
+    if (value is Map && value.containsKey('Str'))
+      return value['Str'].toString();
+    if (value is Map && value.containsKey('Int'))
+      return value['Int'].toString();
   }
   return val.toString();
 }
@@ -446,7 +534,8 @@ int? readIntOrNull(Map<String, dynamic> data, String aggregate, String field) {
     final n = int.tryParse(v);
     if (n != null) return n;
   }
-  throw FormatException('$aggregate.$field: expected int, got ${v.runtimeType}');
+  throw FormatException(
+      '$aggregate.$field: expected int, got ${v.runtimeType}');
 }
 
 /// Read an OPTIONAL enum-kind field's wire string, or `null` when absent (a present
@@ -473,17 +562,20 @@ String? readJsonStrOrNull(Map<String, dynamic> data, String field) {
 /// Read a `set`-kind field as a `Set<String>`, defaulting to EMPTY when the flat
 /// `data` lacks it (a freshly-created aggregate need not have folded the set). A
 /// PRESENT-but-non-array value still throws (parity with [readSet]).
-Set<String> readSetOrEmpty(Map<String, dynamic> data, String aggregate, String field) {
+Set<String> readSetOrEmpty(
+    Map<String, dynamic> data, String aggregate, String field) {
   final v = data[field];
   if (v == null) return <String>{};
   if (v is List) return v.map((e) => e.toString()).toSet();
-  throw FormatException('$aggregate.$field: expected a set/array, got ${v.runtimeType}');
+  throw FormatException(
+      '$aggregate.$field: expected a set/array, got ${v.runtimeType}');
 }
 
 /// Read a `map`-kind field as a `Map<String, String>`, defaulting to EMPTY when
 /// absent. A PRESENT value is reduced exactly as [readStrMap] (handling both the flat
 /// `{k:v}` form and the structural kernel `Value::Map` form).
-Map<String, String> readStrMapOrEmpty(Map<String, dynamic> data, String aggregate, String field) {
+Map<String, String> readStrMapOrEmpty(
+    Map<String, dynamic> data, String aggregate, String field) {
   final v = data[field];
   if (v == null) return <String, String>{};
   return readStrMap(data, aggregate, field);
@@ -515,7 +607,8 @@ Map<String, Object?> readJsonMapOrEmpty(
       return out;
     }
   }
-  throw FormatException('$aggregate.$field: expected a map/object, got ${v.runtimeType}');
+  throw FormatException(
+      '$aggregate.$field: expected a map/object, got ${v.runtimeType}');
 }
 
 /// Decode one JSON-valued map entry to its object: peel the kernel

package/dart_types/pubspec.yaml

@@ -9,7 +9,7 @@ description: >-
   Pure kernel wire/data types for Nomos Dart frontends — no transport, no bridge,
   no runtime. Typed protobuf and USDA boundary values plus the offer codec,
   reactive read engine, schema validation, and data-only error/trace types.
-version: 0.10.1
+version: 0.11.2
 
 environment:
   sdk: ^3.5.0

package/dart_types/test/extremum_subscriptions_test.dart

@@ -0,0 +1,40 @@
+import 'package:nomos_types/src/subscriptions.dart';
+import 'package:test/test.dart';
+
+void main() {
+  test('snapshot membership is a count, not a sum or missing callback',
+      () async {
+    final reads = NomosReads(
+        query: (_, __) => '[]',
+        queryById: (_) => '[]',
+        counter: (_, group) => group == 'empty' ? 0 : 2,
+        summer: (_, __) => 0);
+    expect(reads.readExists('hasMembers', 'empty'), false);
+    expect(await reads.watchExists('hasMembers', 'filled').first, true);
+    expect(reads.readSum('total', 'filled'), 0);
+    final unbound = NomosReads(query: (_, __) => '[]', queryById: (_) => '[]');
+    expect(() => unbound.readExists('hasMembers', ''), throwsUnsupportedError);
+    expect(() => unbound.readCount('count', ''), throwsUnsupportedError);
+    expect(() => unbound.readSum('total', ''), throwsUnsupportedError);
+    final invalid = NomosReads(
+        query: (_, __) => '[]', queryById: (_) => '[]', counter: (_, __) => -1);
+    expect(() => invalid.readExists('hasMembers', ''), throwsStateError);
+  });
+  test(
+      'snapshot extrema preserve null and zero without inventing missing support',
+      () async {
+    final reads = NomosReads(
+        query: (_, __) => '[]',
+        queryById: (_) => '[]',
+        minimum: (_, group) => group == 'empty' ? null : 0,
+        maximum: (_, group) => group == 'empty' ? null : 7);
+    expect(reads.readMin('minimum', 'empty'), isNull);
+    expect(reads.readMin('minimum', 'filled'), 0);
+    expect(await reads.watchMin('minimum', 'filled').first, 0);
+    expect(await reads.watchMax('maximum', 'empty').first, isNull);
+    expect(reads.readMax('maximum', 'filled'), 7);
+    final unbound = NomosReads(query: (_, __) => '[]', queryById: (_) => '[]');
+    expect(() => unbound.readMin('minimum', ''), throwsUnsupportedError);
+    expect(() => unbound.readMax('maximum', ''), throwsUnsupportedError);
+  });
+}

package/dart_types/test/foreign_ref_resolution_test.dart

@@ -0,0 +1,75 @@
+import 'dart:typed_data';
+import 'package:nomos_types/src/foreign_ref.dart';
+import 'package:test/test.dart';
+
+class Reader implements NomosForeignReader {
+  Reader(this.read);
+  final Future<Uint8List> Function() read;
+  @override
+  NomosForeignWorkspaceReader foreignWorkspace(String workspace) =>
+      WorkspaceReader(read);
+}
+
+class WorkspaceReader extends NomosForeignWorkspaceReader {
+  WorkspaceReader(this.read);
+  final Future<Uint8List> Function() read;
+  @override
+  Future<Uint8List> queryById(String aggregateType, String id) => read();
+}
+
+void main() {
+  final ref = NmsInternalForeignRefs.create<String>(
+      id: 'definition-1',
+      workspace: 'field-library',
+      type: 'FieldDefinition',
+      fromUsda: (bytes, _, __) => bytes.isEmpty ? null : 'found');
+  test('only a successful absent result resolves to null', () async {
+    expect(
+        await NmsInternalForeignRefs.resolve(
+            ref, Reader(() async => Uint8List(0))),
+        isNull);
+    expect(
+        await NmsInternalForeignRefs.resolve(
+            ref, Reader(() async => Uint8List(1))),
+        'found');
+  });
+  test(
+      'denial and offline transport remain failures with payload-free provenance',
+      () async {
+    for (final example in [
+      (
+        StateError('UNAUTHORIZED sensitive-value'),
+        ForeignReadFailureKind.denied
+      ),
+      (
+        StateError('offline sensitive-value'),
+        ForeignReadFailureKind.unreachable
+      ),
+    ]) {
+      try {
+        await NmsInternalForeignRefs.resolve(
+            ref, Reader(() async => throw example.$1));
+        fail('a failed read must not become a missing record');
+      } on ForeignReadFailure catch (failure) {
+        expect(failure.kind, example.$2);
+        expect(failure.workspace, 'field-library');
+        expect(failure.id, 'definition-1');
+        expect(failure.toString(), isNot(contains('sensitive-value')));
+      }
+    }
+  });
+  test('a missing generated nominal codec is a failure, never missing data',
+      () async {
+    final locator = NmsInternalForeignRefs.create<String>(
+        id: 'definition-1',
+        workspace: 'field-library',
+        type: 'FieldDefinition');
+    expect(
+        () => NmsInternalForeignRefs.resolve(
+            locator, Reader(() async => Uint8List(1))),
+        throwsA(isA<ForeignReadFailure>().having(
+            (failure) => failure.sourceErrorType,
+            'source type',
+            'StateError')));
+  });
+}

package/dart_types/test/nomos_ref_address_test.dart

@@ -0,0 +1,25 @@
+import 'package:nomos_types/src/nomos_ref.dart';
+import 'package:test/test.dart';
+
+class Drawing {}
+
+void main() {
+  test(
+      'address round trip preserves identity, including literal percent escapes',
+      () {
+    for (final id in [
+      'plain',
+      'floor/one',
+      '50% complete',
+      '%2F',
+      'a?#b',
+      'Étage 1'
+    ]) {
+      final ref = NmsInternalNomosRefs.create<Drawing>(
+          workspace: 'estate-test', type: 'estate.SiteDrawing', id: id);
+      final restored = NmsInternalNomosRefs.fromUri<Drawing>(ref.address);
+      expect(restored, ref, reason: id);
+      expect(restored.id, id);
+    }
+  });
+}

package/dart_types/test/ordered_subscriptions_test.dart

@@ -0,0 +1,34 @@
+import 'dart:convert';
+import 'package:nomos_types/src/subscriptions.dart';
+import 'package:test/test.dart';
+
+void main() {
+  String decode(Map<String, dynamic> data, String id) => id;
+  test(
+      'ordered snapshots preserve selection order and reject invalid cardinality',
+      () async {
+    final rows = <Object>[];
+    final calls = <String>[];
+    final reads = NomosReads(
+        query: (_, __) => throw StateError('not a keyed query'),
+        queryById: (_) => throw StateError('not a primary-key query'),
+        ordered: (id) {
+          calls.add(id);
+          return jsonEncode(rows);
+        });
+    expect(reads.readFirst('first', decode), isNull);
+    expect(await reads.watchTake('top', 2, decode).first, isEmpty);
+    rows.add({'id': 'z', 'data': {}});
+    expect(await reads.watchFirst('first', decode).first, 'z');
+    rows.add({'id': 'a', 'data': {}});
+    expect(reads.readTake('top', 2, decode), ['z', 'a']);
+    expect(() => reads.readFirst('first', decode), throwsFormatException);
+    rows
+      ..clear()
+      ..add({'id': 123, 'data': {}});
+    expect(() => reads.readTake('top', 2, decode), throwsFormatException);
+    expect(calls, everyElement(anyOf('first', 'top')));
+    final missing = NomosReads(query: (_, __) => '[]', queryById: (_) => '[]');
+    expect(() => missing.readFirst('first', decode), throwsUnsupportedError);
+  });
+}

package/operation_contract_check.mjs

@@ -0,0 +1,24 @@
+// Compiler-only, read-only invocation of the kernel's contract checker.
+// No peer, workspace, credentials, offers or second execution lifecycle.
+import { WASI } from 'node:wasi';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const input = process.argv[2];
+const descriptors = process.argv[3];
+if (!input) throw new Error('operation contract checker needs a compiled law package');
+const artifact = new URL('./assets/operation-contract.wasm', import.meta.url);
+const wasi = new WASI({
+  version: 'preview1',
+  args: ['operation-contract', 'validate-operation-contracts', `/input/${path.basename(input)}`,
+    ...(descriptors === undefined ? [] : [`/descriptors/${path.basename(descriptors)}`])],
+  env: {}, preopens: { '/input': path.dirname(path.resolve(input)),
+    ...(descriptors === undefined ? {} : { '/descriptors': path.dirname(path.resolve(descriptors)) }) }, returnOnExit: true,
+});
+let bytes;
+try { bytes = readFileSync(artifact); }
+catch { throw new Error(`compiler package is incomplete: missing ${fileURLToPath(artifact)}; reinstall @githolon/dsl`); }
+const module = await WebAssembly.compile(bytes);
+const instance = await WebAssembly.instantiate(module, { wasi_snapshot_preview1: wasi.wasiImport });
+process.exitCode = wasi.start(instance);