@githolon/dsl 0.26.0 → 0.27.1

package/dart/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 0.27.0
+
+- TYPED SNAPSHOT RECOVERY (corrupt local custody): `NomosBridge.connect(recover: true)` recovers IN-PLACE from a corrupt restoreFrom snapshot — salvages local-only authored writes (via the fallible `intents_above`, which stops at a missing-ancestor gap) + the DLQ, refolds FRESH from cloud, re-offers the salvaged work (deduped), re-queues the DLQ. The report rides `bridge.lastRecovery` = `{salvagedWrites, requeuedDeadLetters, unsalvageable}` — a write the current law refuses lands in `unsalvageable` + the DLQ (surfaced, never dropped). Also `holon.salvage()` / `holon.absorbSalvage()`. Closes the restoreFrom-leaves-read-model-empty case.
+
+## 0.26.0
+
+- TIER-2 SYNC SIZE: `NomosBridge.syncSize()` → `{bytes, kind}` — how many bytes this workspace would transfer to catch up, WITHOUT downloading (a HEAD on the serving pack; the host answers Content-Length, cached ~15s). Sum across open workspaces for an aggregate "X MB to sync" total before any download.
+
+## 0.25.0
+
+- SYNC STATE + REAL LOADING BARS: `NomosBridge` gains `syncStatus` (Stream<SyncStatus> — phase/ahead/behind/saved/onMain/deadLetters/transfer/lastSyncedAt, derived from sync rounds + doorbell + transfer + a 4s metrics poll), `transferProgress` (Stream<TransferProgress> — live pack byte-progress; `total` is the host Content-Length so the bar is truthful, never estimated), and `currentStatus`. New types: SyncStatus, SyncPhase, TransferProgress.
+
+## 0.24.0
+
+- `createWorkspace` / `shareWith` no longer require `authorSecret` — it defaults to the connection's signing key (the home device key `NomosScope.home` loaded). A frontend dev never threads a key through make-workspace or share.
+
+## 0.23.0
+
+- `NomosBridge.shareWith` — one-call cross-custody share (sign quote + deliver recordShare to the subjects home). Closes the shared-with-me loop.
+
 ## 0.22.0
 
 - `NomosBridge.offerIntent` (canonical write verb; `offerDirective` kept as alias) + one-call `NomosBridge.createWorkspace` (sign + relay a control-plane offer).

package/dart/lib/src/webview_bridge.dart

@@ -202,6 +202,67 @@ class NomosBridgeError implements Exception {
   String toString() => 'NomosBridgeError: $message';
 }
 
