@githolon/dsl 0.27.0 → 0.28.0

package/dart/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 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.

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,
@@ -468,18 +569,19 @@ class NomosBridge {
   Future<Map<String, Object?>> shareWith({
     required String subject,
     required String relation,
-    required String authorSecret,
     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,
-      'authorSecret': authorSecret,
+      if (authorSecret != null) 'authorSecret': authorSecret,
       'asserterPrincipal': asserterPrincipal,
       'homeLawHash': homeLawHash,
       'object': object,
@@ -647,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;
 
@@ -692,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 =>
@@ -791,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.23.0
+version: 0.27.0
 
 environment:
   sdk: ^3.5.0

package/package.json

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

@@ -737,22 +737,30 @@ function typedIdClassForAggregateType(aggregateType: string): string {
 function collectEnums(
   aggregates: AggregateHandle[],
   directives: AnyDirective[],
+  domainKey: string,
 ): { dartTypes: Map<string, string>; decls: string[] } {
   const dartTypes = new Map<string, string>(); // "a|b|c" -> DartEnumName
   const usedNames = new Set<string>(); // every emitted enum name (collision guard)
   const decls: string[] = [];
+  // Generated enum types are DOMAIN-QUALIFIED (`EstateStatusEnum`,
+  // `Co2PlatformStatusEnum`) so two domains re-exported through one Dart barrel
+  // never collide on a bare `StatusEnum` — the collision that otherwise forces a
+  // hand-maintained `hide` list on the package barrel. The prefix is the field's
+  // semantic home, not an accident of import order.
+  const domainPrefix = dartTypeNameFromField(domainKey);
   const register = (preferredName: string, values: readonly string[]) => {
     const key = values.join("|");
     if (dartTypes.has(key)) return;
-    // Two DIFFERENT value-sets can prefer the SAME name (e.g. several `status`
-    // fields with distinct literal lists all want `StatusEnum`). Suffix on collision
-    // so each distinct value-set gets a UNIQUE Dart enum (`StatusEnum`, `Status2Enum`).
-    const base = `${dartTypeNameFromField(preferredName)}Enum`;
+    // Two DIFFERENT value-sets WITHIN one domain can prefer the SAME name (e.g.
+    // several `status` fields with distinct literal lists all want `StatusEnum`).
+    // Suffix on collision so each distinct value-set gets a UNIQUE Dart enum
+    // (`EstateStatusEnum`, `EstateStatus2Enum`).
+    const base = `${domainPrefix}${dartTypeNameFromField(preferredName)}Enum`;
     let name = base;
     let n = 1;
     while (usedNames.has(name)) {
       n += 1;
-      name = `${dartTypeNameFromField(preferredName)}${n}Enum`;
+      name = `${domainPrefix}${dartTypeNameFromField(preferredName)}${n}Enum`;
     }
     usedNames.add(name);
     dartTypes.set(key, name);
@@ -2560,7 +2568,11 @@ export interface DomainModule {
 /** Generate the full Dart source for one domain module. */
 export function generateDartDomain(mod: DomainModule): string {
   const domainKey = mod.domain ?? mod.name;
-  const { dartTypes, decls } = collectEnums(mod.aggregates, mod.directives);
+  const { dartTypes, decls } = collectEnums(
+    mod.aggregates,
+    mod.directives,
+    domainKey,
+  );
   const refIdClassForAggregate = refIdClassResolver(mod);
   const aggregatesById = new Map<string, AggregateHandle>();
   for (const a of mod.aggregates) aggregatesById.set(a.id, a);

package/src/codegen_proof.ts

@@ -40,6 +40,7 @@ import type { Field } from "./fields.js";
 import type { Directive } from "./directive.js";
 import type { DomainModule } from "./codegen_dart.js";
 import type { QueryDecl } from "./query.js";
+import type { FieldOp } from "./ops.js";
 import { finishCount } from "./count.js";
 import { mintedCreateField } from "./workspace_routing.js";
 import { deterministicPorts } from "./ctx.js";
@@ -336,6 +337,240 @@ function authorityConformanceLegLines(
   ];
 }
 
+/**
+ * THE RELATION-BOOTSTRAP LEG (the seed-then-prove POSITIVE — complements the negative conformance leg). On the
+ * LOCAL holon with fetch trapped: (1) dispatch the GRANT directive under the proof actor (its subject fields
+ * overwritten to the actor so the relation seats ON it), then (2) dispatch the GATED directive under the SAME
+ * actor and assert it SUCCEEDS — proving that once relation R is granted, an actor holding R authors the gated
+ * write (the exact loop the negative leg can't cover). Emits nothing when no granter is discoverable.
+ */
+function relationSeedLegLines(
+  leg: RelationBootstrapLeg | undefined,
+  factory: string,
+  n: () => number,
+): string[] {
+  if (leg === undefined) return [];
+  const ACTOR = `"user:proof-conformance"`;
+  // Grant payload: overwrite the routed subject/grantedBy fields (and any name-shaped fallback) with the actor.
+  const grantPayloadLit = (() => {
+    const overwrite = new Set<string>([...leg.grantSubjectFields, ...leg.grantGrantedByFields]);
+    const entries = Object.entries(leg.grantPayload).map(([k, v]) => {
+      // Also catch conventional subject/grantedBy field names the plan-probe couldn't value-match.
+      const looksSubject = /^(subject|principal|grantedBy|grantee|member|user)$/i.test(k);
+      return overwrite.has(k) || looksSubject
+        ? `${JSON.stringify(k)}: ${ACTOR}`
+        : `${JSON.stringify(k)}: ${JSON.stringify(v)}`;
+    });
+    return `{ ${entries.join(", ")} }`;
+  })();
+  const gatedPayloadLit = leg.gatedMintField !== undefined && leg.gatedAggregateId !== undefined
+    ? `{ ...${JSON.stringify(leg.gatedPayload)}, ${JSON.stringify(leg.gatedMintField)}: await holon.mint(${JSON.stringify(leg.gatedAggregateId)}) }`
+    : JSON.stringify(leg.gatedPayload);
+  return [
+    `// ${n()}. RELATION BOOTSTRAP (seed-then-prove the POSITIVE): \`${leg.domain}/${leg.gatedDirectiveId}\` is GATED`,
+    `//    (\`.requires("${leg.relation}")\`). \`${leg.domain}/${leg.grantDirectiveId}\` GRANTS "${leg.relation}" (${leg.via}).`,
+    `//    Grant it to the proof actor, THEN prove the gated write SUCCEEDS under that actor (what the negative`,
+    `//    conformance leg above can't cover — a seeded holder authoring a gated write).`,
+    `{`,
+    `  const realFetch3 = globalThis.fetch;`,
+    `  globalThis.fetch = (() => { throw new Error("OFFLINE PROOF VIOLATED: relation-bootstrap touched the network"); }) as typeof fetch;`,
+    `  try {`,
+    `    const ACTOR = ${ACTOR};`,
+    `    // (1) grant "${leg.relation}" to ACTOR (the grant folds a writeTuple; subject seated on ACTOR).`,
+    `    await ${factory}(holon, { actor: ACTOR }).${leg.grantDirectiveId}(${grantPayloadLit});`,
+    `    ok(\`relation bootstrap (grant) — ${leg.domain}/${leg.grantDirectiveId} granted "${leg.relation}" to \${ACTOR}\`);`,
+    `    // (2) the GATED write now SUCCEEDS under the seeded actor (holds "${leg.relation}").`,
+    `    await ${factory}(holon, { actor: ACTOR }).${leg.gatedDirectiveId}(${gatedPayloadLit});`,
+    `    ok(\`relation bootstrap (prove) — ${leg.domain}/${leg.gatedDirectiveId} authored under the seeded holder of "${leg.relation}" (gated write SUCCEEDS once granted)\`);`,
+    `  } finally {`,
+    `    globalThis.fetch = realFetch3;`,
+    `  }`,
+    `}`,
+    ``,
+  ];
+}
+
+// ── relation-bootstrap discovery (seed the gate: grant relation R, then prove a .requires(R) write SUCCEEDS) ──
+//
+// The NEGATIVE conformance leg above proves an ACTORLESS gated offer can't be generated. This POSITIVE leg
+// proves the other half: with the relation GRANTED, an actor that holds it authors the gated write SUCCESS-
+// fully. It needs a sibling directive that ESTABLISHES the relation (folds a granting `writeTuple`). We find
+// it two ways: FIRST a `.grants(R)` producer marker (the static, unambiguous lane — symmetric to `.requires`);
+// ELSE plan-probe each sibling for a `writeTuple`/relation-tuple op whose `relation === R` (inference).
+
+/** A discovered RELATION-BOOTSTRAP leg: a gated (`.requires(R)`) directive plus the sibling directive that
+ *  GRANTS R. The proof dispatches the grant FIRST (its subject/grantedBy set to the seeded proof actor), then
+ *  dispatches the gated directive under that actor and asserts it SUCCEEDS — the seed-then-prove positive. */
+export interface RelationBootstrapLeg {
+  /** The gated directive's domain. */
+  readonly domain: string;
+  /** The gated directive id (`.requires(relation)`). */
+  readonly gatedDirectiveId: string;
+  /** The relation the gate requires (and the grant establishes). */
+  readonly relation: string;
+  /** The synthesized gated-directive payload (auto-stamped `…At` omitted; mintField removed). */
+  readonly gatedPayload: Record<string, unknown>;
+  readonly gatedAutoStamped: readonly string[];
+  /** When the gated directive's own id is kernel-minted, the field to mint at runtime. */
+  readonly gatedMintField?: string;
+  /** The gated create's aggregate id (the mint's type tag) — present when `gatedMintField` is. */
+  readonly gatedAggregateId?: string;
+  /** The granting directive id (the sibling that folds the granting `writeTuple`). */
+  readonly grantDirectiveId: string;
+  /** The synthesized grant payload (auto-stamped `…At` omitted). The SUBJECT fields (below) are overwritten
+   *  at runtime with the seeded proof actor so the grant seats authority ON that actor. */
+  readonly grantPayload: Record<string, unknown>;
+  readonly grantAutoStamped: readonly string[];
+  /** The grant-payload field(s) whose value the plan routed into the tuple SUBJECT — set to the proof actor
+   *  at dispatch so the granted relation lands on the actor the gated write runs as. */
+  readonly grantSubjectFields: readonly string[];
+  /** Grant-payload field(s) routed into the tuple `grantedBy` — set to the proof actor (free attribution). */
+  readonly grantGrantedByFields: readonly string[];
+  /** How the granter was resolved — `"marker"` (`.grants(R)`) or `"inferred"` (plan-probe). Cosmetic. */
+  readonly via: "marker" | "inferred";
+}
+
+/** Run a directive's plan with a synthesized+probe payload under birth-probe globals and return the drained
+ *  field ops (authoring sink + returned ops). `undefined` ⇒ the plan couldn't be probed. */
+function probePlanOps(
+  dir: Directive<unknown>,
+  where: string,
+): { ops: FieldOp[]; synth: SynthesizedPayload; probePayload: Record<string, unknown> } | undefined {
+  let synth: SynthesizedPayload;
+  try {
+    synth = synthesizePayload(dir.payloadSchema as z.ZodTypeAny, where);
+  } catch {
+    return undefined;
+  }
+  const probePayload: Record<string, unknown> = { ...synth.value };
+  for (const f of synth.autoStamped) probePayload[f] = "2026-01-01T00:00:00Z";
+  let ops: FieldOp[] = [];
+  try {
+    withBirthProbeGlobals(() => {
+      __resetAuthoring();
+      __resetReads();
+      __resetBirths();
+      try {
+        const returned = dir.plan(probePayload as never, deterministicPorts({ physical: 1, replica: 1, principal: "principal:probe" }));
+        const drained = [...__drainAuthoring(), ...(Array.isArray(returned) ? returned : [])];
+        ops = drained.filter((o): o is FieldOp => (o as { kind?: string }).kind !== "strike");
+      } finally {
+        try { __drainReads(); __drainBirths(); } catch { /* drained */ }
+      }
+    });
+  } catch {
+    return undefined;
+  }
+  return { ops, synth, probePayload };
+}
+
+/** Does this directive's plan GRANT `relation` — i.e. fold a relation-tuple write whose `relation` field is
+ *  set to R (the `writeTuple`/`relateSubject` shape: a `set(rt, "relation", R)` op on a RelationTuple)? */
+function probeGrantsRelation(dir: Directive<unknown>, relation: string, where: string): boolean {
+  const probed = probePlanOps(dir, where);
+  if (probed === undefined) return false;
+  return probed.ops.some((o) => o.kind === "set" && o.field === "relation" && o.value === relation);
+}
+
+/** Resolve WHICH grant-payload fields route into the tuple subject / grantedBy — by matching the op values
+ *  the plan emitted (the subject `setEntry`'s entryKey, the `grantedBy` leaf) back to synthesized payload
+ *  values. Best-effort: an unmatched routing just leaves the field list empty (runtime falls back). */
+function resolveGrantSubjectFields(
+  probed: { ops: FieldOp[]; synth: SynthesizedPayload },
+): { subjectFields: string[]; grantedByFields: string[] } {
+  const { ops, synth } = probed;
+  const fieldForValue = (v: unknown): string | undefined =>
+    typeof v === "string" && v.length > 0
+      ? Object.entries(synth.value).find(([, sv]) => sv === v)?.[0]
+      : undefined;
+  const subjectFields = new Set<string>();
+  const grantedByFields = new Set<string>();
+  for (const o of ops) {
+    // The subject rides the tuple map entry KEY (`setEntry(rt, "subjects", <subjectRaw>, leaf)`).
+    if (o.kind === "setEntry" && o.field === "subjects" && typeof o.entryKey === "string") {
+      const f = fieldForValue(o.entryKey);
+      if (f !== undefined) subjectFields.add(f);
+      // grantedBy rides the JSON leaf value — scan the serialized leaf for any synthesized payload value.
+      if (typeof o.value === "string") {
+        for (const [name, sv] of Object.entries(synth.value)) {
+          if (typeof sv === "string" && sv.length > 0 && name !== fieldForValue(o.entryKey) && o.value.includes(sv)) {
+            grantedByFields.add(name);
+          }
+        }
+      }
+    }
+  }
+  return { subjectFields: [...subjectFields], grantedByFields: [...grantedByFields] };
+}
+
+/** Discover the RELATION-BOOTSTRAP leg for a module: the first gated (`.requires(R)`) directive plus the
+ *  sibling that ESTABLISHES R (prefer a `.grants(R)` marker; else plan-probe for a granting `writeTuple`).
+ *  `undefined` ⇒ no gated directive, or no discoverable granter (the negative conformance leg still runs). */
+export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstrapLeg | undefined {
+  const domain = mod.domain ?? mod.name;
+  const directives = mod.directives as Directive<unknown>[];
+  const gated = directives.find(
+    (d) =>
+      d?.requiresRelationGate !== undefined &&
+      typeof d.payloadSchema === "object" &&
+      d.birthsChild !== true &&
+      d.attestationAuthorizedGate === undefined,
+  );
+  if (gated === undefined) return undefined;
+  const relation = gated.requiresRelationGate!.relation;
+
+  // Synthesize the gated payload (mirror of the conformance leg — mintField removed, auto-stamped omitted).
+  let gatedSynth: SynthesizedPayload;
+  try {
+    gatedSynth = synthesizePayload(gated.payloadSchema as z.ZodTypeAny, `${domain}/${gated.id}`);
+  } catch {
+    return undefined;
+  }
+  const gatedAgg = (mod.aggregates as AggregateHandle[]).find((a) => a.id === gated.aggregateId);
+  const gatedMintField = gatedAgg !== undefined ? mintedCreateField(gated, gatedAgg) : undefined;
+  const gatedPayload: Record<string, unknown> = { ...gatedSynth.value };
+  if (gatedMintField !== undefined) delete gatedPayload[gatedMintField];
+
+  // Find the granter. FIRST prefer a `.grants(R)` marker (static, unambiguous). ELSE plan-probe siblings for
+  // a granting `writeTuple` whose relation === R. Never the gated directive itself.
+  const candidates = directives.filter((d) => d !== gated && typeof d?.payloadSchema === "object" && d.birthsChild !== true);
+  let via: "marker" | "inferred" = "marker";
+  let granter = candidates.find((d) => (d.grantsRelation ?? []).includes(relation));
+  if (granter === undefined) {
+    via = "inferred";
+    granter = candidates.find((d) => probeGrantsRelation(d, relation, `${domain}/${d.id}`));
+  }
+  if (granter === undefined) return undefined;
+
+  // Synthesize the grant payload + resolve which fields route into subject / grantedBy (so runtime seats the
+  // grant on the proof actor). Best-effort: an un-probable grant plan still emits the leg (runtime overwrites
+  // any field whose name looks like a subject/grantedBy anyway).
+  let grantSynth: SynthesizedPayload;
+  try {
+    grantSynth = synthesizePayload(granter.payloadSchema as z.ZodTypeAny, `${domain}/${granter.id}`);
+  } catch {
+    return undefined;
+  }
+  const grantPayload: Record<string, unknown> = { ...grantSynth.value };
+  const probed = probePlanOps(granter, `${domain}/${granter.id}`);
+  const routed = probed !== undefined ? resolveGrantSubjectFields(probed) : { subjectFields: [], grantedByFields: [] };
+
+  return {
+    domain,
+    gatedDirectiveId: gated.id,
+    relation,
+    gatedPayload,
+    gatedAutoStamped: gatedSynth.autoStamped,
+    ...(gatedMintField !== undefined ? { gatedMintField, gatedAggregateId: gated.aggregateId } : {}),
+    grantDirectiveId: granter.id,
+    grantPayload,
+    grantAutoStamped: grantSynth.autoStamped,
+    grantSubjectFields: routed.subjectFields,
+    grantGrantedByFields: routed.grantedByFields,
+    via,
+  };
+}
+
 // ── child-birth discovery (the G3 `.births()` lane — prove a parent birth end-to-end into the child) ──────
 
 /** ONE step of a discovered birth recipe's genesis chain (the subset codegen reads). */
@@ -634,8 +869,9 @@ export interface TsProofOptions {
  *   · `compile-valid`        — the law compiled (always — every compiled domain is at least this).
  *   · `standalone-provable`  — a `.creates` write proven offline (dispatch → declared query/count locally).
  *   · `child-birth-provable` — a `.births()` directive proven END-TO-END into the child it births.
+ *   · `relation-bootstrap-provable` — a `.requires(R)`-gated write proven to SUCCEED after granting R (seed-then-prove).
  *   · `live-cloud-provable`  — the full cloud loop (the `.mts` `--live` lane) completes (the primary domain). */
-export type ProofKind = "compile-valid" | "standalone-provable" | "child-birth-provable" | "live-cloud-provable";
+export type ProofKind = "compile-valid" | "standalone-provable" | "child-birth-provable" | "relation-bootstrap-provable" | "live-cloud-provable";
 
 /** The machine-readable OFFLINE legs for ONE domain (the `@nomos-proof-legs`
  *  marker shape; the `proof-legs.json` index is a map of these by domain key). */
@@ -657,6 +893,10 @@ export interface ProofLegs {
    *  When this domain is itself the BORN child's law (no standalone create), the index also registers the
    *  child domain key pointing at the SAME leg, so `proof --domain <child>` resolves through the parent birth. */
   readonly childBirth?: ChildBirthLeg;
+  /** THE RELATION-BOOTSTRAP LEG — present iff this domain has a `.requires(R)`-gated directive AND a
+   *  discoverable granter of R (a `.grants(R)` marker, or a plan-probed granting `writeTuple`). Proves the
+   *  gated write SUCCEEDS once R is granted (the seed-then-prove positive). Additive: absent ⇒ older/ungated. */
+  readonly relationBootstrap?: RelationBootstrapLeg;
 }
 
 /** Synthesize the standalone-create offline legs for one domain module, or `null` when it has no
@@ -727,9 +967,19 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
   const childBirth = birthDir !== undefined ? allBirths.find((b) => b.parentDomain === domain && b.birthDirectiveId === birthDir.id) : undefined;
   const childBirthWithSetup = childBirth !== undefined ? attachParentSetup(childBirth, allBirths) : undefined;
 
+  // The relation-bootstrap leg (when the domain has a `.requires(R)`-gated directive AND a discoverable
+  // granter of R). FAIL SOFT: no granter → no leg (the negative conformance leg still covers the gate).
+  let relationBootstrap: RelationBootstrapLeg | undefined;
+  try {
+    relationBootstrap = discoverRelationBootstrapLeg(mod);
+  } catch {
+    relationBootstrap = undefined;
+  }
+
   const legs: ProofKind[] = ["compile-valid"];
   if (standalone !== null) legs.push("standalone-provable");
   if (childBirthWithSetup !== undefined) legs.push("child-birth-provable");
+  if (relationBootstrap !== undefined) legs.push("relation-bootstrap-provable");
 
   return {
     domain,
@@ -746,6 +996,7 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
         }
       : {}),
     ...(childBirthWithSetup !== undefined ? { childBirth: childBirthWithSetup } : {}),
+    ...(relationBootstrap !== undefined ? { relationBootstrap } : {}),
   };
 }
 
@@ -1090,6 +1341,11 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   // throws MissingOfferAuthority. `undefined` ⇒ a documented no-op (the domain authors openly).
   const conformance = discoverAuthorityConformanceLeg(mod);
 
+  // THE RELATION-BOOTSTRAP LEG (the seed-then-prove positive): grant relation R to the proof actor, then prove
+  // a `.requires(R)`-gated write SUCCEEDS under that actor. `undefined` ⇒ no gated directive or no discoverable
+  // granter (the negative conformance leg still runs). Comes from the SAME `legsForDomain` synthesis (marker).
+  const relationBootstrap = primaryLegs.relationBootstrap;
+
   // Workspace-name slug: any package name → a safe, recognizable ws prefix.
   const slug =
     opts.packageName
@@ -1281,6 +1537,11 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   // offer is impossible to GENERATE (throws MissingOfferAuthority before any submit). No-op when un-gated.
   out.push(...authorityConformanceLegLines(conformance, factory, n));
 
+  // THE RELATION-BOOTSTRAP LEG (seed-then-prove the POSITIVE): grant relation R to the proof actor, then prove
+  // the gated write SUCCEEDS under that actor. Runs on the LOCAL holon (fetch re-trapped). Emits nothing when
+  // no granter is discoverable (the negative conformance leg still covers the gate).
+  out.push(...relationSeedLegLines(relationBootstrap, factory, n));
+
   // THE CHILD-BIRTH LEG (G3, gap 2): when the primary domain has a `.births()` directive, prove the birth
   // END-TO-END against the cloud — drive the parent birth offer, then read the BORN child workspace it spawns.
   if (childBirth !== undefined) {

package/src/directive.ts

@@ -175,6 +175,17 @@ export interface Directive<P = unknown> {
    * `attestationAuthorizedGate`/`.attestationAuthorized()` naming convention; the declaration is the noun.)
    */
   readonly birthsChild?: boolean;
+  /**
+   * PROOF-TOOLING PRODUCER MARKER (relation-seed leg). Declares that this directive ESTABLISHES the named
+   * relation(s) — i.e. its `plan` folds a `writeTuple` that grants the relation. Purely a static hint for
+   * the proof generator's relation-bootstrap leg (`discoverRelationBootstrapLeg`): it disambiguates which
+   * sibling directive to run FIRST to seed the actor before proving a `.requires(R)`-gated write succeeds,
+   * and resolves the "who grants the granter" / multiple-candidate ambiguity that pure plan-probe inference
+   * cannot. NO kernel/manifest effect (it is NOT lowered into any era key — the gate is the `writeTuple` the
+   * plan already folds); a directive that never calls `.grants()` is byte-identical to before. Set via the
+   * chainable `.grants(relation)` (symmetric to `.requires`).
+   */
+  readonly grantsRelation?: string[];
   /**
    * The directive's DECLARED required HOST CAPABILITIES — the capability PORTS the HOST must
    * PROVIDE for this directive to run (`OFFER_KERNEL_ARCHITECTURE.dot` cluster_ports / `OFFER_FLOW.dot`
@@ -301,6 +312,14 @@ export interface RequirableDirective<P> extends Directive<P> {
    * the canonical manifest to before this existed (the era rule). Returns a NEW requirable directive.
    */
   births(): RequirableDirective<P>;
+  /**
+   * PROOF-TOOLING PRODUCER MARKER (symmetric to `.requires`): declare that this directive ESTABLISHES the
+   * named relation (its `plan` folds a `writeTuple` granting it). A pure proof-generator hint — NO kernel /
+   * manifest / era-key effect. It tells the relation-bootstrap proof leg which sibling to run FIRST to seed
+   * the actor before proving a `.requires(relation)`-gated write succeeds, and resolves inference ambiguity.
+   * Accumulates + dedups; additive + non-destructive. A directive that never calls this is byte-identical.
+   */
+  grants(relation: string): RequirableDirective<P>;
 }
 
 /** Stage 1: id + a referential marker (which fixes the target aggregate). */
@@ -492,6 +511,13 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
       // the birth after admit. Era-ruled: a non-birthing directive omits the flag and is byte-identical.
       return makeRequirable({ ...base, birthsChild: true });
     },
+    grants(relation: string): RequirableDirective<P> {
+      // PROOF-TOOLING PRODUCER MARKER (symmetric to `.requires`): record that this directive establishes
+      // `relation` (its plan folds a granting `writeTuple`). NO kernel/manifest effect — a pure static hint
+      // the proof generator's relation-bootstrap leg reads. Accumulate + dedup; additive + non-destructive.
+      const merged = [...new Set([...(base.grantsRelation ?? []), relation])].sort();
+      return makeRequirable({ ...base, grantsRelation: merged });
+    },
   };
 }
 

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