@githolon/dsl 0.59.1 → 0.60.1

package/dart/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 0.41.0
+- `NomosTestHarness` emits named phase-progress diagnostics (install → spawn runner → await ready → connect, plus per-session progress in `cluster`) and each `connect()` carries a `connectTimeout` (default 120s) that throws a NAMED remedy instead of hanging — so a multi-test AppSim run can tell install vs runner-wait vs session-block vs deadlock (co2 feedback).
+
+## 0.40.0
+- `connect(maxMounted: …)` — the realm's mounted-workspace budget (LRU park/remount above it); useful on memory-constrained devices holding many local workspaces.
+- MULTI-WORKSPACE BY DEFAULT IN TESTS: `NomosTestHarness.ephemeral` now connects a DECOY session alongside the workspace under test, and `harness.bridge` is a `NomosSession` HANDLE pinned to it (existing tenant tests work unchanged). Sole-session inference therefore never silently passes under the harness — an op that forgot its session refuses in your first test with the same `multiple sessions connected — pass session` a real multi-workspace app raises. Opt out with `decoySession: false`.
+- `NomosBridge.open(...)` — connect + pinned `NomosSession` handle in one call (`final home = await bridge.open(workspace: …); HomeClient(home)`): the recommended plane/handle shape; the bare bridge methods remain one-workspace sugar.
+
+## 0.39.0
+- Multi-session compat surface: `watchCompatibility` takes an optional `session`; `NomosSession` pins its compat watch, `compat`, and `onLawChanged` to ITS workspace (per-session `lawChanged` scoping — previously a multi-session plane's compat verdict was whichever session synced last, and a session's compat watch refused on a >1-session plane).
+
 ## 0.38.0
 - SPLIT: the pure data core (wire types, offer codec, NomosReads, aggregate meta, schema validation, error info) moved to the new `nomos_types` package; `nomos_client` depends on and re-exports it, so existing imports are unchanged. Frontend/UI code can now depend on `nomos_types` alone.
 

package/dart/lib/src/test_harness.dart

@@ -43,8 +43,15 @@ class NomosTestHarnessException implements Exception {
   String toString() => 'NomosTestHarnessException: $message';
 }
 
