@githolon/dsl 0.10.0 → 0.12.0

package/dart/example/nomos_webview_transport.dart

@@ -0,0 +1,63 @@
+// COPY THIS INTO YOUR FLUTTER APP. It is an EXAMPLE, not part of the `nomos_dsl` library: it depends on
+// `webview_flutter`, which the pure-Dart `nomos_dsl` package deliberately does NOT depend on (so the bridge
+// protocol logic stays Flutter-free and unit-testable). This ~50-line transport is the only app-specific glue.
+//
+// It implements `BridgeTransport` (from `package:nomos_dsl/nomos_dsl.dart`) over a `webview_flutter`
+// WebViewController loading the published `nomos-runner` bundle:
+//   • host → runner: `controller.runJavaScript("window.__nomosSend(<json>)")`
+//   • runner → host: a `JavaScriptChannel("NomosHost")` whose onMessage feeds the bridge's message stream.
+//
+// WIRING (in your widget's initState):
+//   final controller = WebViewController()
+//     ..setJavaScriptMode(JavaScriptMode.unrestricted);
+//   final transport = WebViewTransport(controller);          // registers the NomosHost channel
+//   await controller.loadFlutterAsset('assets/nomos/nomos-runner.html');
+//   final bridge = NomosBridge(transport);
+//   await bridge.ready;                                       // resolves on the runner's {event:ready}
+//   await bridge.connect(cloud: 'https://nomos.captainapp.co.uk', workspace: myWs, clientId: deviceId);
+//   final head = await bridge.dispatch(domain: 'guestbook', directiveId: 'signGuestbook',
+//       payload: {'author': 'ada', 'message': 'hi', 'mood': 'delighted'}, domainHash: GUESTBOOK_DOMAIN_HASH);
+//   final rows = await bridge.query('entriesByAuthor', {'author': 'ada'});
+//
+// (Put the runner bundle at `assets/nomos/nomos-runner.{html,js}` and declare it under `flutter: assets:`.)
+
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:nomos_dsl/nomos_dsl.dart';
+import 'package:webview_flutter/webview_flutter.dart';
+
+/// A [BridgeTransport] over a `webview_flutter` controller hosting the `nomos-runner` bundle.
+class WebViewTransport implements BridgeTransport {
+  final WebViewController controller;
+  final _incoming = StreamController<Map<String, Object?>>.broadcast();
+
+  WebViewTransport(this.controller) {
+    // runner → host: the bundle posts JSON strings on the "NomosHost" channel.
+    controller.addJavaScriptChannel(
+      'NomosHost',
+      onMessageReceived: (JavaScriptMessage m) {
+        try {
+          final decoded = jsonDecode(m.message);
+          if (decoded is Map) _incoming.add(decoded.cast<String, Object?>());
+        } catch (_) {/* a non-JSON console line — ignore */}
+      },
+    );
+  }
+
+  @override
+  Stream<Map<String, Object?>> get messages => _incoming.stream;
+
+  @override
+  void send(Map<String, Object?> message) {
+    // host → runner: hand the JSON to the bundle. Double-encode so it survives as a JS string literal.
+    final json = jsonEncode(message);
+    controller.runJavaScript('window.__nomosSend(${jsonEncode(json)})');
+  }
+
+  /// Call once, right after the page finishes loading (e.g. from `NavigationDelegate.onPageFinished`), so the
+  /// runner flushes any message (the initial `{event:"ready"}`) it emitted before this channel was wired.
+  void flushReady() => controller.runJavaScript('window.__nomosReady && window.__nomosReady()');
+
+  void dispose() => _incoming.close();
+}

package/dart/lib/nomos_dsl.dart

@@ -28,6 +28,9 @@ export 'src/driver.dart';
 export 'src/dispatch.dart';
 export 'src/subscriptions.dart';
 export 'src/schema_validation.dart';
+// THE WEBVIEW BRIDGE (app-binding boundary) — the async Dart runtime that drives the REAL githolon running
+// in a WebView, so the generated typed client never needs a `MemoryPersistence` fake.
+export 'src/webview_bridge.dart';
 // The PROVIDER boundary (server-side capability-provider SDK runtime: TaskOutcome /
 // TaskSuccess / TaskFailure / TaskResult / TaskProvider / HostClock). The symmetric twin
 // of `dispatch.dart`; the generated per-task provider classes build on it.

package/dart/lib/src/webview_bridge.dart

