@githolon/dsl 0.13.0 → 0.15.0

package/dart/example/nomos_webview_transport.dart

@@ -15,8 +15,8 @@
 //   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 app = GuestbookClient(bridge);
+//   final head = await app.signGuestbook(SignGuestbookPayload(author: 'ada', message: 'hi', mood: 'delighted'));
 //   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:`.)

package/dart/lib/nomos_dsl.dart

@@ -10,7 +10,7 @@
 ///  - The hand-written kernel WIRE types (`Value`, `Field`/`WireField`, `Hlc`,
 ///    `Op`, `FieldOp`, `Event`, `Schema`/`WireDriver`) — byte-compatible with
 ///    serde_json. See `src/wire.dart`, `src/driver.dart`.
-///  - The ONE write verb `dispatch(intent)` (`src/dispatch.dart`) + the typed
+///  - The ONE effectful write verb `offer(intent)` (`src/offer.dart`) + the typed
 ///    reactive read engine `NomosReads` (`src/subscriptions.dart`).
 ///  - The framework PRIMITIVES ONLY. The CODE-GENERATED per-domain types
 ///    (aggregates + public intent payloads + enums + `watch…` read accessors) NO LONGER
@@ -18,14 +18,14 @@
 ///    `co2_nomos_domains` (`ts_packages/co2-nomos-domains/dart/`), emitted there by
 ///    `ts_packages/co2-nomos-domains/src/emit_dart.ts`. Tenant domains squatting in
 ///    the framework package was the wrong topology; this barrel now exports ONLY the
-///    hand-written framework wire/dispatch/read/provider primitives. App code that
+///    hand-written framework wire/offer/read/provider primitives. App code that
 ///    wants the typed domain surface imports `package:co2_nomos_domains/co2_nomos_domains.dart`,
 ///    which re-exports this framework barrel PLUS every generated domain.
 library;
 
 export 'src/wire.dart';
 export 'src/driver.dart';
-export 'src/dispatch.dart';
+export 'src/offer.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
@@ -33,7 +33,7 @@ export 'src/schema_validation.dart';
 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.
+// of `offer.dart`; the generated per-task provider classes build on it.
 export 'src/provider.dart';
 
 // ── NO generated domains here ──────────────────────────────────────────────

package/dart/lib/src/{dispatch.dart → offer.dart}

@@ -5,19 +5,19 @@
 // wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
 // If a file isn't this / hosting this / authoring for this / proving this — it's gone.
 
-/// The ONE write verb: `dispatch(intent)`.
+/// The ONE effectful write verb: `offer(intent)`.
 ///
-/// END-STATE (the "dispatch(intent) purge", Jack 2026-06-01): app code's only
-/// write verb is `dispatch(intent)`. The frontend constructs ONLY a typed
+/// END-STATE (the "offer(intent) purge", Jack 2026-06-18): app code's only
+/// effectful write verb is `offer(intent)`. The frontend constructs ONLY a typed
 /// generated intent DTO (a [NomosIntent]) — it never hand-types an engine rule
-/// id, never builds an `Event`, never holds an `Hlc`. `dispatch` ships the
+/// id, never builds an `Event`, never holds an `Hlc`. `offer` ships the
 /// intent payload as DATA to the kernel's FRB `author(domain, directiveId, payloadJson,
 /// actor)`; the sealed engine runs the REAL `.plan()` and is the SOLE lowering
 /// authority (HLC + intent id are kernel-allocated host-side).
 ///
 /// This file is HAND-WRITTEN and domain-AGNOSTIC (declared ONCE, here): the
 /// generated per-domain intent classes `implements NomosIntent`, so a single
-/// generic `dispatch` covers every public intent of every domain — replacing the
+/// generic `offer` covers every public intent of every domain — replacing the
 /// ~63-method write façade.
 library;
 
@@ -39,7 +39,7 @@ abstract interface class NomosIntent {
 }
 
 /// The kernel write seam: the FRB `NomosClient.author` signature, as a function