+/// The decoy session [NomosTestHarness.ephemeral] connects alongside the workspace under test — it exists
+/// so the plane is ALWAYS multi-session in tests (sole-session inference never silently passes).
+const String _decoyWorkspace = '__nomos-decoy';
+
 class NomosTestHarness {
   /// The connected bridge — hand it to the generated typed clients (the same surface the app UI uses).
+  /// For [ephemeral] this is a [NomosSession] HANDLE pinned to [workspace] (the plane underneath also
+  /// holds a decoy session, so unpinned plane-level calls refuse the way they would in a real
+  /// multi-workspace app); for [cluster] it is the shared plane — name sessions via [session].
   final NomosBridge bridge;
 
   /// The local workspace name the law was installed into.
@@ -129,6 +136,8 @@ class NomosTestHarness {
     void Function(Future<void> Function())? registerTearDown,
     void Function(String line)? onDiagnostic,
     Duration readyTimeout = const Duration(seconds: 30),
+    Duration connectTimeout = const Duration(seconds: 120),
+    bool decoySession = true,
   }) async {
     if (deployJsonPaths.isEmpty) {
       throw NomosTestHarnessException(
@@ -154,8 +163,10 @@ class NomosTestHarness {
     final workdir = await Directory.systemTemp.createTemp('nomos-harness-');
     // Total-ordered teardown even on a mid-setup failure: build the transport lazily and clean up on throw.
     NodeRunnerTransport? transport;
+    final phase = (String m) { if (onDiagnostic != null) onDiagnostic('[nomos-test-harness] $m'); };
     try {
       final snapshot = '${workdir.path}/snapshot.bin';
+      phase('phase 1/4 installing ${deployJsonPaths.length} law package(s) offline into "$workspace" …');
       final info = await _runInstall(
           node: node,
           useInRepoScript: useInRepoScript,
@@ -167,6 +178,7 @@ class NomosTestHarness {
           runtimeDir: runtimeDir,
           onDiagnostic: onDiagnostic);
 
+      phase('phase 2/4 spawning the node runner (node=$node) …');
       transport = await NodeRunnerTransport.start(
         entry: entry,
         resolveFrom: resolveFrom,
@@ -178,19 +190,44 @@ class NomosTestHarness {
         },
         onDiagnostic: onDiagnostic,
       );
-      final bridge = NomosBridge(transport);
-      await bridge.ready.timeout(readyTimeout,
+      final plane = NomosBridge(transport);
+      phase('phase 3/4 awaiting runner ready (≤${readyTimeout.inSeconds}s) …');
+      await plane.ready.timeout(readyTimeout,
           onTimeout: () => throw NomosTestHarnessException(
-              'the offline runner never signalled ready within $readyTimeout '
-              '(is `node` on PATH and ~/.holon/runtime warm?)'));
-      await bridge.connect(
+              'the offline runner never signalled ready within ${readyTimeout.inSeconds}s '
+              '(phase 3/4: is `node` on PATH and ~/.holon/runtime warm? the runner process may have '
+              'failed to boot the engine — run with onDiagnostic to see its stderr)'));
+      phase('phase 4/4 connecting session "$workspace" (≤${connectTimeout.inSeconds}s) …');
+      await plane.connect(
         cloud: 'https://offline.invalid', // ignored: the offline runner serves everything locally
         workspace: workspace,
         clientId: clientId,
         allowUnborn: true,
-      );
+      ).timeout(connectTimeout,
+          onTimeout: () => throw NomosTestHarnessException(
+              'connect("$workspace") did not complete within ${connectTimeout.inSeconds}s (phase 4/4) — '
+              'the runner is up but the session never mounted; a large ledger converge-fold can be slow, '
+              'raise connectTimeout, or run with onDiagnostic to see where it blocked'));
+      phase('ready — session "$workspace" connected (law ${(info['lawHashes'] as List?)?.isNotEmpty == true ? (info['lawHashes'] as List).first.toString().substring(0, 12) : "installed"})');
+      // THE DECOY SESSION (multi-workspace by default in tests): sole-session inference is how
+      // single-workspace assumptions ship — with one session connected, an op that forgot its session
+      // silently works in tests and only refuses in production when the app connects its second
+      // workspace. The decoy keeps the plane at ≥2 sessions so any unpinned op refuses HERE, in the
+      // dev's first test. [bridge] is a SESSION HANDLE pinned to [workspace], so tenant code written
+      // against the harness keeps working unchanged; only code that grabs the raw plane and assumes
+      // single-session trips. Opt out with `decoySession: false` (please don't).
+      if (decoySession) {
+        await plane.connect(
+          cloud: 'https://offline.invalid',
+          workspace: _decoyWorkspace,
+          session: _decoyWorkspace,
+          clientId: '$clientId-decoy',
+          allowUnborn: true,
+          restoreFrom: base64Encode(await File(snapshot).readAsBytes()),
+        );
+      }
       final harness = NomosTestHarness._(
-          bridge, workspace, transport, workdir, onDiagnostic, [workspace],
+          plane.session(workspace), workspace, transport, workdir, onDiagnostic, [workspace],
           frameworkHash: info['frameworkHash']?.toString(),
           lawHashes: {
             workspace: ((info['lawHashes'] as List?) ?? const [])
@@ -241,6 +278,7 @@ class NomosTestHarness {
     void Function(Future<void> Function())? registerTearDown,
     void Function(String line)? onDiagnostic,
     Duration readyTimeout = const Duration(seconds: 30),
+    Duration connectTimeout = const Duration(seconds: 120),
   }) async {
     if (workspaces.isEmpty) {
       throw NomosTestHarnessException(
@@ -287,6 +325,8 @@ class NomosTestHarness {
       }
 
       // 2. ONE runner / ONE bridge for the whole plane — no env restore default; each connect brings its own.
+      final phase = (String m) { if (onDiagnostic != null) onDiagnostic('[nomos-test-harness] $m'); };
+      phase('cluster: spawning the node runner for ${workspaces.length} workspace(s) …');
       transport = await NodeRunnerTransport.start(
         entry: entry,
         resolveFrom: resolveFrom,
@@ -298,24 +338,32 @@ class NomosTestHarness {
         onDiagnostic: onDiagnostic,
       );
       final bridge = NomosBridge(transport);
+      phase('cluster: awaiting runner ready (≤${readyTimeout.inSeconds}s) …');
       await bridge.ready.timeout(readyTimeout,
           onTimeout: () => throw NomosTestHarnessException(
-              'the offline runner never signalled ready within $readyTimeout '
-              '(is `node` on PATH and ~/.holon/runtime warm?)'));
+              'the offline runner never signalled ready within ${readyTimeout.inSeconds}s '
+              '(is `node` on PATH and ~/.holon/runtime warm? run with onDiagnostic to see the runner stderr)'));
 
       // 3. connect one SESSION per workspace, each restoring its OWN snapshot — LOCAL-ONLY (no cloud;
       //    these are local githolons on the device plane, offline by nature).
       final snapshotB64 = <String, String>{};
+      var _n = 0;
       for (final e in workspaces.entries) {
         snapshotB64[e.key] = base64Encode(await File(snapshots[e.key]!).readAsBytes());
+        phase('cluster: connecting session ${++_n}/${workspaces.length} "${e.key}" (≤${connectTimeout.inSeconds}s) …');
         await bridge.connect(
           workspace: e.key,
           session: e.key,
           clientId: '$clientId-${e.key}',
           restoreFrom: snapshotB64[e.key],
           allowUnborn: true,
-        );
+        ).timeout(connectTimeout,
+            onTimeout: () => throw NomosTestHarnessException(
+                'connect("${e.key}") did not complete within ${connectTimeout.inSeconds}s — the runner is up '
+                'but this session never mounted (a large ledger converge-fold can be slow; raise connectTimeout '
+                'or run with onDiagnostic)'));
       }
+      phase('cluster: ${workspaces.length} session(s) connected');
 
       // 3b. DEVICE-KEY the named sessions: mint a fresh in-kernel key on each (now that it is mounted) and
       //     RE-OPEN it with that key as its signing authorSecret — the resolver's attested-read signing key.

package/dart/lib/src/webview_bridge.dart

@@ -626,6 +626,10 @@ class NomosBridge {
   final Map<String, StreamController<Map<String, Object?>>> _compatWatches = {};
   // COMPAT SUPERPOWER (#72b): the last computed verdict + the live `lawChanged` event stream.
   NomosCompat? _lastCompat;
+  // per-session compat state — a multi-session plane syncs law changes on MANY workspaces; a
+  // [NomosSession]'s compat/onLawChanged must answer for ITS workspace, not whichever synced last.
+  final Map<String, NomosCompat> _lastCompatBySession = {};
+  final Map<String, StreamController<NomosCompat>> _lawChangedBySession = {};
   final StreamController<NomosCompat> _lawChanged =
       StreamController<NomosCompat>.broadcast();
   final StreamController<Map<String, Object?>> _syncEvents =
@@ -728,7 +732,10 @@ class NomosBridge {
       final c = NomosCompat.fromJson((m['compat'] as Map?)?.cast<String, Object?>());
       if (c != null) {
         _lastCompat = c;
+        final sess = m['session'] as String?;
+        if (sess != null) _lastCompatBySession[sess] = c;
         if (!_lawChanged.isClosed) _lawChanged.add(c);
+        if (sess != null) _lawChangedBySession[sess]?.add(c);
       }
       return;
     }
@@ -856,7 +863,8 @@ class NomosBridge {
       String? restoreFrom,
       bool allowUnborn = false,
       bool recover = false,
-      String? session}) async {
+      String? session,
+      int? maxMounted}) async {
     final ws = session ?? workspace;
     _sessionNames.add(ws);
     final r = _asMap(await _call('connect', {
@@ -875,6 +883,8 @@ class NomosBridge {
       if (authorSecret != null) 'authorSecret': authorSecret,
       if (restoreFrom != null) 'restoreFrom': restoreFrom,
       if (allowUnborn) 'allowUnborn': true,
+      // the realm's mounted-workspace budget (LRU park/remount above it) — first connect wins.
+      if (maxMounted != null) 'maxMounted': maxMounted,
       // 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,
@@ -1494,6 +1504,33 @@ class NomosBridge {
     return v;
   }
 
+  /// CONNECT AS A HANDLE (the recommended multi-workspace shape): [connect] + a [NomosSession] pinned to
+  /// the opened session in one call — `final home = await bridge.open(workspace: 'home-…');` then
+  /// `HomeClient(home)`. The bare [NomosBridge] methods remain the ONE-workspace sugar over an inferred
+  /// default session; an app that opens a second workspace should hold handles, not call the plane.
+  Future<NomosSession> open(
+      {String? cloud,
+      required String workspace,
+      String? clientId,
+      String? authToken,
+      String? authorSecret,
+      String? restoreFrom,
+      bool allowUnborn = false,
+      bool recover = false,
+      String? session}) async {
+    await connect(
+        cloud: cloud,
+        workspace: workspace,
+        clientId: clientId,
+        authToken: authToken,
+        authorSecret: authorSecret,
+        restoreFrom: restoreFrom,
+        allowUnborn: allowUnborn,
+        recover: recover,
+        session: session);
+    return this.session(session ?? workspace);
+  }
+
   /// The last computed compat verdict (set by [checkCompat] / a `lawChanged` event). Null until bind.
   NomosCompat? get compat => _lastCompat;
 
@@ -1513,7 +1550,8 @@ class NomosBridge {
   /// workspace's installed law changes (another peer installs/upgrades/retires a domain and it
   /// syncs in). The verdict carries `offerKnown`. The app degrades/prompts on `ok:false`.
   Stream<Map<String, Object?>> watchCompatibility(
-      Map<String, Object?> requirement) {
+      Map<String, Object?> requirement,
+      [String? session]) {
     final subId = 'c${++_seq}';
     late final StreamController<Map<String, Object?>> ctrl;
     ctrl = StreamController<Map<String, Object?>>(
@@ -1521,6 +1559,7 @@ class NomosBridge {
         'subId': subId,
         'kind': 'compat',
         'requirement': requirement,
+        if (session != null) 'session': session,
       }),
       onCancel: () async {
         _compatWatches.remove(subId);
@@ -1656,14 +1695,20 @@ class NomosSession extends NomosBridge {
       parent.watchSpatial(spatialId, bbox, session ?? workspace);
   @override
   Stream<Map<String, Object?>> watchCompatibility(
-          Map<String, Object?> requirement) =>
-      parent.watchCompatibility(requirement);
+          Map<String, Object?> requirement,
+          [String? session]) =>
+      parent.watchCompatibility(requirement, session ?? workspace);
 
   // Live snapshots / streams reflect the shared plane — read them off the parent's controllers.
+  // compat/onLawChanged are LAW-scoped, so a session answers for ITS workspace (falling back to the
+  // plane-wide value when the runner's events carry no session key — older bundles).
   @override
-  NomosCompat? get compat => parent.compat;
+  NomosCompat? get compat =>
+      parent._lastCompatBySession[workspace] ?? parent.compat;
   @override
-  Stream<NomosCompat> get onLawChanged => parent.onLawChanged;
+  Stream<NomosCompat> get onLawChanged => (parent._lawChangedBySession[
+          workspace] ??=
+      StreamController<NomosCompat>.broadcast()).stream;
   @override
   Map<String, Object?>? get lastRecovery => parent.lastRecovery;
   @override

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.38.0
+version: 0.41.0
 
 environment:
   sdk: ^3.5.0

package/dart/test/test_harness_test.dart

@@ -11,6 +11,7 @@ library;
 
 import 'dart:io';
 
+import 'package:nomos_client/nomos_client.dart';
 import 'package:nomos_client/nomos_headless.dart';
 import 'package:test/test.dart';
 
@@ -82,6 +83,54 @@ void main() {
     stdout.writeln('offline harness green: ws=${harness.workspace}');
   }, timeout: const Timeout(Duration(minutes: 2)));
 
+  test('DECOY: the harness plane is multi-session — an unpinned plane op refuses like production', () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final harness = await NomosTestHarness.ephemeral(
+      deployJsonPaths: [_guestbookDeployJson],
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      registerTearDown: addTearDown,
+    );
+    // harness.bridge is a SESSION HANDLE — pinned ops work as before…
+    expect(harness.bridge, isA<NomosSession>());
+    expect(await harness.bridge.query('entriesByAuthor', {'author': 'x'}), isEmpty);
+    // …but the RAW PLANE holds the decoy too, so an op that forgot its session refuses HERE —
+    // exactly the refusal a real multi-workspace app would hit (never a silent sole-session guess).
+    final plane = (harness.bridge as NomosSession).parent;
+    await expectLater(
+      plane.query('entriesByAuthor', {'author': 'x'}),
+      throwsA(predicate((e) => '$e'.contains('multiple sessions'))),
+    );
+  }, timeout: const Timeout(Duration(minutes: 2)));
+
+  test('DX: ephemeral emits phase-progress diagnostics (install → runner → ready → connect)', () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final lines = <String>[];
+    final harness = await NomosTestHarness.ephemeral(
+      deployJsonPaths: [_guestbookDeployJson],
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      registerTearDown: addTearDown,
+      onDiagnostic: lines.add,
+    );
+    final joined = lines.join('\n');
+    // the four named phases are surfaced so an AppSim can tell install vs runner-wait vs connect-block.
+    expect(joined, contains('phase 1/4 installing'));
+    expect(joined, contains('phase 2/4 spawning the node runner'));
+    expect(joined, contains('phase 3/4 awaiting runner ready'));
+    expect(joined, contains('phase 4/4 connecting session'));
+    expect(joined, contains('ready — session "test-ws" connected'));
+    expect(harness.bridge, isNotNull);
+  }, timeout: const Timeout(Duration(minutes: 2)));
+
   test('OFFLINE: dispose is idempotent and removes the temp dir', () async {
     final skip = _missingPrereq();
     if (skip != null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.59.1",
+  "version": "0.60.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/codegen_dart_client.ts

@@ -350,6 +350,11 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `// Drives the REAL githolon over a NomosBridge (the WebView runner). Regenerated every compile; do`,
     `// not edit. Construct with a connected bridge:`,
     `//`,
+    // GENERATED-CODE lints: the bridge read/watch surface returns dynamic (JSON rows), so typed accessors
+    // do dynamic member access + casts by construction. Silence the lints that only make sense for
+    // hand-written code, so this file never adds noise to a tenant's analyzer output (co2 feedback).
+    `// ignore_for_file: avoid_dynamic_calls, unnecessary_this, prefer_const_constructors, unused_import, type_annotate_public_apis, always_specify_types`,
+    `//`,
     `//   final bridge = NomosBridge(transport);   // transport = your WebViewTransport`,
     `//   await bridge.ready;`,
     `//   await bridge.connect(cloud: cloud, workspace: ws, clientId: deviceId);`,

package/src/codegen_proof.ts

@@ -656,6 +656,10 @@ export interface RelationBootstrapLeg {
    *  would trip the seed's owner-binding prerequisite (HomeOwner unset) and FALSE-fail. When present, the
    *  runner IGNORES the standalone grant fields and proves via {@link BornContextAuthority}. */
   readonly bornContext?: BornContextAuthority;
+  /** THE GATED-GRANTER CHAIN (co2: `grantCo2EstateCreator` itself `.requires("co2Admin")`): the granter's
+   *  OWN gate bootstrapped recursively — the runner seats THIS authority first (its prerequisite seeds +
+   *  its grant on the same actor), then the outer grant admits. Depth/cycle-guarded at discovery. */
+  readonly granterAuthority?: RelationBootstrapLeg;
   /** THE PREREQUISITE-SEED CHAIN (the composed co2_platform / `seedPlatformAdmin` case). Present iff the
    *  granter (`grantDirectiveId`) carries a PREREQUISITE invariant whose state is established NOT by a birth
    *  genesis but by a SIBLING SEED in the SAME domain (e.g. `seedPlatformAdmin`'s `PlatformAdminBindsFounder`
@@ -1186,7 +1190,7 @@ export function discoverPrerequisiteChain(mod: DomainModule, granter: Directive<
  *  granter, so granting B makes the actor satisfy R. `undefined` ⇒ no gated directive, or no granter for R
  *  or any of its bases (the caller may then fall through to the seed-path lane; the negative conformance
  *  leg always still runs). */
-export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstrapLeg | undefined {
+export function discoverRelationBootstrapLeg(mod: DomainModule, gatedOverride?: Directive<unknown>, _seen: ReadonlySet<string> = new Set()): RelationBootstrapLeg | undefined {
   const domain = mod.domain ?? mod.name;
   const directives = mod.directives as Directive<unknown>[];
   const isGatedProvable = (d: Directive<unknown> | undefined): boolean =>
@@ -1198,8 +1202,15 @@ export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstr
   // naive standalone-create leg (isStandaloneCreate), so the bootstrap leg is its ONLY positive proof — seed
   // authority, then prove the CREATE is admitted. When no gated create exists, fall back to any gated write
   // (a gated `.mutates`/`.ensures`), so an un-created gated law is still proven.
-  const gated = directives.find((d) => isGatedProvable(d) && d.marker === "creates")
-    ?? directives.find((d) => isGatedProvable(d));
+  // `gatedOverride` targets a SPECIFIC gated directive instead (the gated-`.births()` case — excluded from
+  // the default scan because a birth is proven by its OWN leg; the override reuses the same granter/seed
+  // discovery to SEAT the birth's required relation).
+  const gated = gatedOverride !== undefined && gatedOverride.requiresRelationGate !== undefined && typeof gatedOverride.payloadSchema === "object"
+    ? gatedOverride
+    : gatedOverride !== undefined
+      ? undefined
+      : (directives.find((d) => isGatedProvable(d) && d.marker === "creates")
+        ?? directives.find((d) => isGatedProvable(d)));
   if (gated === undefined) return undefined;
   const relation = gated.requiresRelationGate!.relation;
 
@@ -1313,6 +1324,18 @@ export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstr
   if (found === undefined) return undefined; // no granter at all → the caller emits the diagnostic
   const granter = found.granter;
 
+  // GATED GRANTER (co2: grantCo2EstateCreator itself .requires("co2Admin")): recursively bootstrap the
+  // granter's OWN gate so the runner seats that authority first. Cycle/depth-guarded via the seen-set; an
+  // unresolvable granter gate still emits the leg WITHOUT the chain (the runner's refusal names the gap —
+  // never silently weaker than before this lane existed).
+  let granterAuthority: RelationBootstrapLeg | undefined;
+  if (granter.requiresRelationGate !== undefined && !_seen.has(granter.id) && _seen.size < 4) {
+    granterAuthority = discoverRelationBootstrapLeg(mod, granter, new Set([..._seen, gated.id, granter.id]));
+    // a born-context result proves INSIDE a born workspace — not a seatable pre-grant; drop it (the
+    // runner's refusal then names the granter's unseatable gate).
+    if (granterAuthority?.bornContext !== undefined) granterAuthority = 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).
@@ -1343,6 +1366,7 @@ export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstr
     ...(seedSpeculative ? { seedSpeculative: true } : {}),
     ...(seedWritesRelations !== undefined ? { seedWritesRelations } : {}),
     ...(prerequisiteSeeds !== undefined ? { prerequisiteSeeds } : {}),
+    ...(granterAuthority !== undefined ? { granterAuthority } : {}),
   };
 }
 
@@ -1464,6 +1488,12 @@ export interface ChildBirthLeg {
    *  parent workspace (home → estate is the canonical case), the proof runner drives this setup birth first
    *  and then authors the child birth inside the born parent. */
   readonly parentSetup?: ChildBirthParentSetup;
+  /** RELATION SETUP for a GATED birth (`.births().requires(R)`) with NO parent-birth authority path: the
+   *  relation-bootstrap discovery (granter marker / inferred writeTuple / computed base / prerequisite-seed
+   *  chain) reused to SEAT R on the birth actor before the runner drives the birth offer — the law's own
+   *  granters, never a proof-only backdoor. Absent when `parentSetup` covers authority or no granter is
+   *  discoverable (the runner then reports the gate refusal with the discovery gap named). */
+  readonly relationSetup?: RelationBootstrapLeg;
   /** COMPILE-TIME RECIPE DIAGNOSTICS (births DX): problems found by statically validating each genesis
    *  step against the composed package (missing child module, unknown seed directive, payload-schema
    *  mismatch, a plan that returns a non-array — the exact things that otherwise surface at proof time as
@@ -2041,7 +2071,19 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
   // The child-birth legs (one per `.births()` directive) — discovered by running each plan. A parent
   // with SEVERAL births (co2: birthCatalogueWorkspace + birthEstateWorkspace) keeps EVERY leg; keeping
   // only the first left the other children compile-valid-only (unprovable through their birth).
-  const childBirths = allBirths.filter((b) => b.parentDomain === domain).map((b) => attachParentSetup(b, allBirths));
+  const childBirths = allBirths.filter((b) => b.parentDomain === domain).map((b) => {
+    const withParent = attachParentSetup(b, allBirths);
+    // A GATED birth with no parent-birth authority path: seat its relation via the SAME granter/seed
+    // discovery the relation-bootstrap leg uses (the law's own authority path, e.g. co2's
+    // seedPlatformFounder → seedPlatformAdmin → grantCo2EstateCreator → birthEstateWorkspace).
+    if (withParent.birthRequiresRelation !== undefined && withParent.parentSetup === undefined) {
+      const birthDir = (mod.directives as Directive<unknown>[]).find((d) => d?.id === b.birthDirectiveId);
+      const rb = birthDir !== undefined ? discoverRelationBootstrapLeg(mod, birthDir) : undefined;
+      // a born-context path proves INSIDE a born workspace — not a seatable pre-grant; leave it to the gap diagnostic.
+      if (rb !== undefined && rb.bornContext === undefined) return { ...withParent, relationSetup: rb };
+    }
+    return withParent;
+  });
   const childBirthWithSetup = childBirths[0];
 
   // The relation-bootstrap leg (when the domain has a `.requires(R)`-gated directive AND a discoverable

package/src/compile_package_main.ts

@@ -888,14 +888,26 @@ function emitDartPackages(
   }
 
   const declared = new Set<string>();
-  for (const src of typesSources.values()) for (const n of declaredDartTypeNames(src)) declared.add(n);
+  const declaredByFile = new Map<string, Set<string>>();
+  for (const [f, src] of typesSources) {
+    const ns = declaredDartTypeNames(src);
+    declaredByFile.set(f, ns);
+    for (const n of ns) declared.add(n);
+  }
+  // Only import files that actually CONTRIBUTE an alias target — an alias `typedef A = B` needs B in scope,
+  // but a file no alias references needs no import (the `export` re-exports it). Importing every file
+  // produced unused_import warnings in the tenant's barrel (co2 feedback).
+  const aliasTargets = new Set(Object.keys(names ?? {}));
+  const aliasImportUris = [...typesSources.keys()]
+    .filter((f) => [...(declaredByFile.get(f) ?? [])].some((n) => aliasTargets.has(n)))
+    .map((f) => `${genRel}/${f}.dart`);
   const typesBarrel = [
     "// GENERATED by nomos-compile — the TYPES package's public entrypoint. DO NOT EDIT.",
     "// Pure data: payload classes, read models, VOs/enums, typed read accessors over the",
     "// injected NomosReads seams. Frontend-safe — no bridge, no sessions, no lifecycle.",
     "library;",
     "",
-    ...aliasImportLines(names, [...typesSources.keys()].map((f) => `${genRel}/${f}.dart`)),
+    ...aliasImportLines(names, aliasImportUris),
     `export 'package:nomos_types/nomos_types.dart';`,
     ...[...typesSources.keys()].map((f) => `export '${genRel}/${f}.dart';`),
     ...dartAliasLines(names, declared),
@@ -2291,6 +2303,19 @@ async function main(): Promise<void> {
     }
   }
   console.log(`  deploy     ${rel(deployPath)}`);
+  if (compact) {
+    // COMPACT PACKAGES ride a base64 blob (nomos:usdJsonB64) — a peer needs the b64 decode arm
+    // (kernel ≥ the 2026-07-04 release; every current cloud/browser/node runtime has it). A NATIVE
+    // (iOS/macOS AOT) client pins its OWN kernel binary: if that xcframework predates the arm, install
+    // fails with `parse embedded USDA IR: domain package missing USDA field nomos:usdJsonHex`. Flag it
+    // so the tenant isn't surprised (the requested "flag compact when targeting native").
+    console.log(``);
+    console.log(`  ⚠ compact package (base64 blob): requires a kernel with the b64 decode arm (≥ 2026-07-04).`);
+    console.log(`    Current cloud/browser/node runtimes have it. A NATIVE client (nomos_flutter iOS/macOS)`);
+    console.log(`    pins its OWN kernel — refetch the current NomosKernel.xcframework (rm ios/Frameworks/`);
+    console.log(`    NomosKernel.xcframework && pod install), or set { compact: false } for a hex package that`);
+    console.log(`    parses on every kernel (larger deploy body; may need the signed-upload deploy lane).`);
+  }
   console.log(``);
   console.log(`deploy (Nomos Cloud):`);
   console.log(`  githolon login --agent && githolon ws create <ws> && githolon deploy <ws>   # no secret — deploy is OPEN, kernel-judged at the offer gate`);