@githolon/dsl 0.89.0 → 0.90.1

package/dart/lib/src/dev_cloud.dart

@@ -5,7 +5,7 @@
 //
 // ```dart
 // final cloud = await NomosTestCloud.start(serverEntry: devServerPath);   // spawns the dev cloud + proxy
-// final harness = await NomosTestHarness.cluster(cloud: cloud.origin, ...); // cloud-BOUND sessions
+// final harness = await NomosTestHarness.cloudBound(cloud: cloud, deployJsonPaths: [...], platformWorkspace: 'co2-platform', subject: 'user:test');
 // // ... author offline ...
 // cloud.setOnline(false);              // PARTITION — the up leg can't reach custody
 // await harness.session('estate').sync(admit: true);   // stays local; nothing lands remotely

package/dart/lib/src/test_harness.dart

@@ -33,6 +33,9 @@
 import 'dart:convert';
 import 'dart:io';
 
+import 'package:crypto/crypto.dart' show sha256;
+
+import 'dev_cloud.dart';
 import 'node_runner_transport.dart';
 import 'webview_bridge.dart' show NomosBridge, NomosSession;
 
@@ -147,6 +150,25 @@ class NomosTestHarness {
   /// When set, overrides EVERY phase's default deadline (see [HarnessPhaseTimeout]).
   final Duration? _phaseTimeout;
 
+  /// The test cloud a [cloudBound] harness runs against (null for the offline constructors). Partition it
+  /// with [NomosTestCloud.setOnline]; assert remote custody with [NomosTestCloud.remoteHead].
+  final NomosTestCloud? testCloud;
+
+  /// The HOME workspace a [cloudBound] harness mounted (born remotely by the platform ceremony). Null for
+  /// the offline constructors.
+  final String? homeWorkspace;
+
+  /// The mounted home as a [NomosSession] (the [cloudBound] app-shaped entry point — bind the generated
+  /// `HomeClient` to it). Throws for an offline harness (no home ceremony ran).
+  NomosSession get homeSession {
+    final ws = homeWorkspace;
+    if (ws == null) {
+      throw NomosTestHarnessException(
+          'homeSession is only available on a cloudBound harness (this one was built by ephemeral/cluster)');
+    }
+    return session(ws);
+  }
+
   NomosTestHarness._(this.bridge, this.workspace, this._transport, this._workdir,
       this._onDiagnostic, List<String> sessionNames,
       {Map<String, String> devicePublics = const {},
@@ -154,7 +176,9 @@ class NomosTestHarness {
       Map<String, List<String>> lawHashes = const {},
       Map<String, String> snapshots = const {},
       _InstallLane? installLane,
-      Duration? phaseTimeout})
+      Duration? phaseTimeout,
+      this.testCloud,
+      this.homeWorkspace})
       : _sessionNames = List.of(sessionNames), // GROWABLE — restoreWorkspace may add a fresh session
         _devicePublics = devicePublics,
         _lawHashes = Map.of(lawHashes),
@@ -613,6 +637,226 @@ class NomosTestHarness {
     }
   }
 