@@ -0,0 +1,161 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/// THE WEBVIEW BRIDGE — the Dart half of the app-binding boundary. A Flutter app talks to the REAL githolon
+/// (the `@githolon/client` runner running in a WebView on mobile / the same page on Flutter web) over ONE
+/// stable message protocol, so the generated typed Dart client drives the real kernel — never a
+/// `MemoryPersistence` pretending to be a GitHolon.
+///
+/// A WebView round-trip is ASYNC, so the bridge is async (unlike the sync FRB `Authorer` in `dispatch.dart`).
+/// The generated per-domain Dart client wraps a [NomosBridge]; the bridge owns request/reply correlation +
+/// reactive `watch` streams. The platform TRANSPORT ([BridgeTransport]) is injected — `dart:js_util` on web,
+/// a WebView JS-channel on mobile — so this protocol logic is pure Dart + fully unit-testable.
+library;
+
+import 'dart:async';
+
+/// The protocol version the runner and the bridge agree on (`webview-runner.mjs` `WEBVIEW_BRIDGE_VERSION`).
+const int kWebviewBridgeVersion = 1;
+
+/// The platform channel to the WebView runner: send a JSON-shaped message; receive the runner's messages.
+/// Web impl jsifies/dartifies over `dart:js_util`; mobile impl JSON-encodes over a WebView JS-channel. The
+/// bridge treats messages as plain `Map<String, Object?>` — the transport owns the channel serialization.
+abstract interface class BridgeTransport {
+  void send(Map<String, Object?> message);
+  Stream<Map<String, Object?>> get messages;
+}
+
+/// A typed refusal surfaced from the githolon's gate (a law refusal, a drift, a malformed op). Carries the
+/// human-first message verbatim — the generated client lets it throw, loudly, exactly like the TS client.
+class NomosBridgeError implements Exception {
+  final String message;
+  NomosBridgeError(this.message);
+  @override
+  String toString() => 'NomosBridgeError: $message';
+}
+
+/// THE BRIDGE. Construct over a [BridgeTransport], `await ready`, then `connect(...)` and drive the holon.
+class NomosBridge {
+  final BridgeTransport _transport;
+  final Map<int, Completer<Object?>> _pending = {};
+  final Map<String, StreamController<List<dynamic>>> _watches = {};
+  final Completer<void> _ready = Completer<void>();
+  int _seq = 0;
+  late final StreamSubscription<Map<String, Object?>> _sub;
+
+  NomosBridge(this._transport) {
+    _sub = _transport.messages.listen(_onMessage);
+  }
+
+  /// Completes once the runner has posted `{ event: "ready" }` (the wasm + client are booted).
+  Future<void> get ready => _ready.future;
+
+  void _onMessage(Map<String, Object?> m) {
+    if (m['v'] != kWebviewBridgeVersion) return; // a foreign-version message is ignored (forward-compatible)
+    final event = m['event'];
+    if (event == 'ready') {
+      if (!_ready.isCompleted) _ready.complete();
+      return;
+    }
+    if (event == 'watch') {
+      final ctrl = _watches[m['subId']];
+      if (ctrl != null && !ctrl.isClosed) ctrl.add((m['rows'] as List?) ?? const []);
+      return;
+    }
+    final id = m['id'];
+    if (id is! int) return;
+    final completer = _pending.remove(id);
+    if (completer == null) return;
+    if (m['ok'] == true) {
+      completer.complete(m['result']);
+    } else {
+      completer.completeError(NomosBridgeError((m['error'] ?? 'the githolon refused the request').toString()));
+    }
+  }
+
+  /// Send one request and await the typed reply (the runner answers ok/error). The ONLY low-level call —
+  /// every typed method below is a thin wrapper, so the request/reply contract lives in exactly one place.
+  Future<Object?> _call(String op, [Map<String, Object?> args = const {}]) {
+    final id = ++_seq;
+    final completer = Completer<Object?>();
+    _pending[id] = completer;
+    _transport.send({'v': kWebviewBridgeVersion, 'id': id, 'op': op, 'args': args});
+    return completer.future;
+  }
+
+  Map<String, Object?> _asMap(Object? v) => (v as Map?)?.cast<String, Object?>() ?? const {};
+  List<Map<String, dynamic>> _asRows(Object? v) =>
+      ((_asMap(v)['rows'] as List?) ?? const []).map((e) => (e as Map).cast<String, dynamic>()).toList();
+
+  // ── the runtime-aware surface (the boundary the generated Dart client wraps) ──
+
+  /// Open the user/estate workspace: pull its ledger, boot the local holon under the installed law.
+  Future<void> connect({required String cloud, required String workspace, String? clientId, String? authToken, String? restoreFrom}) async {
+    await _call('connect', {'cloud': cloud, 'workspace': workspace, if (clientId != null) 'clientId': clientId, if (authToken != null) 'authToken': authToken, if (restoreFrom != null) 'restoreFrom': restoreFrom});
+  }
+
+  /// LOCAL-FIRST write: author `directiveId` under `domainHash`. Returns the new local head; durable on [sync].
+  Future<String> dispatch({required String domain, required String directiveId, required Map<String, Object?> payload, required String domainHash}) async {
+    final r = _asMap(await _call('dispatch', {'domain': domain, 'directiveId': directiveId, 'payload': payload, 'domainHash': domainHash}));
+    return r['head'].toString();
+  }
+
+  /// §5 cross-custody delivery: a `recordShare` carrying a pre-signed §3 quote into a home holon.
+  Future<String> deliverShare({required Map<String, Object?> quote, required String domainHash}) async {
+    final r = _asMap(await _call('deliverShare', {'quote': quote, 'domainHash': domainHash}));
+    return r['head'].toString();
+  }
+
+  /// A declared query's rows from the local projection.
+  Future<List<Map<String, dynamic>>> query(String queryId, [Map<String, Object?> params = const {}]) async =>
+      _asRows(await _call('query', {'queryId': queryId, 'params': params}));
+
+  /// A single aggregate by id (the by-id read).
+  Future<List<Map<String, dynamic>>> queryById(String id) async => _asRows(await _call('queryById', {'id': id}));
+
+  /// A maintained O(1) count / sum.
+  Future<int> count(String countId, [String group = '']) async => ((_asMap(await _call('count', {'countId': countId, 'group': group}))['count']) as num).toInt();
+  Future<int> sum(String sumId, [String group = '']) async => ((_asMap(await _call('sum', {'sumId': sumId, 'group': group}))['sum']) as num).toInt();
+
+  /// Push local writes → the session branch → cloud admission, and pull canonical main back.
+  Future<Map<String, Object?>> sync({bool admit = true}) async => _asMap(await _call('sync', {'admit': admit}));
+
+  /// Diagnostics — is the expected law installed/active/drift-free here? (The generated client surfaces it
+  /// so the app can answer "can I author this directive, and if not what deploy fixes it".)
+  Future<Map<String, Object?>> lawStatus(String hash) async => _asMap(await _call('lawStatus', {'hash': hash}));
+
+  /// Reactive local read: a stream of row-sets that re-emits on every local change. Cancelling the
+  /// subscription tells the runner to drop the watch.
+  Stream<List<dynamic>> watch(String queryId, [Map<String, Object?> params = const {}]) =>
+      _watchStream(kind: 'query', queryId: queryId, params: params);
+  Stream<List<dynamic>> watchById(String id) => _watchStream(kind: 'byId', id: id);
+
+  Stream<List<dynamic>> _watchStream({required String kind, String? queryId, Map<String, Object?>? params, String? id}) {
+    final subId = 'w${++_seq}';
+    late final StreamController<List<dynamic>> ctrl;
+    ctrl = StreamController<List<dynamic>>(
+      onListen: () => _call('watch', {'subId': subId, 'kind': kind, if (queryId != null) 'queryId': queryId, if (params != null) 'params': params, if (id != null) 'id': id}),
+      onCancel: () async {
+        _watches.remove(subId);
+        try { await _call('unwatch', {'subId': subId}); } catch (_) {}
+      },
+    );
+    _watches[subId] = ctrl;
+    return ctrl.stream;
+  }
+
+  /// Tear down: stop the transport subscription + fail any in-flight calls.
+  Future<void> dispose() async {
+    await _sub.cancel();
+    for (final c in _pending.values) {
+      if (!c.isCompleted) c.completeError(NomosBridgeError('bridge disposed'));
+    }
+    _pending.clear();
+    for (final w in _watches.values) {
+      if (!w.isClosed) await w.close();
+    }
+    _watches.clear();
+  }
+}

