@githolon/dsl 0.12.0 → 0.14.0

package/dart/lib/src/webview_bridge.dart

@@ -41,6 +41,16 @@ class NomosBridge {
   final BridgeTransport _transport;
   final Map<int, Completer<Object?>> _pending = {};
   final Map<String, StreamController<List<dynamic>>> _watches = {};
+  final StreamController<Map<String, Object?>> _syncEvents =
+      StreamController<Map<String, Object?>>.broadcast();
+  final StreamController<Map<String, Object?>> _signalEvents =
+      StreamController<Map<String, Object?>>.broadcast();
+  final StreamController<Map<String, Object?>> _flameEvents =
+      StreamController<Map<String, Object?>>.broadcast();
+  final StreamController<Map<String, Object?>> _spanEvents =
+      StreamController<Map<String, Object?>>.broadcast();
+  final List<Map<String, Object?>> _spanBuffer =
+      []; // recent span events — so BOOT spans (emitted during connect, before the UI subscribes) survive
   final Completer<void> _ready = Completer<void>();
   int _seq = 0;
   late final StreamSubscription<Map<String, Object?>> _sub;
@@ -53,7 +63,8 @@ class NomosBridge {
   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)
+    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();
@@ -61,7 +72,37 @@ class NomosBridge {
     }
     if (event == 'watch') {
       final ctrl = _watches[m['subId']];
-      if (ctrl != null && !ctrl.isClosed) ctrl.add((m['rows'] as List?) ?? const []);
+      if (ctrl != null && !ctrl.isClosed) {
+        if (m['ok'] == false) {
+          ctrl.addError(NomosBridgeError(
+              (m['error'] ?? 'the watch read failed').toString()));
+        } else {
+          ctrl.add((m['rows'] as List?) ?? const []);
+        }
+      }
+      return;
+    }
+    if (event == 'sync' || event == 'link') {
+      // autoSync telemetry: each round { event:'sync', reason, result } and socket state { event:'link', status }.
+      if (!_syncEvents.isClosed) _syncEvents.add(m);
+      return;
+    }
+    if (event == 'trace') {
+      // the realtime cloud flamepath: { event:'trace', trace:{at, oid, edge, clients} } — one per admission.
+      if (!_flameEvents.isClosed) _flameEvents.add(m);
+      return;
+    }
+    if (event == 'signal') {
+      // signal holon projection: ephemeral coordination such as peer frontiers / lag.
+      if (!_signalEvents.isClosed) _signalEvents.add(m);
+      return;
+    }
+    if (event == 'span') {
+      // LIVE per-layer span: { event:'span', span:{ phase:'begin'|'end', id, track, name, kind, t0|t1 } }.
+      _spanBuffer.add(m);
+      if (_spanBuffer.length > 400)
+        _spanBuffer.removeRange(0, _spanBuffer.length - 400);
+      if (!_spanEvents.isClosed) _spanEvents.add(m);
       return;
     }
     final id = m['id'];
@@ -71,7 +112,8 @@ class NomosBridge {
     if (m['ok'] == true) {
       completer.complete(m['result']);
     } else {
-      completer.completeError(NomosBridgeError((m['error'] ?? 'the githolon refused the request').toString()));
+      completer.completeError(NomosBridgeError(
+          (m['error'] ?? 'the githolon refused the request').toString()));
     }
   }
 
@@ -81,65 +123,164 @@ class NomosBridge {
     final id = ++_seq;
     final completer = Completer<Object?>();
     _pending[id] = completer;
-    _transport.send({'v': kWebviewBridgeVersion, 'id': id, 'op': op, 'args': args});
+    _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 {};
+  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();
+      ((_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});
+  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}));
+  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}));
+  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 =>
+  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}));
+  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();
+  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}));
+  Future<Map<String, Object?>> sync({bool admit = true}) async =>
+      _asMap(await _call('sync', {'admit': admit}));
+
+  /// PERSIST: a base64 snapshot of the whole local holon (the bare nomos.git incl. un-synced writes + the
+  /// DLQ). Store it on disk and pass it back as `connect(restoreFrom:)` next launch — the app then boots from
+  /// LOCAL CUSTODY (no network clone), instant at any chain length. Returns the snapshot string.
+  Future<String> export() async =>
+      (_asMap(await _call('export'))['snapshot'] ?? '').toString();
+
+  /// The local ledger tip (an O(1) ref read). Cheap change signal — persistence skips re-exporting an
+  /// unchanged snapshot when [head] matches the last saved tip.
+  Future<String> head() async =>
+      (_asMap(await _call('head'))['head'] ?? '').toString();
+
+  /// AUTO-SYNC — event-driven background sync. The edge DOORBELL converges peers' writes in real time and a
+  /// local write flushes the up leg at once; `fallbackMs` is only a just-in-case safety pull (default 60s).
+  /// Each round arrives on [syncEvents] as `{ event:'sync', reason, result }`; socket state as `{event:'link'}`.
+  /// Call once after [connect] — then the app never polls.
+  Future<void> autoSync(
+          {int? debounceMs, int? fallbackMs, String? signalId}) async =>
+      await _call('autoSync', {
+        if (debounceMs != null) 'debounceMs': debounceMs,
+        if (fallbackMs != null) 'fallbackMs': fallbackMs,
+        if (signalId != null) 'signalId': signalId
+      });
+  Future<void> stopAutoSync() async {
+    await _call('stopAutoSync');
+  }
+
+  /// Background-sync telemetry: each autoSync round (`event:'sync'`) and doorbell socket state (`event:'link'`).
+  Stream<Map<String, Object?>> get syncEvents => _syncEvents.stream;
+
+  /// Ephemeral signal-holon projections (`event:'signal'`), currently peer frontiers / lag for the workspace.
+  Stream<Map<String, Object?>> get signalEvents => _signalEvents.stream;
+
+  /// THE REALTIME FLAMEPATH: one event per admission the edge broadcasts over the doorbell —
+  /// `{ at, oid, edge:{totalMs,scanMs,fetchMs,gateFoldMs,sealMs,intents}, clients:[{client,n}] }`.
+  /// Every subscriber sees EVERY admission (yours and your peers') — the cloud track of the flame chart.
+  Stream<Map<String, Object?>> get flameEvents => _flameEvents.stream;
+
+  /// LIVE per-layer spans of the local pipeline (begin/end as they happen): mutex wait, githolon author,
+  /// push, converge … The host renders in-progress bars so a hang is visible WHILE it blocks, not after.
+  Stream<Map<String, Object?>> get spanEvents => _spanEvents.stream;
+
+  /// The buffered recent span events — replay these on first build to recover the BOOT flamepath
+  /// (fetch wasm / clone ledger / instantiate) that streamed during connect(), before the UI subscribed.
+  List<Map<String, Object?>> get recentSpans => List.unmodifiable(_spanBuffer);
+
+  /// Ledger size (commits) + branch-vs-main (ahead) + projection bytes — the dashboard's slow state.
+  Future<Map<String, Object?>> metrics() async =>
+      _asMap(await _call('metrics'));
 
   /// 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}));