+  /// CLOUD-BOUND HARNESS (co2's real-app topology): a [NomosTestCloud] plays the remote control plane, the
+  /// REAL authenticated home-birth ceremony runs REMOTELY on [platformWorkspace], and the born home is
+  /// mounted into ONE local engine plane as a normal cloud-bound [NomosSession] ([homeSession]). From there
+  /// the app shape holds exactly: generated `.births()` directives run LOCALLY (the app never clones the
+  /// platform), children open as sibling sessions (`outcome.bornRefs.single.acquire(harness.bridge)`),
+  /// writes/projections work offline, and [converge] establishes remote custody parent-first when
+  /// connectivity returns ([NomosTestCloud.setOnline]). Entirely inside the test cloud's trust universe.
+  ///
+  /// ```dart
+  /// final cloud = await NomosTestCloud.start(serverEntry: devServer);
+  /// final h = await NomosTestHarness.cloudBound(
+  ///   cloud: cloud, deployJsonPaths: ['build/co2.deploy.json'],
+  ///   platformWorkspace: 'co2-platform', subject: 'user:test');
+  /// final home = h.homeSession;                    // the app's entry point
+  /// cloud.setOnline(false);                        // PARTITION
+  /// // ... local births + writes ...
+  /// cloud.setOnline(true);
+  /// await h.converge();                            // home first, then locally-born children
+  /// expect((await cloud.remoteHead(home.workspace)).initialized, isTrue);
+  /// ```
+  static Future<NomosTestHarness> cloudBound({
+    required NomosTestCloud cloud,
+    required List<String> deployJsonPaths,
+    String platformWorkspace = 'test-platform',
+    required String subject,
+    String? authToken,
+    String clientId = 'test-runner',
+    String? nodeEntry,
+    String? resolveFrom,
+    String node = 'node',
+    bool autoTearDown = true,
+    void Function(Future<void> Function())? registerTearDown,
+    void Function(String line)? onDiagnostic,
+    Duration readyTimeout = const Duration(seconds: 30),
+    Duration connectTimeout = const Duration(seconds: 120),
+    Duration? phaseTimeout,
+    bool decoySession = true,
+  }) async {
+    if (deployJsonPaths.isEmpty) {
+      throw NomosTestHarnessException(
+          'no deployJsonPaths — pass the build/<name>.deploy.json `npx githolon compile` emits');
+    }
+    final entry = nodeEntry ??
+        await _resolveEntry(node, resolveFrom ?? Directory.current.path);
+    final bareUid = subject.startsWith('user:') ? subject.substring(5) : subject;
+    final http = HttpClient();
+    Future<Map<String, Object?>> post(String path, Object? body,
+        {Map<String, String> headers = const {}}) async {
+      final req = await http.postUrl(Uri.parse('${cloud.origin}$path'));
+      req.headers.set('content-type', 'application/json');
+      req.headers.set('x-nomos-principal', bareUid);
+      if (authToken != null) req.headers.set('x-nomos-auth', authToken);
+      headers.forEach(req.headers.set);
+      if (body != null) req.add(utf8.encode(body is String ? body : jsonEncode(body)));
+      final resp = await req.close();
+      final text = await resp.transform(utf8.decoder).join();
+      final decoded = (jsonDecode(text) as Map).cast<String, Object?>();
+      if (resp.statusCode >= 300 || decoded['ok'] == false) {
+        throw NomosTestHarnessException(
+            'cloudBound setup: POST $path → ${resp.statusCode}: ${text.substring(0, text.length.clamp(0, 400))}');
+      }
+      return decoded;
+    }
+
+    final workdir = await Directory.systemTemp.createTemp('nomos-harness-');
+    NodeRunnerTransport? transport;
+    try {
+      // 1/5 — the remote control plane: create the platform workspace + deploy the law under the test
+      //       cloud's own trust universe (its K_root; nothing here touches production).
+      String? frameworkHash;
+      final lawHashes = <String>[];
+      await _phased(
+          phase: '1/5: create platform + deploy law on the test cloud',
+          workspace: platformWorkspace,
+          awaiting: 'POST /v2/workspaces + /domains',
+          timeout: phaseTimeout ?? _kInstallDeadline,
+          onDiagnostic: onDiagnostic,
+          run: () async {
+            final created = await post('/v2/workspaces/$platformWorkspace', null);
+            frameworkHash =
+                ((created['controller'] as Map?)?['domainHash'])?.toString();
+            for (final p in deployJsonPaths) {
+              final body = await File(p).readAsString();
+              await post('/v2/workspaces/$platformWorkspace/domains', body);
+              final summary = ((jsonDecode(body) as Map)['summary'] as Map?);
+              final h = summary?['domainHash']?.toString();
+              if (h != null && h.isNotEmpty) lawHashes.add(h);
+            }
+          });
+      if (frameworkHash == null || frameworkHash!.isEmpty) {
+        throw NomosTestHarnessException(
+            'cloudBound: the test cloud returned no controller.domainHash — cannot run the birth ceremony (frameworkHash unknown)');
+      }
+      if (lawHashes.isEmpty) {
+        throw NomosTestHarnessException(
+            'cloudBound: no deploy.json carried a summary.domainHash — cannot run the birth ceremony (lawHash unknown)');
+      }
+      // 2/5 — THE HOME CEREMONY, remotely: the platform's own gateway offer births the home (the ONE
+      //       control-plane contact; the app lane below never touches the platform again).
+      String? home;
+      await _phased(
+          phase: '2/5: remote home-birth ceremony',
+          workspace: platformWorkspace,
+          awaiting: 'POST /v2/workspaces/$platformWorkspace/birthHome',
+          timeout: phaseTimeout ?? _kInstallDeadline,
+          onDiagnostic: onDiagnostic,
+          run: () async {
+            final out = await post('/v2/workspaces/$platformWorkspace/birthHome', {
+              'owner': subject,
+              'frameworkHash': frameworkHash,
+              'lawHash': lawHashes.first,
+              'bornAt': DateTime.now().toUtc().toIso8601String(),
+            });
+            final born = (out['born'] as List?) ?? const [];
+            final bornNames = born.map((b) => (b as Map)['workspace']?.toString()).whereType<String>().where((w) => w.isNotEmpty).toList();
+            home = bornNames.isEmpty ? null : bornNames.first;
+            home ??= _homeNameOf(subject); // deterministic fallback (home-<sha256(subject)[..40]>)
+          });
+      // 3/5 — the LOCAL engine plane, CLOUD-BOUND (no offline env: the runner pulls the runtime + the
+      //       home's custody from the test cloud like a real device).
+      transport = await _phased(
+          phase: '3/5: spawn the node runner (cloud-bound)',
+          awaiting: 'Process.start($node)',
+          timeout: phaseTimeout ?? _kSpawnDeadline,
+          onDiagnostic: onDiagnostic,
+          run: () => NodeRunnerTransport.start(
+              entry: entry, resolveFrom: resolveFrom, node: node, onDiagnostic: onDiagnostic));
+      final plane = NomosBridge(transport!);
+      await _phased(
+          phase: '4/5: runner ready',
+          awaiting: "event:'ready'",
+          timeout: phaseTimeout ?? readyTimeout,
+          onDiagnostic: onDiagnostic,
+          run: () => plane.ready);
+      // 5/5 — mount the born home as a normal cloud-bound session (clone from the test cloud).
+      await _phased(
+          phase: '5/5: mount the born home',
+          workspace: home,
+          awaiting: 'connect(cloud:, workspace: $home)',
+          timeout: phaseTimeout ?? connectTimeout,
+          onDiagnostic: onDiagnostic,
+          run: () => plane.connect(
+                cloud: cloud.origin,
+                workspace: home!,
+                clientId: clientId,
+                authToken: authToken,
+              ));
+      // NO DECOY on a cloudBound harness: the app is genuinely multi-workspace (the home plus every
+      // locally-born child), so the plane is never sole-session — the decoy the offline  harness
+      // needs (to break single-session inference) would just be a spurious local-only workspace here.
+      final _ = decoySession; // (accepted for signature parity; a cloudBound plane needs no decoy)
+      final harness = NomosTestHarness._(
+        plane.session(home!),
+        home!,
+        transport,
+        workdir,
+        onDiagnostic,
+        [home!],
+        frameworkHash: frameworkHash,
+        lawHashes: {home!: lawHashes},
+        phaseTimeout: phaseTimeout,
+        testCloud: cloud,
+        homeWorkspace: home,
+      );
+      if (autoTearDown && registerTearDown != null) {
+        registerTearDown(() => harness.dispose());
+      }
+      return harness;
+    } catch (e) {
+      try { transport?.dispose(); } catch (_) {}
+      try { await workdir.delete(recursive: true); } catch (_) {}
+      rethrow;
+    } finally {
+      http.close(force: true);
+    }
+  }
+
+  /// The framework home-slot derivation (`home-<sha256(subject)[0..40]>`) — the fallback when the birth
+  /// offer response carries no `born` surface (an older dev cloud).
+  static String _homeNameOf(String subject) =>
+      'home-${sha256.convert(utf8.encode(subject)).toString().substring(0, 40)}';
+
+  /// CONVERGE local custody with the test cloud (co2 topology step 8): sync every connected session —
+  /// PARENT-FIRST by connect order, so the home's chain lands remotely and its birth offer-effects create
+  /// each locally-born child's remote custody BEFORE that child's own sync converges against it. Repeats
+  /// until every session reports neither `pushFailed` nor `stillAhead`, or [timeout] (then throws with the
+  /// per-workspace last verdicts). Returns the final sync result per workspace.
+  Future<Map<String, Map<String, Object?>>> converge(
+      {Duration timeout = const Duration(seconds: 120), List<String>? workspaces}) async {
+    // Every LIVE session on the plane (not the harness's construction-time list — a locally-born child
+    // acquired after construction must converge too), PARENT-FIRST: the home syncs before its children, so
+    // its birth offer-effect creates each child's remote custody BEFORE that child pushes its own writes.
+    final live = bridge.connectedSessions.where((w) => w != _decoyWorkspace).toList();
+    final hw = homeWorkspace;
+    if (hw != null && live.remove(hw)) live.insert(0, hw); // the parent leads
+    final targets = workspaces ?? live;
+    final last = <String, Map<String, Object?>>{};
+    final pending = List.of(targets);
+    final deadline = DateTime.now().add(timeout);
+    while (pending.isNotEmpty) {
+      for (final ws in List.of(pending)) {
+        try {
+          final r = (await bridge.session(ws).sync(admit: true)).cast<String, Object?>();
+          last[ws] = r;
+          if (r['pushFailed'] != true && r['stillAhead'] != true) pending.remove(ws);
+        } catch (e) {
+          last[ws] = {'error': e.toString()};
+        }
+      }
+      if (pending.isEmpty) break;
+      if (DateTime.now().isAfter(deadline)) {
+        throw NomosTestHarnessException(
+            'converge: ${pending.length} workspace(s) did not converge within ${timeout.inSeconds}s — '
+            '${pending.map((w) => '$w: ${jsonEncode(last[w] ?? {})}').join('; ')}');
+      }
+      await Future<void>.delayed(const Duration(milliseconds: 500));
+    }
+    return last;
+  }
+
   // ── CUSTODY DIAGNOSTIC HELPERS (architecture/session_bound_clients.md ask 9) ──
 
   /// The raw multi-workspace plane under [bridge] (the session handle a single-workspace harness

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

