@githolon/dsl 0.102.4 → 0.103.0

package/dart/test/webview_bridge_test.dart

@@ -16,6 +16,7 @@ class FakeRunner implements BridgeTransport {
   final _incoming = StreamController<Map<String, Object?>>.broadcast();
   final List<Map<String, Object?>> sent = [];
   String? lastWatchSubId;
+  bool acknowledgeWatch = true;
   bool acknowledgeUnwatch = true;
 
   FakeRunner() {
@@ -109,6 +110,18 @@ class FakeRunner implements BridgeTransport {
             ]
           }));
           break;
+        case 'queryPage':
+          _incoming.add(reply({
+            'rows': [
+              {
+                'id': 'page-a',
+                'data': {'q': args['queryId']}
+              }
+            ],
+            'cursor': 'opaque-next',
+            'done': false,
+          }));
+          break;
         case 'queryById':
           _incoming.add(reply({
             'rows': [
@@ -119,6 +132,24 @@ class FakeRunner implements BridgeTransport {
             ]
           }));
           break;
+        case 'checkRefFreshness':
+          _incoming.add(reply({
+            'unique': [
+              {
+                'ref': (args['refs'] as List).single,
+                'outcome': {
+                  'status': 'stale',
+                  'latest': {
+                    'workspace': 'catalogue',
+                    'type': 'catalogue.Publication',
+                    'id': 'publication:2',
+                  },
+                },
+              },
+            ],
+            'order': [0],
+          }));
+          break;
         case 'count':
           _incoming.add(reply({'count': 7}));
           break;
@@ -232,7 +263,9 @@ class FakeRunner implements BridgeTransport {
           break;
         case 'watch':
           lastWatchSubId = args['subId'] as String;
-          _incoming.add(reply({'subId': args['subId']}));
+          if (acknowledgeWatch) {
+            _incoming.add(reply({'subId': args['subId']}));
+          }
           break;
         case 'unwatch':
           if (acknowledgeUnwatch) {
@@ -341,9 +374,6 @@ Future<Object?> _invoke(
         payload: a['payload'],
         actor: a['actor'] as String?,
         domainHash: a['domainHash'] as String?,
-        attestations: (a['attestations'] as List?)
-            ?.map((e) => (e as Map).cast<String, Object?>())
-            .toList(),
         force: a['force'] as bool?,
       );
     default:
@@ -515,6 +545,39 @@ void main() {
     await bridge.ready.timeout(const Duration(seconds: 1));
   });
 
+  test('dispose closes active watches without mutating its iteration',
+      () async {
+    await bridge.ready;
+    final subscription =
+        bridge.watch('entriesByOwner', {'owner': 'user:ada'}).listen((_) {});
+    await Future<void>.delayed(Duration.zero);
+
+    await bridge.dispose();
+    await subscription.cancel();
+  });
+
+  test('dispose does not wait for a paused watch consumer', () async {
+    await bridge.ready;
+    final subscription =
+        bridge.watch('entriesByOwner', {'owner': 'user:ada'}).listen((_) {});
+    await Future<void>.delayed(Duration.zero);
+    subscription.pause();
+
+    await bridge.dispose().timeout(const Duration(seconds: 1));
+    await subscription.cancel();
+  });
+
+  test('dispose contains an unacknowledged watch registration error', () async {
+    await bridge.ready;
+    runner.acknowledgeWatch = false;
+    final subscription =
+        bridge.watch('entriesByOwner', {'owner': 'user:ada'}).listen((_) {});
+    await Future<void>.delayed(Duration.zero);
+
+    await bridge.dispose();
+    await subscription.cancel();
+  });
+
   test('offer round-trips a typed head; args reach the runner verbatim',
       () async {
     await bridge.ready;
@@ -602,12 +665,17 @@ void main() {
   });
 
   test(
-      'connect / query / queryById / count / sync / lawStatus all wrap the runner',
+      'connect / query / queryPage / queryById / count / sync / lawStatus all wrap the runner',
       () async {
     await bridge.ready;
     await bridge.connect(cloud: 'https://c', workspace: 'ws', clientId: 'c1');
     expect((await bridge.query('byAuthor', {'author': 'ada'})).first['data'],
         {'q': 'byAuthor'});
+    final page = await bridge.queryPage('byAuthor',
+        params: {'author': 'ada'}, pageSize: 1);
+    expect(page.rows.single['id'], 'page-a');
+    expect(page.cursor, 'opaque-next');
+    expect(page.done, isFalse);
     expect((await bridge.queryById('Entry_1')).first['id'], 'Entry_1');
     expect(await bridge.count('entries'), 7);
     expect(await bridge.sync(), {'pushed': true});
@@ -615,6 +683,35 @@ void main() {
         await bridge.lawStatus('abc'), {'installed': true, 'drifted': false});
   });
 
+  test('version freshness returns the required sum type without resolving history',
+      () async {
+    await bridge.ready;
+    final reference = NmsInternalVersionedNomosRefs.create<Object, Object>(
+      pinned: NmsInternalNomosRefs.create<Object>(
+        workspace: 'catalogue',
+        type: 'catalogue.Publication',
+        id: 'publication:1',
+      ),
+      series: NmsInternalNomosRefs.create<Object>(
+        workspace: 'catalogue',
+        type: 'catalogue.Series',
+        id: 'series:1',
+      ),
+      currentField: 'currentPublication',
+    );
+
+    final freshness = await bridge.checkReferenceFreshness(reference);
+    expect(freshness, isA<ReferenceStale<Object>>());
+    expect((freshness as ReferenceStale<Object>).latest.id, 'publication:2');
+    final request = runner.sent.last;
+    expect(request['op'], 'checkRefFreshness');
+    final args = (request['args'] as Map).cast<String, Object?>();
+    final check = ((args['refs'] as List).single as Map).cast<String, Object?>();
+    expect(check['currentField'], 'currentPublication');
+    expect((check['pinned'] as Map)['id'], 'publication:1');
+    expect((check['series'] as Map)['id'], 'series:1');
+  });
+
   test(
       'moments and historic reads keep commit plumbing behind an opaque handle',
       () async {

package/dart_types/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.8.1
+
+- Carry the typed USDA-native kernel protocol, plan diagnostics, reference freshness and application
+  readiness shapes used by generated clients without exposing transport or runtime implementation details.
+
 ## 0.8.0
 
 - Make `NomosRef<T>` the canonical identity of generated business records. References carry their workspace,

package/dart_types/lib/nomos_types.dart

@@ -33,10 +33,19 @@ export 'src/foreign_ref.dart' show ForeignRef;
 export 'src/activity.dart';
 // NomosRef is inspectable but framework-created. Its constructor and wire codec stay behind the runtime.
 export 'src/nomos_ref.dart' show NomosRef;
+export 'src/versioned_nomos_ref.dart'
+    show
+        VersionedNomosRef,
+        ReferenceFreshness,
+        ReferenceCurrent,
+        ReferenceStale,
+        ReferenceFreshnessUnavailable;
+export 'src/optional_ref.dart' show NomosOptionalRef;
 export 'src/invitation.dart' show Identity, User, Recipient, Invitation;
 // Branded identity wrappers (NomosPrincipal / NomosDeviceSecret) for the generated cross-workspace
 // birth methods — actor/authorSecret are distinct types, so a transposition is a compile error.
 export 'src/principal.dart';
+export 'src/sha256_digest.dart';
 // The CUSTODY-LIFECYCLE types (rebirth_and_custody_lifecycle.md): NomosCustodyBreak / NomosCustodyStatus /
 // CustodyBreakPolicy — custody incompatibility as a first-class, typed, app-decidable event. Pure data.
 export 'src/custody.dart';

package/dart_types/lib/src/nomos_ref.dart

@@ -69,6 +69,26 @@ abstract final class NmsInternalNomosRefs {
 
   static String id<TAggregate>(NomosRef<TAggregate> reference) => reference._id;
 
+  /// Retype a concrete aggregate reference to a compiled public contract after
+  /// checking the stable wire kind. Generated version-pin factories use this
+  /// when a concrete catalogue row satisfies a cross-domain contract.
+  static NomosRef<TTo> retype<TTo>(
+    NomosRef<Object?> reference, {
+    required String expectedType,
+  }) {
+    final actual = reference._type;
+    if (actual != expectedType && !actual.endsWith('.$expectedType')) {
+      throw ArgumentError(
+        'Reference carries $actual; expected $expectedType',
+      );
+    }
+    return NomosRef<TTo>._(
+      reference._workspace,
+      reference._type,
+      reference._id,
+    );
+  }
+
   static NomosRef<TAggregate> fromJson<TAggregate>(Object? value) {
     if (value is String) return fromUri<TAggregate>(value);
     final map = (value as Map).cast<String, dynamic>();

package/dart_types/lib/src/optional_ref.dart

@@ -0,0 +1,85 @@
+// NOMOS — an optional relationship is a required business decision.
+//
+// Storage may legitimately omit a reference. Generated application inputs must
+// not turn that into an optional named argument: callers choose absent or present.
+library;
+
+import 'nomos_ref.dart';
+
+/// An explicit choice for an optional first-class Nomos relationship.
+///
+/// Generated business inputs use this instead of `NomosRef<T>?`. The input
+/// parameter itself is required, so accidentally forgetting a relationship is a
+/// compile error while a deliberately absent relationship remains representable.
+sealed class NomosOptionalRef<TAggregate> {
+  const NomosOptionalRef();
+
+  /// Deliberately omit this relationship from the offered business facts.
+  const factory NomosOptionalRef.absent() = _AbsentNomosRef<TAggregate>;
+
+  /// Supply a framework-created reference for this relationship.
+  const factory NomosOptionalRef.present(NomosRef<TAggregate> reference) =
+      _PresentNomosRef<TAggregate>;
+
+  /// True when the relationship is deliberately absent.
+  bool get isAbsent => this is _AbsentNomosRef<TAggregate>;
+
+  /// True when the relationship carries a reference.
+  bool get isPresent => this is _PresentNomosRef<TAggregate>;
+
+  /// The supplied reference, or `null` when absence was chosen explicitly.
+  NomosRef<TAggregate>? get referenceOrNull => switch (this) {
+        _PresentNomosRef<TAggregate>(:final reference) => reference,
+        _ => null,
+      };
+
+  /// Exhaustively handle the two relationship choices.
+  R when<R>({
+    required R Function() absent,
+    required R Function(NomosRef<TAggregate> reference) present,
+  }) =>
+      switch (this) {
+        _AbsentNomosRef<TAggregate>() => absent(),
+        _PresentNomosRef<TAggregate>(:final reference) => present(reference),
+      };
+
+  /// Write this choice into an action payload. Absence omits the key; presence
+  /// writes the encoded reference value.
+  void writeTo(
+    Map<String, Object?> data,
+    String key,
+    Object? Function(NomosRef<TAggregate> reference) encode,
+  ) {
+    switch (this) {
+      case _AbsentNomosRef<TAggregate>():
+        break;
+      case _PresentNomosRef<TAggregate>(:final reference):
+        data[key] = encode(reference);
+    }
+  }
+
+  @override
+  bool operator ==(Object other) =>
+      other is NomosOptionalRef<TAggregate> &&
+      other.runtimeType == runtimeType &&
+      other.referenceOrNull == referenceOrNull;
+
+  @override
+  int get hashCode => Object.hash(runtimeType, referenceOrNull);
+}
+
+final class _AbsentNomosRef<TAggregate> extends NomosOptionalRef<TAggregate> {
+  const _AbsentNomosRef();
+
+  @override
+  String toString() => 'NomosOptionalRef<$TAggregate>.absent()';
+}
+
+final class _PresentNomosRef<TAggregate> extends NomosOptionalRef<TAggregate> {
+  final NomosRef<TAggregate> reference;
+
+  const _PresentNomosRef(this.reference);
+
+  @override
+  String toString() => 'NomosOptionalRef<$TAggregate>.present($reference)';
+}

package/dart_types/lib/src/sha256_digest.dart

@@ -0,0 +1,41 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.
+
+/// A SHA-256 digest in Nomos's canonical wire spelling: exactly 64 lowercase
+/// hexadecimal characters.
+///
+/// This extension type is zero-cost on the wire and nominal in Dart: a bare
+/// [String], or a different semantic string type, cannot be passed where a
+/// [Sha256Digest] is required. Construction validates before an offer can be
+/// assembled, rather than deferring the mistake to kernel-side Zod validation.
+extension type const Sha256Digest._(String value) {
+  factory Sha256Digest(String value) {
+    if (!_isLowercaseSha256(value)) {
+      throw FormatException(
+        'expected a 64-character lowercase hexadecimal SHA-256 digest',
+        value,
+      );
+    }
+    return Sha256Digest._(value);
+  }
+
+  /// Parse a wire value. This is an explicit alias for generated decode sites
+  /// and application boundaries that prefer parser vocabulary.
+  static Sha256Digest parse(String value) => Sha256Digest(value);
+
+  /// Parse without throwing.
+  static Sha256Digest? tryParse(String value) {
+    if (!_isLowercaseSha256(value)) return null;
+    return Sha256Digest._(value);
+  }
+}
+
+bool _isLowercaseSha256(String value) {
+  if (value.length != 64) return false;
+  for (final codeUnit in value.codeUnits) {
+    final digit = codeUnit >= 0x30 && codeUnit <= 0x39;
+    final lowercaseHex = codeUnit >= 0x61 && codeUnit <= 0x66;
+    if (!digit && !lowercaseHex) return false;
+  }
+  return true;
+}

package/dart_types/lib/src/versioned_nomos_ref.dart

@@ -0,0 +1,81 @@
+// NOMOS — a version pin and its stable series (architecture/foreign_ref.md).
+//
+// This is deliberately a pure data type. The generated application owns the
+// effectful freshness check because it owns the authenticated multi-workspace
+// kernel bridge; a projected DTO never hides a runtime or global singleton.
+library;
+
+import 'nomos_ref.dart';
+
+/// An immutable publication pin together with the stable series that declares
+/// which publication is current.
+///
+/// Nomos can check this reference in O(current state): it reads the series' one
+/// compiled current-pointer field and compares that address with [pinned]. It
+/// does not resolve [pinned], reconstruct history, or retain an index of every
+/// version ever published.
+final class VersionedNomosRef<TVersion, TSeries> {
+  final NomosRef<TVersion> pinned;
+  final NomosRef<TSeries> series;
+  final String _currentField;
+
+  const VersionedNomosRef._(this.pinned, this.series, this._currentField);
+
+  @override
+  bool operator ==(Object other) =>
+      other is VersionedNomosRef<TVersion, TSeries> &&
+      other.pinned == pinned &&
+      other.series == series;
+
+  @override
+  int get hashCode => Object.hash(pinned, series);
+
+  @override
+  String toString() => 'VersionedNomosRef<$TVersion, $TSeries>';
+}
+
+/// The typed answer to a generated application's current-version check.
+sealed class ReferenceFreshness<TVersion> {
+  const ReferenceFreshness();
+}
+
+/// The pinned publication is still the series' current publication.
+final class ReferenceCurrent<TVersion> extends ReferenceFreshness<TVersion> {
+  final NomosRef<TVersion> latest;
+  const ReferenceCurrent(this.latest);
+}
+
+/// The series now points at [latest], while the reference remains pinned to an
+/// older immutable publication.
+final class ReferenceStale<TVersion> extends ReferenceFreshness<TVersion> {
+  final NomosRef<TVersion> latest;
+  const ReferenceStale(this.latest);
+}
+
+/// Nomos could not establish freshness without guessing (for example, the
+/// series is not local, denied, missing, or does not satisfy the compiled law).
+final class ReferenceFreshnessUnavailable<TVersion>
+    extends ReferenceFreshness<TVersion> {
+  final String reason;
+  const ReferenceFreshnessUnavailable(this.reason);
+}
+
+/// Framework-only construction and wire access for generated implementation
+/// code. Tenant code receives [VersionedNomosRef] and the required sum result.
+abstract final class NmsInternalVersionedNomosRefs {
+  static VersionedNomosRef<TVersion, TSeries> create<TVersion, TSeries>({
+    required NomosRef<TVersion> pinned,
+    required NomosRef<TSeries> series,
+    required String currentField,
+  }) =>
+      VersionedNomosRef<TVersion, TSeries>._(
+        pinned,
+        series,
+        currentField,
+      );
+
+  static String currentField<TVersion, TSeries>(
+    VersionedNomosRef<TVersion, TSeries> reference,
+  ) =>
+      reference._currentField;
+}

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. The hand-written serde-JSON-compatible types plus the offer codec,
   reactive read engine, schema validation, and data-only error/trace types.
-version: 0.8.0
+version: 0.8.1
 
 environment:
   sdk: ^3.5.0

package/dart_types/test/optional_ref_test.dart

@@ -0,0 +1,44 @@
+import 'package:nomos_types/nomos_types.dart';
+import 'package:nomos_types/src/nomos_ref.dart' show NmsInternalNomosRefs;
+import 'package:test/test.dart';
+
+final class Site {}
+
+void main() {
+  test('NomosOptionalRef requires an explicit absent or present choice', () {
+    const absent = NomosOptionalRef<Site>.absent();
+    final site = NmsInternalNomosRefs.create<Site>(
+      workspace: 'estate',
+      type: 'EstateSite',
+      id: 'site-1',
+    );
+    final present = NomosOptionalRef.present(site);
+
+    expect(absent.isAbsent, isTrue);
+    expect(absent.referenceOrNull, isNull);
+    expect(present.isPresent, isTrue);
+    expect(present.referenceOrNull, site);
+  });
+
+  test('NomosOptionalRef omits absence and encodes presence', () {
+    final data = <String, Object?>{};
+    const NomosOptionalRef<Site>.absent().writeTo(
+      data,
+      'siteId',
+      NmsInternalNomosRefs.id,
+    );
+    expect(data, isEmpty);
+
+    final site = NmsInternalNomosRefs.create<Site>(
+      workspace: 'estate',
+      type: 'EstateSite',
+      id: 'site-1',
+    );
+    NomosOptionalRef.present(site).writeTo(
+      data,
+      'siteId',
+      NmsInternalNomosRefs.id,
+    );
+    expect(data, {'siteId': 'site-1'});
+  });
+}

package/dart_types/test/sha256_digest_test.dart

@@ -0,0 +1,18 @@
+import 'package:nomos_types/nomos_types.dart';
+import 'package:test/test.dart';
+
+void main() {
+  test('accepts exactly 64 lowercase hexadecimal characters', () {
+    final digest = Sha256Digest('0123456789abcdef' * 4);
+    expect(digest.value, '0123456789abcdef' * 4);
+    expect(digest.toString(), digest.value);
+  });
+
+  test('refuses malformed, uppercase, and incorrectly sized values', () {
+    expect(() => Sha256Digest('abc'), throwsFormatException);
+    expect(() => Sha256Digest('A' * 64), throwsFormatException);
+    expect(() => Sha256Digest('g' * 64), throwsFormatException);
+    expect(Sha256Digest.tryParse('0' * 64)?.value, '0' * 64);
+    expect(Sha256Digest.tryParse('0' * 63), isNull);
+  });
+}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.102.4",
+  "version": "0.103.0",
   "type": "module",
+  "sideEffects": false,
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -16,21 +17,22 @@
   },
   "exports": {
     ".": "./src/index.ts",
-    "./manifest": "./src/manifest.ts",
     "./stable-ids": "./src/stable_ids.ts",
     "./compose": "./src/compose.ts",
-    "./usd": "./src/usd.ts",
-    "./usd-layers": "./src/usd_layers.ts",
     "./application-composition": "./src/application_composition.ts",
     "./usd-state": "./src/usd_state.ts",
     "./engine-entry": "./src/engine_entry.ts",
+    "./compile-proof": {
+      "types": "./compile_proof.d.mts",
+      "default": "./compile_proof.mjs"
+    },
     "./workspace-type": "./src/workspace_type.ts",
     "./workspace-routing": "./src/workspace_routing.ts",
     "./workspace-sharding": "./src/workspace_sharding.ts",
     "./build-package": "./src/build_package.ts",
-    "./compile-engine": "./src/compile_engine.ts",
     "./codegen-dart": "./src/codegen_dart.ts",
     "./codegen-dot": "./src/codegen_dot.ts",
+    "./codegen-usda": "./src/codegen_usda.ts",
     "./codegen-provider": "./src/codegen_provider_dart.ts",
     "./framework/disclosure": "./src/framework/disclosure.ts",
     "./framework/bootstrap": "./src/framework/bootstrap.ts",
@@ -51,6 +53,8 @@
     "!dart_types/.dart_tool",
     "!dart_types/build",
     "runtime",
+    "compile_proof.mjs",
+    "compile_proof.d.mts",
     "compile_package.mjs",
     "check_package.mjs",
     "compat_package.mjs",