package/dart/test/webview_bridge_test.dart

@@ -0,0 +1,225 @@
+// NOMOS — the WEBVIEW BRIDGE protocol test (the Dart half of the app-binding boundary). A FAKE transport
+// stands in for the WebView runner (`webview-runner.mjs`): it auto-answers each request from a stub holon,
+// exactly as the real runner would, so the bridge's request/reply correlation, reactive `watch` streams, and
+// error framing are proven in pure Dart — no browser, no MemoryPersistence. The bridge and the JS runner are
+// the two ends of ONE protocol (`kWebviewBridgeVersion`).
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:nomos_dsl/nomos_dsl.dart';
+import 'package:test/test.dart';
+
+/// A fake runner-over-a-transport: records sent requests, replies the way `webview-runner.mjs` does, and can
+/// push reactive `watch` events. Lets us drive [NomosBridge] without a real WebView.
+class FakeRunner implements BridgeTransport {
+  final _incoming = StreamController<Map<String, Object?>>.broadcast();
+  final List<Map<String, Object?>> sent = [];
+  String? lastWatchSubId;
+
+  FakeRunner() {
+    // the runner announces readiness at construction.
+    scheduleMicrotask(() => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready'}));
+  }
+
+  @override
+  Stream<Map<String, Object?>> get messages => _incoming.stream;
+
+  @override
+  void send(Map<String, Object?> message) {
+    sent.add(message);
+    final id = message['id'] as int;
+    final op = message['op'] as String;
+    final args = (message['args'] as Map).cast<String, Object?>();
+    // reply exactly as the runner's ops do (the contract both ends share).
+    Map<String, Object?> reply(Object? result) => {'v': kWebviewBridgeVersion, 'id': id, 'ok': true, 'result': result};
+    scheduleMicrotask(() {
+      switch (op) {
+        case 'connect': _incoming.add(reply({'workspace': args['workspace']})); break;
+        case 'dispatch':
+          // a directive the law refuses answers ok:false (the runner frames the gate's verdict).
+          if (args['directiveId'] == 'refuseMe') {
+            _incoming.add({'v': kWebviewBridgeVersion, 'id': id, 'ok': false, 'error': 'the law refused this intent'});
+          } else {
+            _incoming.add(reply({'head': 'HEAD-${args['directiveId']}'}));
+          }
+          break;
+        case 'deliverShare': _incoming.add(reply({'head': 'HEAD-share'})); break;
+        case 'query': _incoming.add(reply({'rows': [{'id': 'a', 'data': {'q': args['queryId']}}]})); break;
+        case 'queryById': _incoming.add(reply({'rows': [{'id': args['id'], 'data': {'ok': true}}]})); break;
+        case 'count': _incoming.add(reply({'count': 7})); break;
+        case 'sync': _incoming.add(reply({'pushed': true})); break;
+        case 'lawStatus': _incoming.add(reply({'installed': true, 'drifted': false})); break;
+        case 'badop': _incoming.add({'v': kWebviewBridgeVersion, 'id': id, 'ok': false, 'error': 'the law refused this intent'}); break;
+        case 'watch': lastWatchSubId = args['subId'] as String; _incoming.add(reply({'subId': args['subId']})); break;
+        case 'unwatch': _incoming.add(reply({'subId': args['subId']})); break;
+        default: _incoming.add({'v': kWebviewBridgeVersion, 'id': id, 'ok': false, 'error': "unknown op '$op'"});
+      }
+    });
+  }
+
+  /// Simulate the holon firing a reactive change to an active watch.
+  void pushWatch(String subId, List<dynamic> rows) => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'watch', 'subId': subId, 'rows': rows});
+}
+
+/// A transport that answers EVERY request with one canned `result` (the golden corpus's reply) and records
+/// the request the bridge sent — so we can assert both halves of the wire contract from the Dart side.
+class ReplayTransport implements BridgeTransport {
+  final Map<String, Object?> result;
+  final _incoming = StreamController<Map<String, Object?>>.broadcast();
+  Map<String, Object?>? lastRequest;
+  ReplayTransport(this.result) {
+    scheduleMicrotask(() => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready'}));
+  }
+  @override
+  Stream<Map<String, Object?>> get messages => _incoming.stream;
+  @override
+  void send(Map<String, Object?> message) {
+    lastRequest = message;
+    final id = message['id'];
+    scheduleMicrotask(() => _incoming.add({'v': kWebviewBridgeVersion, 'id': id, 'ok': true, 'result': result}));
+  }
+}
+
+/// Load the shared golden corpus (the same file the JS runner test replays). Probed across the candidate
+/// working dirs `dart test` may run from, so it doesn't depend on one invocation cwd.
+Map<String, Object?> _loadCorpus() {
+  const candidates = [
+    '../../cloud/web-client/test/fixtures/bridge-protocol.golden.json', // cwd = dsl/dart (the usual)
+    'cloud/web-client/test/fixtures/bridge-protocol.golden.json', // cwd = repo root
+    '../../../cloud/web-client/test/fixtures/bridge-protocol.golden.json',
+  ];
+  for (final p in candidates) {
+    final f = File(p);
+    if (f.existsSync()) return (jsonDecode(f.readAsStringSync()) as Map).cast<String, Object?>();
+  }
+  fail('golden corpus not found from ${Directory.current.path}; tried $candidates');
+}
+
+/// Drive one corpus op through the typed bridge method and return its typed result (so we can compare it to
+/// what the corpus says the unwrapped value should be).
+Future<Object?> _invoke(NomosBridge b, String op, Map<String, Object?> a) async {
+  switch (op) {
+    case 'connect':
+      await b.connect(cloud: a['cloud'] as String, workspace: a['workspace'] as String, clientId: a['clientId'] as String?);
+      return null;
+    case 'dispatch':
+      return b.dispatch(domain: a['domain'] as String, directiveId: a['directiveId'] as String, payload: (a['payload'] as Map).cast<String, Object?>(), domainHash: a['domainHash'] as String);
+    case 'deliverShare':
+      return b.deliverShare(quote: (a['quote'] as Map).cast<String, Object?>(), domainHash: a['domainHash'] as String);
+    case 'query':
+      return b.query(a['queryId'] as String, (a['params'] as Map).cast<String, Object?>());
+    case 'queryById':
+      return b.queryById(a['id'] as String);
+    case 'count':
+      return b.count(a['countId'] as String, a['group'] as String);
+    case 'sum':
+      return b.sum(a['sumId'] as String, a['group'] as String);
+    case 'sync':
+      return b.sync(admit: a['admit'] as bool);
+    case 'lawStatus':
+      return b.lawStatus(a['hash'] as String);
+    default:
+      fail('corpus op not wired into the Dart bridge: $op');
+  }
+}
+
+/// What the corpus says the typed (unwrapped) return value should be, given the reply's `result`.
+Object? _expectedTyped(String op, Map<String, Object?> result) {
+  switch (op) {
+    case 'dispatch':
+    case 'deliverShare':
+      return result['head'];
+    case 'query':
+    case 'queryById':
+      return result['rows'];
+    case 'count':
+      return result['count'];
+    case 'sum':
+      return result['sum'];
+    case 'sync':
+    case 'lawStatus':
+      return result;
+    default:
+      return null; // connect: void
+  }
+}
+
+void main() {
+  // ── THE GOLDEN CORPUS — the cross-language conformance the JS runner replays too ──
+  // For each case: call the typed bridge method with the corpus `args`, then assert (1) the request the bridge
+  // SENT carries exactly those args, and (2) the typed value the bridge parsed from the corpus `result` matches.
+  // The JS runner asserts the SAME corpus from the other side — so neither end can drift the wire alone.
+  group('golden corpus (shared with the JS runner)', () {
+    final corpus = _loadCorpus();
+    final cases = (corpus['cases'] as List).cast<Map<String, Object?>>();
+    test('version pins the bridge version', () => expect(corpus['version'], kWebviewBridgeVersion));
+    for (final c in cases) {
+      final op = c['op'] as String;
+      final args = (c['args'] as Map).cast<String, Object?>();
+      final result = (c['result'] as Map).cast<String, Object?>();
+      test("'$op' request args + parsed result match the corpus", () async {
+        final transport = ReplayTransport(result);
+        final bridge = NomosBridge(transport);
+        await bridge.ready;
+        final typed = await _invoke(bridge, op, args);
+        expect((transport.lastRequest!['args'] as Map).cast<String, Object?>(), equals(args), reason: 'sent request args');
+        if (op != 'connect') expect(typed, equals(_expectedTyped(op, result)), reason: 'parsed typed result');
+        await bridge.dispose();
+      });
+    }
+  });
+
+  late FakeRunner runner;
+  late NomosBridge bridge;
+  setUp(() { runner = FakeRunner(); bridge = NomosBridge(runner); });
+  tearDown(() => bridge.dispose());
+
+  test('ready completes once the runner boots', () async {
+    await bridge.ready.timeout(const Duration(seconds: 1));
+  });
+
+  test('dispatch round-trips a typed head; args reach the runner verbatim', () async {
+    await bridge.ready;
+    final head = await bridge.dispatch(domain: 'guestbook', directiveId: 'signGuestbook', payload: {'author': 'ada'}, domainHash: 'abc');
+    expect(head, 'HEAD-signGuestbook');
+    final req = runner.sent.firstWhere((m) => m['op'] == 'dispatch');
+    expect((req['args'] as Map)['payload'], {'author': 'ada'});
+    expect((req['args'] as Map)['domainHash'], 'abc');
+  });
+
+  test('connect / deliverShare / query / 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.deliverShare(quote: {'publicKey': 'k'}, domainHash: 'h'), 'HEAD-share');
+    expect((await bridge.query('byAuthor', {'author': 'ada'})).first['data'], {'q': 'byAuthor'});
+    expect((await bridge.queryById('Entry_1')).first['id'], 'Entry_1');
+    expect(await bridge.count('entries'), 7);
+    expect(await bridge.sync(), {'pushed': true});
+    expect(await bridge.lawStatus('abc'), {'installed': true, 'drifted': false});
+  });
+
+  test('watch is a reactive stream; a runner push reaches the listener; cancel unwatches', () async {
+    await bridge.ready;
+    final got = <List<dynamic>>[];
+    final sub = bridge.watch('byAuthor', {'author': 'ada'}).listen(got.add);
+    await Future<void>.delayed(Duration.zero); // let the watch register
+    runner.pushWatch(runner.lastWatchSubId!, [{'id': 'a', 'data': {'n': 2}}]);
+    await Future<void>.delayed(Duration.zero);
+    expect(got, [[{'id': 'a', 'data': {'n': 2}}]]);
+    await sub.cancel();
+    expect(runner.sent.any((m) => m['op'] == 'unwatch'), isTrue);
+  });
+
+  test('a law refusal throws NomosBridgeError with the verbatim message', () async {
+    await bridge.ready;
+    Object? err;
+    try {
+      await bridge.dispatch(domain: 'x', directiveId: 'refuseMe', payload: {}, domainHash: 'h');
+    } on NomosBridgeError catch (e) {
+      err = e;
+    }
+    expect(err, isA<NomosBridgeError>());
+    expect((err as NomosBridgeError).message, contains('law refused'));
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
   "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",

package/src/codegen_dart.ts

@@ -1265,7 +1265,7 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
  * `SiteRootAggregate` → `Site`) and append `ReadModel` (`SiteReadModel`,
  * `BuildingReadModel`, `ThingReadModel`, `TrackableThingReadModel`). Pure + deterministic
  * — the same wire type always yields the same name. */
-function readModelClassName(aggregateType: string): string {
+export function readModelClassName(aggregateType: string): string {
   let stem = aggregateType;
   if (stem.endsWith("RootAggregate")) {
     stem = stem.slice(0, -"RootAggregate".length);

package/src/codegen_dart_client.ts

@@ -0,0 +1,219 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * ASYNC DART BRIDGE-CLIENT CODEGEN (#61) — the Flutter sibling of `codegen_ts.ts`.
+ *
+ * `codegen_dart.ts` emits the per-domain TYPES: read-model classes (`…ReadModel.fromProjected`),
+ * typed intent DTOs (`…Payload.toPayloadJson()`), typed ids, enums. Until this file a Flutter app
+ * still hand-typed directive ids + query ids against the raw `NomosBridge` (string + Map). This closes
+ * that: ONE generated `<name>.client.dart` per domain, emitted by `nomos-compile` AFTER the package is
+ * hashed (the deployed law's content hash baked in), carrying a `<Domain>Client` over a connected
+ * [NomosBridge] (the WebView runner) with:
+ *
+ *   * a typed DISPATCH method per directive — takes the generated `…Payload`, serialises via its
+ *     `toPayloadJson()`, auto-stamps omitted `…At` timestamps (the same caller-clock sugar the TS
+ *     client applies), returns the new local head;
+ *   * a typed declared-QUERY accessor per `query(...)` — one-shot `Future<List<…ReadModel>>` + a
+ *     reactive `watch…` `Stream<List<…ReadModel>>`, parsed off the bridge's `{type,id,data}` rows;
+ *   * by-id read/watch + a type-index `list…` per aggregate;
+ *   * typed O(1) count/sum accessors.
+ *
+ * It IMPORTS the sibling `<name>.dart` (for the read-model + payload classes) and the vendored
+ * `nomos_dsl.dart` barrel (for `NomosBridge`). NO manifest/hash impact — pure frontend codegen, exactly
+ * like `codegen_dart.ts`. NO FALLBACK: an unsupported shape throws at compile time.
+ */
+import type { z } from "zod";
+
+import type { AggregateHandle } from "./aggregate.js";
+import type { Field } from "./fields.js";
+import type { Directive } from "./directive.js";
+import type { QueryDecl } from "./query.js";
+import type { DomainModule } from "./codegen_dart.js";
+import { cap, readModelClassName } from "./codegen_dart.js";
+import { finishCount } from "./count.js";
+import { finishSum } from "./sum.js";
+import { autoStampFields } from "./codegen_ts.js";
+
+const camel = (s: string) => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
+const lcFirst = (s: string) => (s.length ? s[0]!.toLowerCase() + s.slice(1) : s);
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyDirective = Directive<any>;
+
+/** Dart reserved words that can't be method names — suffixed `_` if one slips through. */
+const DART_RESERVED = new Set([
+  "assert", "break", "case", "catch", "class", "const", "continue", "default", "do", "else", "enum",
+  "extends", "false", "final", "finally", "for", "if", "in", "is", "new", "null", "rethrow", "return",
+  "super", "switch", "this", "throw", "true", "try", "var", "void", "while", "with", "dynamic",
+]);
+const safeMethod = (s: string): string => (DART_RESERVED.has(s) ? `${s}_` : s);
+
+/** `guestbook` / `tool-library` / `Tool Library` → `GuestbookClient` / `ToolLibraryClient`. */
+export const dartClientClassName = (domain: string): string => `${cap(camel(domain))}Client`;
+/** `guestbook` → `guestbookDomainHash` — the Dart top-level const (lowerCamel by lint). */
+export const dartHashConstName = (fileBase: string): string => `${lcFirst(camel(fileBase))}DomainHash`;
+
+const dartStr = (s: string) => `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+
+/** The Dart param type for a query index key (int-kinded keys → `int`, else `String`). */
+function dartKeyType(agg: AggregateHandle | undefined, key: string): string {
+  const lead = key.includes(".") ? key.split(".")[0]! : key;
+  const f = agg?.fields[lead] as Field | undefined;
+  return f && (f.kind === "int" || f.kind === "counter") ? "int" : "String";
+}
+
+/** A Dart-safe param identifier from a (possibly dotted) index key: `a.b.c` → `aBC`. */
+function dartKeyParam(key: string): string {
+  const parts = key.split(".").filter((p) => p !== "");
+  const id = parts.length === 0 ? "key" : parts[0]! + parts.slice(1).map((p) => cap(p)).join("");
+  const cleaned = id.replace(/[^A-Za-z0-9_]/g, "_");
+  const safe = /^[0-9]/.test(cleaned) ? `v${cleaned}` : cleaned;
+  return safeMethod(safe);
+}
+
+/** Parse ONE bridge row (`{type,id,data}`) into a typed read model. Works for a `Map` (one-shot
+ * `query`/`queryById` rows) or a `dynamic` (`watch` stream rows) — indexing resolves on both. */
+function rowToModel(model: string, rowVar: string): string {
+  return `${model}.fromProjected((${rowVar}['data'] as Map).cast<String, dynamic>(), (${rowVar}['id'] ?? '').toString())`;
+}
+
+export interface DartBridgeClientOptions {
+  /** sha256 of the built `.package.usda` — the law this client dispatches under. */
+  readonly domainHash: string;
+}
+
+/** Generate the `<name>.client.dart` async bridge client for one domain module. */
+export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClientOptions): string {
+  const domain = mod.domain ?? mod.name;
+  const className = dartClientClassName(domain);
+  const hashConst = dartHashConstName(mod.name);
+  const aggById = new Map<string, AggregateHandle>();
+  for (const a of mod.aggregates) aggById.set(a.id, a);
+
+  const methods: string[] = [];
+
+  // ── directives → typed dispatch ──
+  const dirs = (mod.directives as AnyDirective[]).filter(
+    (d) => d && typeof d.id === "string" && typeof (d as { payloadSchema?: unknown }).payloadSchema === "object",
+  );
+  for (const d of dirs) {
+    const payloadClass = `${cap(d.id)}Payload`;
+    const stamps = autoStampFields((d as unknown as { payloadSchema: z.ZodTypeAny }).payloadSchema);
+    const method = safeMethod(d.id);
+    if (stamps.length > 0) {
+      methods.push(
+        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
+        `  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at dispatch.`,
+        `  Future<String> ${method}(${payloadClass} payload) {`,
+        `    final data = payload.toPayloadJson();`,
+        `    final now = DateTime.now().toUtc().toIso8601String();`,
+        ...stamps.map((s) => `    data.putIfAbsent(${dartStr(s)}, () => now);`),
+        `    return bridge.dispatch(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, domainHash: domainHash);`,
+        `  }`,
+        ``,
+      );
+    } else {
+      methods.push(
+        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
+        `  Future<String> ${method}(${payloadClass} payload) =>`,
+        `      bridge.dispatch(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.toPayloadJson(), domainHash: domainHash);`,
+        ``,
+      );
+    }
+  }
+
+  // ── declared queries → one-shot + reactive ──
+  for (const q of (mod.queries ?? []) as QueryDecl[]) {
+    const model = readModelClassName(q.returns);
+    const agg = aggById.get(q.returns);
+    const params = q.key.map((k) => `required ${dartKeyType(agg, k)} ${dartKeyParam(k)}`).join(", ");
+    const argMap = `{${q.key.map((k) => `${dartStr(k)}: ${dartKeyParam(k)}`).join(", ")}}`;
+    const m = safeMethod(lcFirst(camel(q.id)));
+    methods.push(
+      `  /// Declared query \`${q.id}\` (indexed probe — routed by the read manifest).`,
+      `  Future<List<${model}>> ${m}({${params}}) async =>`,
+      `      (await bridge.query(${dartStr(q.id)}, ${argMap})).map((r) => ${rowToModel(model, "r")}).toList();`,
+      ``,
+      `  /// Reactive \`${q.id}\` — re-emits on every local change (cancel the subscription to stop).`,
+      `  Stream<List<${model}>> watch${cap(camel(q.id))}({${params}}) =>`,
+      `      bridge.watch(${dartStr(q.id)}, ${argMap}).map((rows) => rows.map((r) => ${rowToModel(model, "r")}).toList());`,
+      ``,
+    );
+  }
+
+  // ── counts / sums → O(1) typed reads ──
+  for (const c of (mod.counts ?? []).map((raw) => finishCount(raw))) {
+    const m = safeMethod(lcFirst(camel(c.id)));
+    methods.push(
+      c.by != null
+        ? `  /// Declared count \`${c.id}\` — the maintained O(1) tally per \`${c.by}\`.\n  Future<int> ${m}(String ${dartKeyParam(c.by)}) => bridge.count(${dartStr(c.id)}, ${dartKeyParam(c.by)});`
+        : `  /// Declared count \`${c.id}\` — the maintained O(1) grand total.\n  Future<int> ${m}() => bridge.count(${dartStr(c.id)});`,
+      ``,
+    );
+  }
+  for (const s of (mod.sums ?? []).map((raw) => finishSum(raw))) {
+    const m = safeMethod(lcFirst(camel(s.id)));
+    methods.push(
+      s.by != null
+        ? `  /// Declared sum \`${s.id}\` — the maintained O(1) total per \`${s.by}\`.\n  Future<int> ${m}(String ${dartKeyParam(s.by)}) => bridge.sum(${dartStr(s.id)}, ${dartKeyParam(s.by)});`
+        : `  /// Declared sum \`${s.id}\` — the maintained O(1) grand total.\n  Future<int> ${m}() => bridge.sum(${dartStr(s.id)});`,
+      ``,
+    );
+  }
+
+  // ── per-aggregate by-id read/watch + type-index list ──
+  for (const agg of mod.aggregates) {
+    const model = readModelClassName(agg.id);
+    const lc = lcFirst(camel(agg.id));
+    const Cap = cap(camel(agg.id));
+    methods.push(
+      `  /// Read one ${agg.id} by aggregate id.`,
+      `  Future<List<${model}>> ${safeMethod(`${lc}ById`)}(String id) async =>`,
+      `      (await bridge.queryById(id)).map((r) => ${rowToModel(model, "r")}).toList();`,
+      ``,
+      `  /// Watch one ${agg.id} by aggregate id (local reactive read).`,
+      `  Stream<List<${model}>> watch${Cap}ById(String id) =>`,
+      `      bridge.watchById(id).map((rows) => rows.map((r) => ${rowToModel(model, "r")}).toList());`,
+      ``,
+      `  /// Every ${agg.id} (the type-index probe — O(result), not a scan).`,
+      `  Future<List<${model}>> ${safeMethod(`list${Cap}s`)}() async =>`,
+      `      (await bridge.query('aggregatesByType', {'__type': ${dartStr(agg.id)}})).map((r) => ${rowToModel(model, "r")}).toList();`,
+      ``,
+    );
+  }
+
+  return [
+    `// AUTO-GENERATED by nomos-compile — typed ASYNC Dart client for domain "${domain}".`,
+    `// Drives the REAL githolon over a NomosBridge (the WebView runner). Regenerated every compile; do`,
+    `// not edit. Construct with a connected bridge:`,
+    `//`,
+    `//   final bridge = NomosBridge(transport);   // transport = your WebViewTransport`,
+    `//   await bridge.ready;`,
+    `//   await bridge.connect(cloud: cloud, workspace: ws, clientId: deviceId);`,
+    `//   final app = ${className}(bridge);`,
+    `//   await app.${dirs[0] ? safeMethod(dirs[0].id) : "someDirective"}(/* typed payload */);`,
+    ``,
+    `import 'nomos_dsl.dart';`,
+    `import '${mod.name}.dart';`,
+    `// Re-export the sibling types (read models + payloads + the bridge runtime) so ONE import of this`,
+    `// client file gives an app the whole typed surface.`,
+    `export '${mod.name}.dart';`,
+    `export 'nomos_dsl.dart' show NomosBridge, BridgeTransport, NomosBridgeError, kWebviewBridgeVersion;`,
+    ``,
+    `/// sha256 of the deployed \`.package.usda\` — the installed law this client dispatches under.`,
+    `const String ${hashConst} = ${dartStr(opts.domainHash)};`,
+    ``,
+    `/// Typed async client for the \`${domain}\` domain, bound to a connected [NomosBridge].`,
+    `class ${className} {`,
+    `  final NomosBridge bridge;`,
+    `  final String domainHash;`,
+    `  ${className}(this.bridge, {this.domainHash = ${hashConst}});`,
+    ``,
+    ...methods,
+    `}`,
+    ``,
+  ].join("\n");
+}

package/src/compile_package_main.ts

@@ -63,6 +63,7 @@ import {
   type DomainModule,
   type PermissionVocabulary,
 } from "./codegen_dart.js";
+import { generateDartBridgeClient } from "./codegen_dart_client.js";
 import type { AnyCount } from "./count.js";
 import type { QueryDecl } from "./query.js";
 import type { SpatialDecl } from "./spatial.js";
@@ -408,6 +409,9 @@ const DART_SUPPORT_SRC = [
   "dispatch.dart",
   "subscriptions.dart",
   "provider.dart",
+  // The async WebView bridge runtime (NomosBridge / BridgeTransport) the generated
+  // `<name>.client.dart` drives — the barrel re-exports it, so it must be vendored too.
+  "webview_bridge.dart",
 ] as const;
 
 /**
@@ -416,7 +420,7 @@ const DART_SUPPORT_SRC = [
  * `emit_dart.ts` drives) + the vendored `nomos_dsl.dart` barrel and its `src/`
  * support files, with the generated files' `package:` import rewritten relative.
  */
-function emitDart(modules: readonly DomainModule[], dartOut: string): string[] {
+function emitDart(modules: readonly DomainModule[], dartOut: string, domainHash: string): string[] {
   mkdirSync(path.join(dartOut, "src"), { recursive: true });
 
   // 1. the vendored framework support (barrel + src/), copied byte-for-byte except
@@ -431,10 +435,18 @@ function emitDart(modules: readonly DomainModule[], dartOut: string): string[] {
     copyFileSync(path.join(libDir, "src", f), path.join(dartOut, "src", f));
   }
 
-  // 2. one generated file per composed domain.
+  // 2. one generated file per composed domain — the TYPES (`<name>.dart`) + the async bridge
+  //    CLIENT (`<name>.client.dart`, the Flutter sibling of `<name>.client.ts`).
   const written: string[] = [];
   for (const mod of modules) {
-    const src = generateDartDomain(mod);
+    // Default the read-model allowlist to EVERY aggregate when the domain didn't pin one, so
+    // `<name>.dart` carries a read model per aggregate — the bridge client imports them. A domain
+    // that pins `readModelAggregates` keeps its choice (byte-identical to before this default).
+    const modForDart: DomainModule =
+      mod.readModelAggregates === undefined
+        ? { ...mod, readModelAggregates: mod.aggregates.map((a) => a.id) }
+        : mod;
+    const src = generateDartDomain(modForDart);
     if (!src.includes(DART_PACKAGE_IMPORT)) {
       fail(
         `generated Dart for domain '${mod.name}' does not carry the expected support import (${DART_PACKAGE_IMPORT}) — codegen_dart header drifted; fix the rewrite in compile_package_main.ts`,
@@ -443,6 +455,11 @@ function emitDart(modules: readonly DomainModule[], dartOut: string): string[] {
     const p = path.join(dartOut, `${mod.name}.dart`);
     writeFileSync(p, src.replace(DART_PACKAGE_IMPORT, DART_RELATIVE_IMPORT), "utf8");
     written.push(p);
+
+    const clientSrc = generateDartBridgeClient(modForDart, { domainHash });
+    const cp = path.join(dartOut, `${mod.name}.client.dart`);
+    writeFileSync(cp, clientSrc, "utf8");
+    written.push(cp);
   }
   return written;
 }
@@ -1351,7 +1368,7 @@ async function main(): Promise<void> {
       cfgDir,
       typeof dartCfg === "object" && dartCfg.out !== undefined ? dartCfg.out : path.join(outDir, "dart"),
     );
-    dartFiles = emitDart(domainModules, dartOut);
+    dartFiles = emitDart(domainModules, dartOut, domainHash);
   }
 
   // ── summary ──