+  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 {}]) =>
+  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>> watchById(String id) =>
+      _watchStream(kind: 'byId', id: id);
 
-  Stream<List<dynamic>> _watchStream({required String kind, String? queryId, Map<String, Object?>? params, String? 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}),
+      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 (_) {}
+        try {
+          await _call('unwatch', {'subId': subId});
+        } catch (_) {}
       },
     );
     _watches[subId] = ctrl;
@@ -157,5 +298,9 @@ class NomosBridge {
       if (!w.isClosed) await w.close();
     }
     _watches.clear();
+    if (!_syncEvents.isClosed) await _syncEvents.close();
+    if (!_signalEvents.isClosed) await _signalEvents.close();
+    if (!_flameEvents.isClosed) await _flameEvents.close();
+    if (!_spanEvents.isClosed) await _spanEvents.close();
   }
 }

package/dart/test/webview_bridge_test.dart

@@ -19,7 +19,8 @@ class FakeRunner implements BridgeTransport {
 
   FakeRunner() {
     // the runner announces readiness at construction.
-    scheduleMicrotask(() => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready'}));
+    scheduleMicrotask(
+        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready'}));
   }
 
   @override
@@ -32,34 +33,98 @@ class FakeRunner implements BridgeTransport {
     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};
+    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 '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'});
+            _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'"});
+        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 'autoSync':
+          _incoming.add(reply({'started': 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});
+  void pushWatch(String subId, List<dynamic> rows) => _incoming.add({
+        'v': kWebviewBridgeVersion,
+        'event': 'watch',
+        'subId': subId,
+        'rows': rows
+      });
+
+  /// Simulate the runner forwarding a signal holon projection.
+  void pushSignal(Map<String, Object?> signal) => _incoming
+      .add({'v': kWebviewBridgeVersion, 'event': 'signal', 'signal': signal});
 }
 
 /// A transport that answers EVERY request with one canned `result` (the golden corpus's reply) and records
@@ -69,7 +134,8 @@ class ReplayTransport implements BridgeTransport {
   final _incoming = StreamController<Map<String, Object?>>.broadcast();
   Map<String, Object?>? lastRequest;
   ReplayTransport(this.result) {
-    scheduleMicrotask(() => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready'}));
+    scheduleMicrotask(
+        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready'}));
   }
   @override
   Stream<Map<String, Object?>> get messages => _incoming.stream;
@@ -77,7 +143,8 @@ class ReplayTransport implements BridgeTransport {
   void send(Map<String, Object?> message) {
     lastRequest = message;
     final id = message['id'];
-    scheduleMicrotask(() => _incoming.add({'v': kWebviewBridgeVersion, 'id': id, 'ok': true, 'result': result}));
+    scheduleMicrotask(() => _incoming.add(
+        {'v': kWebviewBridgeVersion, 'id': id, 'ok': true, 'result': result}));
   }
 }
 
@@ -91,24 +158,37 @@ Map<String, Object?> _loadCorpus() {
   ];
   for (final p in candidates) {
     final f = File(p);
-    if (f.existsSync()) return (jsonDecode(f.readAsStringSync()) as Map).cast<String, Object?>();
+    if (f.existsSync())
+      return (jsonDecode(f.readAsStringSync()) as Map).cast<String, Object?>();
   }
-  fail('golden corpus not found from ${Directory.current.path}; tried $candidates');
+  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 {
+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?);
+      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);
+      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);
+      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?>());
+      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':
@@ -153,7 +233,8 @@ void main() {
   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));