+/// Live byte-progress of a custody pack transfer (the big initial clone / heavy resync over `/pack`).
+/// [total] is the host's REAL packed size from `Content-Length` (known before the first body byte — the
+/// warm host packs into memory then sends), so [fraction] is a truthful 0→1 bar, never an estimate.
+/// [total] is null only if the host omitted the length (then show an indeterminate spinner, not a fake bar).
+class TransferProgress {
+  final int received;
+  final int? total;
+  final String kind; // 'delta' (incremental) | 'full' (initial clone)
+  const TransferProgress({required this.received, this.total, this.kind = 'delta'});
+  double? get fraction => (total == null || total == 0) ? null : (received / total!).clamp(0.0, 1.0);
+  bool get done => total != null && received >= total!;
+  factory TransferProgress.fromMessage(Map<String, Object?> m) => TransferProgress(
+        received: (m['received'] as num?)?.toInt() ?? 0,
+        total: (m['total'] as num?)?.toInt(),
+        kind: m['kind']?.toString() ?? 'delta',
+      );
+}
+
+enum SyncPhase { idle, syncing, transferring, behind, offline, error }
+
+/// The app-ready sync state — a truthful aggregation of the low-level signals (sync rounds, the doorbell,
+/// transfer progress, periodic metrics). Map it straight to a sync-state page; no fake progress.
+class SyncStatus {
+  final SyncPhase phase;
+  final int ahead; // local writes not yet on canonical main
+  final int behind; // commits available to pull
+  final int saved; // durably persisted locally
+  final int onMain; // accepted on canonical main
+  final int deadLetters; // refused work awaiting a law fix
+  final TransferProgress? transfer; // non-null while a pack is moving
+  final DateTime? lastSyncedAt;
+  final String? lastError;
+  const SyncStatus({
+    this.phase = SyncPhase.idle,
+    this.ahead = 0,
+    this.behind = 0,
+    this.saved = 0,
+    this.onMain = 0,
+    this.deadLetters = 0,
+    this.transfer,
+    this.lastSyncedAt,
+    this.lastError,
+  });
+  SyncStatus copyWith({
+    SyncPhase? phase, int? ahead, int? behind, int? saved, int? onMain, int? deadLetters,
+    TransferProgress? transfer, bool clearTransfer = false, DateTime? lastSyncedAt,
+    String? lastError, bool clearError = false,
+  }) =>
+      SyncStatus(
+        phase: phase ?? this.phase,
+        ahead: ahead ?? this.ahead,
+        behind: behind ?? this.behind,
+        saved: saved ?? this.saved,
+        onMain: onMain ?? this.onMain,
+        deadLetters: deadLetters ?? this.deadLetters,
+        transfer: clearTransfer ? null : (transfer ?? this.transfer),
+        lastSyncedAt: lastSyncedAt ?? this.lastSyncedAt,
+        lastError: clearError ? null : (lastError ?? this.lastError),
+      );
+}
+
 /// THE BRIDGE. Construct over a [BridgeTransport], `await ready`, then `connect(...)` and drive the holon.
 class NomosBridge {
   final BridgeTransport _transport;
@@ -221,6 +282,15 @@ class NomosBridge {
       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 StreamController<TransferProgress> _transferEvents =
+      StreamController<TransferProgress>.broadcast();
+  // The DERIVED app-ready sync state. seeded-on-listen with a metrics poll; updated on sync/signal/transfer.
+  late final StreamController<SyncStatus> _syncStatusCtrl = StreamController<SyncStatus>.broadcast(
+    onListen: _startStatusPoll,
+    onCancel: () { if (!_syncStatusCtrl.hasListener) _stopStatusPoll(); },
+  );
+  SyncStatus _status = const SyncStatus();
+  Timer? _metricsTimer;
   final Completer<void> _ready = Completer<void>();
   int _seq = 0;
   final String _traceId = _newTraceId();
@@ -289,6 +359,22 @@ class NomosBridge {
     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);
+      if (event == 'sync') {
+        // a completed round → idle (the next metrics poll folds in residual ahead/behind), stamp the time.
+        _pushStatus(_status.copyWith(
+            phase: SyncPhase.idle, clearTransfer: true, lastSyncedAt: DateTime.now()));
+      } else if (m['status'] == 'closed' || m['status'] == 'offline') {
+        _pushStatus(_status.copyWith(phase: SyncPhase.offline));
+      }
+      return;
+    }
+    if (event == 'transfer') {
+      // LIVE pack byte-progress { received, total, kind } — the real loading bar (host Content-Length).
+      final tp = TransferProgress.fromMessage(m);
+      if (!_transferEvents.isClosed) _transferEvents.add(tp);
+      _pushStatus(_status.copyWith(
+          phase: tp.done ? SyncPhase.syncing : SyncPhase.transferring,
+          transfer: tp, clearTransfer: tp.done));
       return;
     }
     if (event == 'trace') {
@@ -299,6 +385,8 @@ class NomosBridge {
     if (event == 'signal') {
       // signal holon projection: ephemeral coordination such as peer frontiers / lag.
       if (!_signalEvents.isClosed) _signalEvents.add(m);
+      // the doorbell says canonical main advanced → we're behind until the next pull lands.
+      if (_status.phase == SyncPhase.idle) _pushStatus(_status.copyWith(phase: SyncPhase.behind));
       return;
     }
     if (event == 'span') {
@@ -366,8 +454,9 @@ class NomosBridge {
       String? authToken,
       String? authorSecret,
       String? restoreFrom,
-      bool allowUnborn = false}) async {
-    await _call('connect', {
+      bool allowUnborn = false,
+      bool recover = false}) async {
+    final r = _asMap(await _call('connect', {
       'cloud': cloud,
       'workspace': workspace,
       if (clientId != null) 'clientId': clientId,
@@ -377,9 +466,19 @@ class NomosBridge {
       if (authorSecret != null) 'authorSecret': authorSecret,
       if (restoreFrom != null) 'restoreFrom': restoreFrom,
       if (allowUnborn) 'allowUnborn': true,
-    });
+      // RECOVER-IN-PLACE over a corrupt restoreFrom snapshot: salvage local-only writes + DLQ, refold fresh
+      // from cloud, re-offer the salvaged work. The report lands on [lastRecovery]. Nothing local is lost.
+      if (recover) 'recover': true,
+    }));
+    _lastRecovery = (r['recovery'] as Map?)?.cast<String, Object?>();
   }
 
+  /// The salvage report from the most recent `connect(recover: true)` — `{ salvagedWrites, requeuedDeadLetters,
+  /// unsalvageable }`, or null if the connection didn't recover. Show "recovered N writes" / surface
+  /// `unsalvageable` (writes the current law refused — kept in the DLQ, never dropped).
+  Map<String, Object?>? get lastRecovery => _lastRecovery;
+  Map<String, Object?>? _lastRecovery;
+
   /// 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}));
@@ -438,17 +537,19 @@ class NomosBridge {
   Future<Map<String, Object?>> createWorkspace({
     required String parent,
     required String actor,
-    required String authorSecret,
+    String? authorSecret,
     String? name,
     Object? payload,
     String directiveId = 'createWorkspace',
     String? domainHash,
     String? authToken,
   }) async {
+    // [authorSecret] defaults to the connection's signing key (the home key NomosScope.home loaded) —
+    // a frontend dev never threads a key through.
     final r = _asMap(await _call('createWorkspace', {
       'parent': parent,
       'actor': actor,
-      'authorSecret': authorSecret,
+      if (authorSecret != null) 'authorSecret': authorSecret,
       if (name != null) 'name': name,
       if (payload != null) 'payload': payload,
       'directiveId': directiveId,
@@ -458,6 +559,39 @@ class NomosBridge {
     return (r['verdict'] as Map?)?.cast<String, Object?>() ?? r;
   }
 
+  /// SHARE a workspace/record with a user — the one-call cross-custody grant that lands in their home's
+  /// "shared-with-me" list. This holon signs a quote `<asserterWorkspace>:<object>#<relation>@<subject>` with
+  /// [authorSecret] (the asserting owner's device key — the signature IS the grant) and delivers a
+  /// `recordShare` to the subject's home; the home's gate verifies it (no key needed there). Live authority
+  /// stays the forward Check on the asserter when the user opens it. Returns the worker verdict; an unborn
+  /// home (the user never logged in) comes back `{ok:false, needsHomeBirth:true}`.
+  /// `await bridge.shareWith(subject:'user:bob', relation:'editor', authorSecret: key, asserterPrincipal:'user:ada', homeLawHash: h)`.
+  Future<Map<String, Object?>> shareWith({
+    required String subject,
+    required String relation,
+    required String asserterPrincipal,
+    required String homeLawHash,
+    String? authorSecret,
+    String object = 'workspace:self',
+    String? asserterWorkspace,
+    String? attestedAt,
+    String? authToken,
+  }) async {
+    // [authorSecret] defaults to the connection's signing key — the frontend dev never handles a key.
+    final r = _asMap(await _call('shareWith', {
+      'subject': subject,
+      'relation': relation,
+      if (authorSecret != null) 'authorSecret': authorSecret,
+      'asserterPrincipal': asserterPrincipal,
+      'homeLawHash': homeLawHash,
+      'object': object,
+      if (asserterWorkspace != null) 'asserterWorkspace': asserterWorkspace,
+      if (attestedAt != null) 'attestedAt': attestedAt,
+      if (authToken != null) 'authToken': authToken,
+    }));
+    return (r['verdict'] as Map?)?.cast<String, Object?>() ?? r;
+  }
+
   Future<Map<String, Object?>> undoMostRecent({
     String scope = 'all',
     List<String>? actions,
@@ -615,6 +749,52 @@ class NomosBridge {
   /// Background-sync telemetry: each autoSync round (`event:'sync'`) and doorbell socket state (`event:'link'`).
   Stream<Map<String, Object?>> get syncEvents => _syncEvents.stream;
 
+  /// LIVE pack byte-progress — the real loading bar. Each event carries `received`/`total` (the host's
+  /// actual `Content-Length`, known before the body) + `kind` ('delta'|'full'). Emits only while a `/pack`
+  /// transfer is moving (small syncs ride the inline offer-result piggyback — instant, no bar).
+  Stream<TransferProgress> get transferProgress => _transferEvents.stream;
+
+  /// THE APP-READY SYNC STATE — a truthful aggregation of sync rounds, the doorbell, transfer progress, and a
+  /// periodic metrics poll. Map straight to a sync-state page. Starts a lightweight 4s metrics poll while
+  /// listened to (stops on cancel). [currentStatus] is the latest snapshot for a non-stream read.
+  Stream<SyncStatus> get syncStatus => _syncStatusCtrl.stream;
+  SyncStatus get currentStatus => _status;
+
+  void _pushStatus(SyncStatus s) {
+    _status = s;
+    if (!_syncStatusCtrl.isClosed) _syncStatusCtrl.add(s);
+  }
+
+  void _startStatusPoll() {
+    _pushStatus(_status); // seed the new listener with the current snapshot
+    _pollMetricsOnce();
+    _metricsTimer ??= Timer.periodic(const Duration(seconds: 4), (_) => _pollMetricsOnce());
+  }
+
+  void _stopStatusPoll() {
+    _metricsTimer?.cancel();
+    _metricsTimer = null;
+  }
+
+  Future<void> _pollMetricsOnce() async {
+    try {
+      final m = await metrics();
+      int? n(String k) => m.containsKey(k) ? ((m[k] as num?)?.toInt() ?? 0) : null;
+      final ahead = n('ahead') ?? _status.ahead;
+      final behind = n('behind') ?? _status.behind;
+      // Don't stomp an in-flight transfer's phase; otherwise derive idle/behind/syncing from the counts.
+      final phase = _status.transfer != null
+          ? _status.phase
+          : (behind > 0 ? SyncPhase.behind : (ahead > 0 ? SyncPhase.syncing : SyncPhase.idle));
+      _pushStatus(_status.copyWith(
+        ahead: ahead, behind: behind, saved: n('saved'), onMain: n('onMain'),
+        deadLetters: n('deadLetters'), phase: phase, clearError: true,
+      ));
+    } catch (e) {
+      _pushStatus(_status.copyWith(phase: SyncPhase.error, lastError: e.toString()));
+    }
+  }
+
   /// Ephemeral signal-holon projections (`event:'signal'`), currently peer frontiers / lag for the workspace.
   Stream<Map<String, Object?>> get signalEvents => _signalEvents.stream;
 
@@ -660,6 +840,12 @@ class NomosBridge {
   Future<Map<String, Object?>> metrics() async =>
       _asMap(await _call('metrics'));
 
+  /// TIER-2 SYNC SIZE — how many bytes this workspace would transfer to catch up to main, WITHOUT downloading
+  /// them (a HEAD on the serving pack; the host answers Content-Length only, cached ~15s). Sum across your open
+  /// workspaces for an aggregate "X MB to sync" total BEFORE downloading. `{ bytes, kind:'delta'|'full'|
+  /// 'up-to-date' }`; `bytes` is null if the host omitted the length.
+  Future<Map<String, Object?>> syncSize() async => _asMap(await _call('syncSize'));
+
   /// 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 =>
@@ -759,9 +945,12 @@ class NomosBridge {
       if (!w.isClosed) await w.close();
     }
     _compatWatches.clear();
+    _stopStatusPoll();
     if (!_syncEvents.isClosed) await _syncEvents.close();
     if (!_signalEvents.isClosed) await _signalEvents.close();
     if (!_flameEvents.isClosed) await _flameEvents.close();
     if (!_spanEvents.isClosed) await _spanEvents.close();
+    if (!_transferEvents.isClosed) await _transferEvents.close();
+    if (!_syncStatusCtrl.isClosed) await _syncStatusCtrl.close();
   }
 }

package/dart/pubspec.yaml

@@ -11,7 +11,7 @@ description: >-
   Nomos 2 Dart frontend types — the hand-written kernel wire types plus the
   code-generated per-domain aggregate + directive-payload types. (De)serializes
   the EXACT serde JSON the Rust kernel + projection produce/consume.
-version: 0.22.0
+version: 0.27.0
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.26.0",
+  "version": "0.27.1",
   "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

@@ -783,6 +783,48 @@ export const retireWorkspace = directive("retireWorkspace")
   })
   .requires("admin");
 
+/**
+ * retireOwnWorkspace — SELF-SERVICE retirement: the principal who CREATED a workspace may retire it (you
+ * made it, you can withdraw it — e.g. `githolon proof --live` cleaning up its throwaway workspace). Same
+ * effect as {@link retireWorkspace} (status → retired, custody untouched) but gated by `creator` (the birth
+ * authority) and SCOPED by {@link retireOwnOnly} to records THIS principal created — so a creator can only
+ * retire its OWN workspaces, never another's. Admins keep the unrestricted {@link retireWorkspace}.
+ */
+export const retireOwnWorkspace = directive("retireOwnWorkspace")
+  .mutates(CloudWorkspace)
+  .payload(
+    z.object({
+      workspaceId: z.string().min(1),
+      retiredBy: z.string().min(1),
+      retiredAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    const ws = instance(CloudWorkspace, p.workspaceId);
+    return [set(ws, "status", "retired" as const)];
+  })
+  .requires("creator");
+
+/** A creator may retire ONLY a workspace it created — the captured author must equal the record's
+ *  `createdBy` (set at {@link createWorkspace}/birth). A record read of the target (no new declared query),
+ *  so the read manifest is unchanged (era-/evolve-safe). */
+export const retireOwnOnly = workspaceInvariant("RetireOwnOnly")
+  .on("retireOwnWorkspace")
+  .reads((ctx) => [
+    refAs("target", "CloudWorkspace", "pre:" + String((ctx?.intent ?? {}).workspaceId ?? "")),
+  ])
+  .assert((refs, ctx) => {
+    const target = (refs as { target?: { principal?: string; createdBy?: string } }).target;
+    const author = ctx?.principal ?? "";
+    // The captured, VERIFIED author must equal the record's recorded creator (its `principal`/`createdBy`,
+    // set by the same identity at createWorkspace). So a creator may retire ONLY its own workspaces.
+    return author &&
+      ((target?.principal && target.principal === author) ||
+        (target?.createdBy && target.createdBy === author))
+      ? { accept: true }
+      : { reject: "retire-own-only: only the workspace's creator may retire it" };
+  });
+
 /**
  * reclaimWorkspace — THE LAWFUL CUSTODY DISCARD. Where {@link retireWorkspace}
  * withdraws the law (a status, the bytes untouched), reclaim is the law AUTHORIZING