-/// type. `dispatch` takes this (rather than importing the FRB client) so the
+/// type. `offer` takes this (rather than importing the FRB client) so the
 /// generated `nomos_dsl` package stays free of a `flutter_rust_bridge` dependency
 /// — the app threads `client.author` in. Returns the new HEAD commit oid (hex).
 typedef Authorer = String Function({
@@ -54,7 +54,7 @@ typedef Authorer = String Function({
 /// intent object — nothing is hand-typed. Builds NO `Event` and NO `Hlc`: the
 /// engine lowers. [actor] is the authenticated actor the caller threads from auth.
 /// Returns the new HEAD commit oid (hex).
-String dispatch(NomosIntent intent,
+String offer(NomosIntent intent,
         {required Authorer author, required String actor}) =>
     author(
       domain: intent.domain,

package/dart/lib/src/provider.dart

@@ -7,22 +7,22 @@
 
 /// The PROVIDER boundary: the typed server-side capability-provider SDK runtime.
 ///
-/// This is the SYMMETRIC TWIN of `dispatch.dart` (the peer write boundary). Where
-/// the peer authors an Order (`createTranscribeVoiceNote(...)` -> `dispatch`), a
+/// This is the SYMMETRIC TWIN of `offer.dart` (the peer write boundary). Where
+/// the peer authors an Obligation (`createTranscribeVoiceNote(...)` -> `offer`), a
 /// PROVIDER (Whisper, a renderer, a multi-target PR transporter) is the
-/// other end of the framework `impureCapability` Order→Receipt pair: it WATCHES `requested`
+/// other end of the framework `impureCapability` Obligation→Receipt pair: it WATCHES `requested`
 /// task rows, performs the impure side-effect OUTSIDE the fold, and authors the RECEIPT
 /// (`complete…`/`fail…`/`block…`/`deadLetter…`) back through the SAME write path. The receipt is an ordinary
 /// intent — the provider is a Nomos author, NOT a bypass (ONE-WRITE-PATH).
-/// Order and Receipt are intent roles, not provider-owned jobs or privileged server
+/// Obligation and Receipt are intent roles, not provider-owned jobs or privileged server
 /// mutation channels.
 ///
 /// PRINCIPLE (Jack 2026-06-04): code is ~free; INTEGRATION POINTS are expensive +
 /// fuckup-guaranteed. So the generated provider SDK is fully TYPED to the boundary —
-/// the dev writes a typed `handler(Order) -> Result | Failure | Blocked | DeadLetter`; the generated
-/// dispatcher DECODES the incoming Order JSON into the typed Order and ENCODES the typed
+/// the dev writes a typed `handler(Obligation) -> Result | Failure | Blocked | DeadLetter`; the generated
+/// dispatcher DECODES the incoming Obligation JSON into the typed Obligation and ENCODES the typed
 /// outcome into the ordinary Receipt intent. NO dynamic / `Map<String, dynamic>` / raw-JSON leaks
-/// into the dev-facing API; the types stop ONLY at the actual JSON serde (`handleOrder`).
+/// into the dev-facing API; the types stop ONLY at the actual JSON serde (`handleObligation`).
 ///
 /// This file is HAND-WRITTEN and domain-AGNOSTIC (declared ONCE, here): the generated
 /// per-task provider classes build on these interfaces, so the round-trip mechanism is
@@ -31,9 +31,9 @@ library;
 
 import 'dart:convert';
 
-import 'dispatch.dart' show NomosIntent;
+import 'offer.dart' show NomosIntent;
 
-/// The typed OUTCOME a provider handler returns for one Order: success, failure, blocked,
+/// The typed OUTCOME a provider handler returns for one Obligation: success, failure, blocked,
 /// or dead-lettered.
 /// SEALED so a generated dispatcher's `switch` is EXHAUSTIVE — a new outcome variant is
 /// a compile error at every dispatcher, never a silent fall-through. The mirror of the
@@ -44,7 +44,7 @@ sealed class TaskOutcome<R> {
 
 /// The SUCCESS outcome: the typed [result] the handler produced. The generated
 /// dispatcher maps this → the `complete…` Receipt directive (status:completed +
-/// resultRef + closesOrder).
+/// resultRef + closesObligation).
 final class TaskSuccess<R> extends TaskOutcome<R> {
   /// The typed result the handler produced (e.g. a transcription's `resultRef`).
   final R result;
@@ -53,7 +53,7 @@ final class TaskSuccess<R> extends TaskOutcome<R> {
 
 /// The FAILURE outcome: the [failureReason] the handler recorded. The generated
 /// dispatcher maps this → the `fail…` Receipt directive (status:failed + failureReason +
-/// closesOrder). A recorded failure is the terminal state — NOT a retry storm
+/// closesObligation). A recorded failure is the terminal state — NOT a retry storm
 /// (conformance X1's "declined is recorded" discipline at the task scale).
 final class TaskFailure<R> extends TaskOutcome<R> {
   /// Why the side-effect failed (recorded onto the task, never re-thrown into the fold).
@@ -63,13 +63,13 @@ final class TaskFailure<R> extends TaskOutcome<R> {
 
 /// The BLOCKED outcome: the provider cannot proceed until an external condition changes.
 /// The generated dispatcher maps this -> the `block...` Receipt directive
-/// (status:blocked + blockedReason + nextAction + closesOrder). This is terminal for this
-/// order; recovery is a fresh explicit Order after the next action is satisfied.
+/// (status:blocked + blockedReason + nextAction + closesObligation). This is terminal for this
+/// obligation; recovery is a fresh explicit Obligation after the next action is satisfied.
 final class TaskBlocked<R> extends TaskOutcome<R> {
   /// Why the provider cannot proceed.
   final String blockedReason;
 
-  /// What the host/human must do before a fresh order can proceed.
+  /// What the host/human must do before a fresh obligation can proceed.
   final String nextAction;
 
   const TaskBlocked({
@@ -78,11 +78,11 @@ final class TaskBlocked<R> extends TaskOutcome<R> {
   });
 }
 
-/// The DEAD-LETTER outcome: stop retrying this order and park it in the DLQ. The generated
+/// The DEAD-LETTER outcome: stop retrying this obligation and park it in the DLQ. The generated
 /// dispatcher maps this -> the `deadLetter...` Receipt directive
-/// (status:deadLettered + deadLetterReason + closesOrder).
+/// (status:deadLettered + deadLetterReason + closesObligation).
 final class TaskDeadLetter<R> extends TaskOutcome<R> {
-  /// Why this order was moved to the DLQ.
+  /// Why this obligation was moved to the DLQ.
   final String deadLetterReason;
   const TaskDeadLetter(this.deadLetterReason);
 }
@@ -106,34 +106,34 @@ abstract interface class TaskResult {
 typedef HostClock = int Function();
 
 /// The minimal contract a generated per-task provider exposes. Generic in the typed
-/// Order/Result; the generated subtype binds them. `handleOrder` is the ONE seam a host
+/// Obligation/Result; the generated subtype binds them. `handleObligation` is the ONE seam a host
 /// loop calls per `requested` row.
 abstract interface class TaskProvider<O, R> {
   /// The framework `impureCapability` ids this provider is bound to (provenance — the host
   /// can assert it is draining the right capability). Carried as DATA, never hand-typed.
-  String get orderDirectiveId;
+  String get obligationDirectiveId;
   String get completeDirectiveId;
   String get failDirectiveId;
   String get blockDirectiveId;
   String get deadLetterDirectiveId;
 
-  /// DECODE an incoming Order intent's payload JSON into the typed [O], run the
+  /// DECODE an incoming Obligation intent's payload JSON into the typed [O], run the
   /// registered typed handler, and ENCODE the outcome into the ordinary Receipt intent — a
-  /// [NomosIntent] ready for the ONE write path (`dispatch`). `now` stamps the
+  /// [NomosIntent] ready for the ONE write path (`offer`). `now` stamps the
   /// terminal time. Decoding raw JSON happens HERE and only here; the handler the dev
   /// writes sees ONLY the typed [O] and returns ONLY a typed [TaskOutcome].
-  NomosIntent handleOrder(String orderPayloadJson, {required HostClock now});
+  NomosIntent handleObligation(String obligationPayloadJson, {required HostClock now});
 
-  /// Convenience: decode an Order payload from an already-parsed map (the host may have
-  /// the row's `data` map in hand from a read). Same path as [handleOrder].
-  NomosIntent handleOrderMap(
-    Map<String, Object?> orderPayload, {
+  /// Convenience: decode an Obligation payload from an already-parsed map (the host may have
+  /// the row's `data` map in hand from a read). Same path as [handleObligation].
+  NomosIntent handleObligationMap(
+    Map<String, Object?> obligationPayload, {
     required HostClock now,
   });
 }
 
-/// Decode an Order payload JSON string to a map for a generated `…Order.fromJson`.
-/// Shared so every generated provider decodes Orders identically (the symmetry of the
+/// Decode an Obligation payload JSON string to a map for a generated `…Obligation.fromJson`.
+/// Shared so every generated provider decodes Obligations identically (the symmetry of the
 /// client's `jsonEncode(toPayloadJson())`).
-Map<String, Object?> decodeOrderPayload(String orderPayloadJson) =>
-    (jsonDecode(orderPayloadJson) as Map<String, Object?>);
+Map<String, Object?> decodeObligationPayload(String obligationPayloadJson) =>
+    (jsonDecode(obligationPayloadJson) as Map<String, Object?>);

package/dart/lib/src/subscriptions.dart

@@ -7,8 +7,8 @@
 
 /// The READ half of the client boundary: typed, reactive subscriptions.
 ///
-/// END-STATE (the "dispatch(intent) purge", Jack 2026-06-01): the app's ONLY
-/// Nomos surface is `dispatch(intent)` (write — see `dispatch.dart`) + TYPED
+/// END-STATE (the "offer(intent) purge", Jack 2026-06-18): the app's ONLY
+/// Nomos surface is `offer(intent)` (write — see `offer.dart`) + TYPED
 /// PUB/SUB SUBSCRIPTIONS (read — here + the generated per-domain accessors). The
 /// app reads ONLY through generated typed accessors (`watchSites()`,
 /// `watchSite(id)`, indexed-field queries → typed results); it never hand-writes a
@@ -75,7 +75,7 @@ typedef Summer = int Function(String sumId, String groupKey);
 /// A "projection changed" tick: fires (any value) whenever a write may have
 /// advanced the projection, so the subscription re-runs its indexed read. The
 /// `query()`/`query_by_id()` closures are SYNCHRONOUS point-in-time reads; this tick is what
-/// makes a typed accessor REACTIVE. The app threads its existing post-`dispatch`
+/// makes a typed accessor REACTIVE. The app threads its existing post-`offer`
 /// invalidation signal in here (today the runtime's ~750ms projection poll / the
 /// write-completion broadcast). A read with no live tick is a one-shot current read.
 typedef ReadTick = Stream<void>;

package/dart/lib/src/webview_bridge.dart

@@ -8,7 +8,7 @@
 /// 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`).
+/// A WebView round-trip is ASYNC, so the bridge is async (unlike the sync FRB `Authorer` in `offer.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.
@@ -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,147 @@ 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});
-  }
-
-  /// 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();
+  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
+    });
   }
 
-  /// §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}));
+  /// LOCAL-FIRST offer: carry opaque intent bytes into the GitHolon. Returns the new local head; durable on [sync].
+  Future<String> offer({required String intentBytes}) async {
+    final r = _asMap(await _call('offer', {'intentBytes': intentBytes}));
     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 +281,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();
   }
 }