+    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?>();
@@ -163,8 +244,12 @@ void main() {
         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');
+        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();
       });
     }
@@ -172,50 +257,107 @@ void main() {
 
   late FakeRunner runner;
   late NomosBridge bridge;
-  setUp(() { runner = FakeRunner(); bridge = NomosBridge(runner); });
+  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 {
+  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');
+    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 {
+  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.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});
+    expect(
+        await bridge.lawStatus('abc'), {'installed': true, 'drifted': false});
   });
 
-  test('watch is a reactive stream; a runner push reaches the listener; cancel unwatches', () async {
+  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}}]);
+    runner.pushWatch(runner.lastWatchSubId!, [
+      {
+        'id': 'a',
+        'data': {'n': 2}
+      }
+    ]);
     await Future<void>.delayed(Duration.zero);
-    expect(got, [[{'id': 'a', 'data': {'n': 2}}]]);
+    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 {
+  test('signal events are forwarded on their own stream', () async {
+    await bridge.ready;
+    final got = <Map<String, Object?>>[];
+    final sub = bridge.signalEvents.listen(got.add);
+    runner.pushSignal({
+      'type': 'signal.projection',
+      'domain': 'presence',
+      'projection': {
+        'peers': [
+          {'clientId': 'prof-a', 'behindBest': 141},
+        ],
+      },
+    });
+    await Future<void>.delayed(Duration.zero);
+    expect(got.single['signal'], isA<Map>());
+    expect(((got.single['signal'] as Map)['projection'] as Map)['peers'],
+        isA<List>());
+    await sub.cancel();
+  });
+
+  test('autoSync forwards a scoped signal id', () async {
+    await bridge.ready;
+    await bridge.autoSync(signalId: 'signal:ws:list:main');
+    final req = runner.sent.firstWhere((m) => m['op'] == 'autoSync');
+    expect((req['args'] as Map)['signalId'], 'signal:ws:list:main');
+  });
+
+  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');
+      await bridge.dispatch(
+          domain: 'x', directiveId: 'refuseMe', payload: {}, domainHash: 'h');
     } on NomosBridgeError catch (e) {
       err = e;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.12.0",
+  "version": "0.14.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/framework/workspaces.ts

@@ -641,6 +641,11 @@ export const AuthProvider = aggregate("AuthProvider", {
   issuer: t.string().merge(Lww),
   /** The provider's public JWKS endpoint (asymmetric verification keys). */
   jwksUrl: t.string().merge(Lww),
+  /** OPTIONAL expected `aud` claim. When the platform sets it, a token's `aud` MUST carry this value
+   *  (defense-in-depth beyond the issuer match — e.g. a Firebase project id, an Auth0 API audience).
+   *  Absent ⇒ issuer match alone. This is LAW-STATE the PLATFORM owns; the host merely enforces it as a
+   *  capability (it never chooses the audience). */
+  audience: t.string().merge(Lww),
   /** Human label for audit ("acme supabase", ...). */
   label: t.string().merge(Lww),
   /** Who set it (attribution). */
@@ -661,6 +666,7 @@ export const setAuthProvider = directive("setAuthProvider")
       // deterministic engine does not provide — a regex keeps the plan pure.
       issuer: z.string().regex(/^https?:\/\/\S+$/, "expected an http(s) URL"),
       jwksUrl: z.string().regex(/^https?:\/\/\S+$/, "expected an http(s) URL"),
+      audience: z.string().min(1).optional(),
       label: z.string().min(1),
       setBy: z.string().min(1),
       setAt: epochMs,
@@ -672,6 +678,7 @@ export const setAuthProvider = directive("setAuthProvider")
       withMarker(set(ap, "scope", "platform"), "ensures"),
       set(ap, "issuer", p.issuer),
       set(ap, "jwksUrl", p.jwksUrl),
+      ...(p.audience ? [set(ap, "audience", p.audience)] : []),
       set(ap, "label", p.label),
       set(ap, "setBy", p.setBy),
       set(ap, "setAt", p.setAt),