package/dart/test/cloud_bound_topology_test.dart

@@ -0,0 +1,140 @@
+// THE CLOUD-BOUND TOPOLOGY ACCEPTANCE (co2's exact 10-step ask) — the real-app shape end-to-end:
+//
+//   1. the remote platform births the home (the ONE control-plane contact — the authenticated ceremony);
+//   2. the app mounts the home locally (a normal cloud-bound NomosSession; co2-platform is never cloned);
+//   3. the network PARTITIONS (NomosTestCloud.setOnline(false));
+//   4. the home births the estate LOCALLY (`birthEstateWorkspace` — a `.births()` offer on this device);
+//   5. the estate opens as a sibling session and ACCEPTS LOCAL WRITES while offline;
+//   6. UI-facing queries return those writes immediately (no sync awaited, ever);
+//   7. the network HEALS;
+//   8. `harness.converge()` establishes remote custody PARENT-FIRST (the home's synced chain folds the
+//      birth offer-effect remotely, creating the estate's custody; then the estate converges against it);
+//   9. a FRESH observer (the dev cloud's own remote projection) sees the estate writes;
+//  10. custody is REAL on both: remote heads born with commits (the dev cloud adopted the chains through
+//      the same gate everything else uses — replay IS validation).
+//
+// Entirely inside the test cloud's trust universe: nothing here touches production K_root or custody.
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+String get _root => '${Directory.current.path}/../..';
+String get _repoEntry => '$_root/cloud/web-client/runner/node-entry.mjs';
+String get _devServer => '$_root/cloud/dev-server/server.mjs';
+String get _deploy =>
+    '$_root/bench/scale/fixtures/cloud-topology/build/cloud-topology.deploy.json';
+const _subject = 'user:topology-test';
+
+String? _missingPrereq() {
+  if (!File(_repoEntry).existsSync()) return 'in-repo runner not found at $_repoEntry';
+  if (!File(_devServer).existsSync()) return 'in-repo dev server not found at $_devServer';
+  if (!File(_deploy).existsSync()) {
+    return 'compile the fixture: cd bench/scale/fixtures/cloud-topology && node ../../../../dsl/compile_package.mjs — missing $_deploy';
+  }
+  return null;
+}
+
+void main() {
+  test('the co2 topology: remote home ceremony → local estate birth offline → converge → remote custody',
+      () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final diag = Platform.environment['NOMOS_HARNESS_DIAG'] == '1'
+        ? (String l) => stderr.writeln(l)
+        : null;
+    final cloud = await NomosTestCloud.start(serverEntry: _devServer, onDiagnostic: diag);
+    NomosTestHarness? harness;
+    try {
+      // 1+2 — the remote ceremony + the local mount, in one constructor (the app's boot path).
+      harness = await NomosTestHarness.cloudBound(
+        cloud: cloud,
+        deployJsonPaths: [_deploy],
+        platformWorkspace: 'topology-platform',
+        subject: _subject,
+        nodeEntry: _repoEntry,
+        onDiagnostic: diag,
+      );
+      final home = harness.homeSession;
+      expect(home.workspace, startsWith('home-'),
+          reason: 'the remote ceremony born the deterministic home slot');
+      final remoteHome = await cloud.remoteHead(home.workspace);
+      expect(remoteHome.initialized, isTrue,
+          reason: 'the home was born REMOTELY (custody exists before the app ever mounted it)');
+
+      // 3 — PARTITION.
+      cloud.setOnline(false);
+
+      // 4 — the home births the estate LOCALLY (the app lane never needs the network).
+      final outcome = await harness.bridge.session(home.workspace).offerCreates(
+        domain: 'home',
+        directiveId: 'birthEstateWorkspace',
+        payload: {
+          'owner': _subject,
+          'frameworkHash': harness.frameworkHash,
+          'lawHash': harness.lawHashes(home.workspace).first,
+          'bornAt': '2026-07-14T00:00:00Z',
+        },
+        actor: _subject,
+      );
+      expect(outcome.born, isNotEmpty, reason: 'the local .births() offer spawned the estate');
+      final estateWs = outcome.born.single;
+      expect(estateWs, startsWith('estate-'));
+
+      // 5 — the estate opens as a sibling session and accepts a LOCAL WRITE while offline.
+      final estate = await harness.bridge.acquireSession(estateWs);
+      await estate.offerCreates(
+        domain: 'estate',
+        directiveId: 'writeEstateNote',
+        payload: {'author': _subject, 'body': 'written offline', 'writtenAt': '2026-07-14T00:00:01Z'},
+        actor: _subject,
+      );
+
+      // 6 — the UI-facing query returns the write IMMEDIATELY (local projection; nothing awaited sync).
+      final localRows = await estate.query('notesByAuthor', {'author': _subject});
+      expect(localRows, hasLength(1));
+      expect((localRows.single['data'] as Map)['body'], 'written offline');
+
+      // …and the estate has NO remote custody yet — the partition is real.
+      final remoteEstateOffline = await cloud.remoteHead(estateWs);
+      expect(remoteEstateOffline.initialized, isFalse,
+          reason: 'while partitioned, the locally-born estate must have NO remote custody');
+
+      // 7+8 — HEAL, then converge parent-first (home's chain lands; its birth offer-effect creates the
+      // estate's remote custody; the estate then converges against it).
+      cloud.setOnline(true);
+      await harness.converge(timeout: const Duration(seconds: 180));
+
+      // 9 — a FRESH observer: the dev cloud's own remote projection serves the estate write.
+      final http = HttpClient();
+      try {
+        final req = await http.getUrl(Uri.parse(
+            '${cloud.origin}/v2/workspaces/$estateWs/notesByAuthor?author=${Uri.encodeQueryComponent(_subject)}'));
+        final resp = await req.close();
+        final body = jsonDecode(await resp.transform(utf8.decoder).join());
+        final rows = ((body as Map)['rows'] as List?) ?? const [];
+        expect(rows, hasLength(1),
+            reason: 'the remote projection (a fresh observer) serves the offline-written note after converge');
+        expect(((rows.single as Map)['data'] as Map)['body'], 'written offline');
+      } finally {
+        http.close(force: true);
+      }
+
+      // 10 — custody is REAL on both (the dev cloud adopted the chains through the one gate).
+      final remoteHome2 = await cloud.remoteHead(home.workspace);
+      final remoteEstate2 = await cloud.remoteHead(estateWs);
+      expect(remoteHome2.initialized, isTrue);
+      expect(remoteHome2.commits, greaterThan(0));
+      expect(remoteEstate2.initialized, isTrue,
+          reason: 'converge established the estate\'s remote custody (parent birth folded remotely)');
+      expect(remoteEstate2.commits, greaterThan(0));
+    } finally {
+      try { await harness?.dispose(); } catch (_) {}
+      await cloud.stop();
+    }
+  }, timeout: const Timeout(Duration(minutes: 6)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.89.0",
+  "version": "0.90.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/compile_package_main.ts

@@ -1050,7 +1050,7 @@ const NOMOS_TYPES_DEP = "^0.4.1";
 // 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
-const NOMOS_CLIENT_DEP = "^0.56.0";
+const NOMOS_CLIENT_DEP = "^0.57.0";
 // DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in dsl/dart/pubspec.yaml
 // and dsl/dart_types/pubspec.yaml — a Dart release without this bump fails the suite, so tenants never
 // land back in dependency_overrides (the exact co2 report this closes, third occurrence).
@@ -2777,7 +2777,11 @@ async function main(): Promise<void> {
           unresolved = `${path.relative(process.cwd(), pkg)}: ${`${err.stdout ?? ""}${err.stderr ?? ""}`.trim().split("\n").slice(-3).join(" ")}`;
         }
       }
-      if (!dartMissing && inPackage.length > 0) {
+      // Only analyze when EVERY package's deps resolved: `dart analyze` against an unresolved package reports
+      // every framework symbol (NomosRef, …) as undefined — a meaningless flood, not a real defect. An
+      // unresolved dep is already surfaced as UNVERIFIED below (e.g. a fixture pinning an as-yet-unpublished
+      // nomos_client — it verifies for real the moment that version lands).
+      if (!dartMissing && unresolved === undefined && inPackage.length > 0) {
         try {
           execFileSync("dart", ["analyze", "--no-fatal-warnings", ...inPackage], { stdio: "pipe", encoding: "utf8" });
         } catch (e) {