@githolon/dsl 0.57.0 → 0.58.0

package/dart/lib/nomos_headless.dart

@@ -2,8 +2,15 @@
 /// `package:nomos_client/nomos_client.dart` barrel (which stays web-safe).
 ///
 /// MULTI-WORKSPACE BY DESIGN. A [NomosBridge] is a device's LOCAL HOLARCHY PLANE: one bridge / one
-/// transport, and MANY live workspaces on it (the home, each estate, each catalogue, locally-born children).
-/// Each workspace is a LOCAL githolon — cloud sync is an optional per-workspace posture, not a prerequisite.
+/// transport / ONE shared engine plane, and MANY live workspaces mounted on it (the home, each estate, each
+/// catalogue, locally-born children) — N workspaces on one wasm engine, not N engines. Each workspace is a
+/// LOCAL githolon — cloud sync is an optional per-workspace posture, not a prerequisite.
+///
+/// LOCAL BIRTHS OPEN IN-PLACE. A `.births()` directive offered into one workspace writes the child's custody
+/// straight into this same plane; the child is resident the moment it is born, so `bridge.connect(session:
+/// child)` (no `restoreFrom`) mounts it IN-PLACE — no re-clone — and reads/writes flow into the born child at
+/// once. (Proof: dsl/dart/test/cluster_births_test.dart; JS twin: cloud/web-client/test/realm.e2e.mjs.)
+///
 /// Open workspaces and hold their [NomosSession] handles:
 ///
 /// ```dart

package/dart/lib/src/test_harness.dart

@@ -190,7 +190,13 @@ class NomosTestHarness {
         allowUnborn: true,
       );
       final harness = NomosTestHarness._(
-          bridge, workspace, transport, workdir, onDiagnostic, [workspace]);
+          bridge, workspace, transport, workdir, onDiagnostic, [workspace],
+          frameworkHash: info['frameworkHash']?.toString(),
+          lawHashes: {
+            workspace: ((info['lawHashes'] as List?) ?? const [])
+                .map((e) => e.toString())
+                .toList()
+          });
       if (autoTearDown && registerTearDown != null) {
         registerTearDown(harness.dispose);
       }
@@ -259,9 +265,11 @@ class NomosTestHarness {
     try {
       // 1. install each workspace's law offline → one snapshot per workspace (colocated, still separate law).
       final snapshots = <String, String>{};
+      final lawHashesByWs = <String, List<String>>{};
+      String? frameworkHash;
       for (final e in workspaces.entries) {
         final snap = '${workdir.path}/${e.key}.bin';
-        await _runInstall(
+        final info = await _runInstall(
             node: node,
             useInRepoScript: useInRepoScript,
             inRepoScript: resolvedHelper,
@@ -272,6 +280,10 @@ class NomosTestHarness {
             runtimeDir: runtimeDir,
             onDiagnostic: onDiagnostic);
         snapshots[e.key] = snap;
+        lawHashesByWs[e.key] = ((info['lawHashes'] as List?) ?? const [])
+            .map((x) => x.toString())
+            .toList();
+        frameworkHash ??= info['frameworkHash']?.toString();
       }
 
       // 2. ONE runner / ONE bridge for the whole plane — no env restore default; each connect brings its own.
@@ -324,7 +336,9 @@ class NomosTestHarness {
       final names = workspaces.keys.toList();
       final harness = NomosTestHarness._(
           bridge, names.first, transport, workdir, onDiagnostic, names,
-          devicePublics);
+          devicePublics: devicePublics,
+          frameworkHash: frameworkHash,
+          lawHashes: lawHashesByWs);
       if (autoTearDown && registerTearDown != null) {
         registerTearDown(harness.dispose);
       }

package/dart/lib/src/webview_bridge.dart

@@ -772,8 +772,9 @@ class NomosOfferOutcome {
   final List<NomosCreated> created;
 
   /// The born child workspace name(s), when the offer ran a `.births()` directive (else empty). Each is a
-  /// LOCAL workspace on this device's plane; `bridge.session(name)` returns its handle. (Opening a born
-  /// child as its own live session across a colocated cluster is gated on the shared engine plane, #42.)
+  /// LOCAL workspace on this device's plane, resident in the shared engine plane the moment it is born:
+  /// `bridge.session(name)` returns its handle, and `bridge.connect(session: name)` (no `restoreFrom`) mounts
+  /// it IN-PLACE and opens it as a live sibling session — reads/writes flow into the child at once (#42).
   final List<String> born;
 
   /// The raw per-child birth outcomes the holon reported (`{ workspace, genesisHead, … }`), when present.
@@ -1127,14 +1128,18 @@ class NomosBridge {
         .whereType<Map>()
         .map((m) => m.cast<String, Object?>())
         .toList();
+    // `born` elements may be plain workspace-name strings OR `{workspace,…}` objects (both shapes ship);
+    // fall back to the birth outcomes' workspace names when no bare `born` list was sent.
+    final bornRaw = (r['born'] as List?);
     final bornNames = <String>[
-      ...((r['born'] as List?) ?? const []).map((e) => e.toString()),
-      // Fall back to the workspace field of each birth outcome when a bare `born` list wasn't sent.
-      if ((r['born'] as List?) == null)
+      if (bornRaw != null)
+        ...bornRaw.map((e) =>
+            (e is Map ? (e['workspace'] ?? '') : e).toString())
+      else
         ...births
             .map((m) => (m['workspace'] ?? '').toString())
             .where((s) => s.isNotEmpty),
-    ];
+    ]..removeWhere((s) => s.isEmpty);
     return NomosOfferOutcome(
       head: r['head'].toString(),
       created: ((r['created'] as List?) ?? const [])

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

package/dart/test/cluster_births_test.dart

@@ -0,0 +1,189 @@
+// LOCAL BIRTHS — DART LEG. An offline `.births()` directive dispatch: the estate-birth `home` law's
+// `birthEstateWorkspace` OFFERS a birth on THIS device's local plane — no cloud. Three things are proven:
+//
+//   1. THE DART API PATH: the offer surfaces the typed birth verdict — `born` (the child workspace name) +
+//      `birthOutcomes` (the per-child fate) — off NomosOfferOutcome. A birth is observable from Dart.
+//   2. THE OFFLINE BIRTH SUCCEEDS (status=born): the child genesis (installDomain×2 + seed) folds through the
+//      CHILD's own gate, fully offline. This needed a lane fix — the client holon's wasm provider now stages
+//      the stage-0 bootstrap package at the preopen root (`/work/domain.package.usda`), the SAME file the
+//      adapter engine stages, which `run_birth_effect` reads as the genesis-lane executor for the child's
+//      step-0 `bootstrap/installDomain`. Without it the birth failed with "bare JavaScript is not a domain
+//      package" (see cloud/web-client/src/kernel_provider_wasm.mjs boot).
+//   3. A FAILED birth carries a TYPED reason to Dart (deliberate bad framework hash) — never a silent drop.
+//   4. THE LOOP CLOSES (task #42): the born child OPENS as a sibling session on the SAME bridge and a typed
+//      query INSIDE it returns the genesis-seeded row. This is the whole point — a local birth is not just
+//      observable, it is USABLE: the child custody born in the parent session is resident in the shared
+//      engine plane, so `bridge.connect(session: born)` mounts it IN-PLACE (no re-clone) and reads its seed.
+//
+// (HISTORICAL: this leg was once a NAMED GAP — before the runner ran openRealm, each session was its own
+// single-workspace engine, so a sibling session could not see custody born in another. The shared engine
+// plane closed it; the JS twin of this proof is cloud/web-client/test/realm.e2e.mjs T2.)
+@TestOn('vm')
+library;
+
+import 'dart:io';
+
+import 'package:nomos_client/nomos_client.dart' show NomosOfferOutcome;
+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 _birthDeploy =>
+    '$_root/bench/scale/fixtures/estate-birth/build/estate-birth.deploy.json';
+String get _runtimeDir => '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+
+String? _missingPrereq() {
+  if (!File(_repoEntry).existsSync()) return 'in-repo runner not found at $_repoEntry';
+  if (!File(_birthDeploy).existsSync()) {
+    return 'compile the fixture: cd bench/scale/fixtures/estate-birth && node ../../../../dsl/compile_package.mjs — missing $_birthDeploy';
+  }
+  if (!File('$_runtimeDir/holon.wasm').existsSync() ||
+      !File('$_runtimeDir/packages.json').existsSync()) {
+    return 'warm ~/.holon/runtime first (run any `githolon` command once)';
+  }
+  return null;
+}
+
+const _owner = 'sample-owner';
+
+/// Set up a single-session plane over the estate-birth law + OFFER `birthEstateWorkspace` on it. Returns the
+/// harness (for teardown) + the offer outcome (born / birthOutcomes surfaced). [frameworkHash] overrides the
+/// real framework hash (pass a bogus one to force a genesis failure).
+Future<(NomosTestHarness, NomosOfferOutcome)> _birth({String? frameworkHash}) async {
+  final harness = await NomosTestHarness.ephemeral(
+    deployJsonPaths: [_birthDeploy],
+    nodeEntry: _repoEntry,
+    runtimeDir: _runtimeDir,
+    workspace: 'estate-birth',
+  );
+  // The genesis recipe installs the framework + child law BY HASH — the harness surfaces both (frameworkHash
+  // is not derivable client-side; lawHash is this package's own domainHash).
+  final fw = frameworkHash ?? harness.frameworkHash;
+  final lawHash = harness.lawHashes('estate-birth').first;
+  final outcome = await harness.bridge.offerCreates(
+    domain: 'home',
+    directiveId: 'birthEstateWorkspace',
+    payload: {
+      'owner': _owner,
+      'frameworkHash': fw,
+      'lawHash': lawHash,
+      'bornAt': '2026-07-05T00:00:00Z',
+    },
+    actor: _owner,
+  );
+  return (harness, outcome);
+}
+
+void main() {
+  test('offline .births() dispatch surfaces born + birthOutcomes TYPED to Dart', () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final (harness, outcome) = await _birth();
+    try {
+      expect(outcome.head, isNotEmpty,
+          reason: 'the birth offer admitted on the local plane');
+      // THE API PATH (co2's ask): the birth verdict is typed back to Dart.
+      expect(outcome.born, isNotEmpty,
+          reason: 'the offer-effect allocated the estate child workspace on the local plane');
+      expect(outcome.born.single, startsWith('estate-'),
+          reason: 'the born workspace is estate-<sha256(owner)>');
+      expect(outcome.birthOutcomes, isNotEmpty,
+          reason: 'the typed birth verdict rides beside born');
+      expect(outcome.birthOutcomes.first['workspace'], outcome.born.single);
+      expect(outcome.birthOutcomes.first['status'], isNotNull);
+
+      // The child handle is addressable on the plane (the loop that OPENS + reads it is the dedicated test
+      // below — 'born child OPENS as a sibling session ...').
+      expect(harness.bridge.session(outcome.born.single).workspace, outcome.born.single);
+    } finally {
+      await harness.dispose();
+    }
+  }, timeout: const Timeout(Duration(minutes: 3)));
+
+  test('offline birth genesis SUCCEEDS (status=born) — the child is folded through its own gate', () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final (harness, outcome) = await _birth();
+    try {
+      // The lane is fixed (the provider stages the stage-0 bootstrap package at the preopen root), so the
+      // child genesis folds clean and the born verdict is `born` — hard-asserted, no skip.
+      expect(outcome.born, hasLength(1));
+      expect(outcome.birthOutcomes, hasLength(1));
+      expect(outcome.birthOutcomes.first['status'], 'born',
+          reason: 'the child genesis (installDomain×2 + seed) folded through the child\'s own gate offline');
+      expect(outcome.birthOutcomes.first['workspace'], outcome.born.single);
+    } finally {
+      await harness.dispose();
+    }
+  }, timeout: const Timeout(Duration(minutes: 3)));
+
+  test('born child OPENS as a sibling session on the SAME bridge → typed query returns the seeded row (THE LOOP)',
+      () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final (harness, outcome) = await _birth();
+    try {
+      expect(outcome.birthOutcomes.first['status'], 'born',
+          reason: 'precondition: the child is born on the local plane');
+      final child = outcome.born.single;
+
+      // THE LOOP CLOSES: open the born child as its OWN session on the SAME bridge. No `restoreFrom` — the
+      // child custody is ALREADY resident in the shared engine plane (born in the parent session), so the
+      // runner mounts it IN-PLACE (openRealm.workspace(child)), no re-clone. This is exactly realm.e2e T2.
+      await harness.bridge.connect(workspace: child, session: child);
+
+      // A typed query INSIDE the born child returns its genesis-seeded row — the estate the child's genesis
+      // chain seeded via estate/seedEstateWorkspace, keyed on the owner (`estate-<sha256(owner)>` self-bound).
+      final rows = await harness.bridge.session(child).query('estatesByOwner', {'owner': _owner});
+      expect(rows, hasLength(1),
+          reason: 'the born child\'s genesis seed reads back through its OWN session (the loop is closed)');
+      expect(rows.first['data']?['owner'], _owner,
+          reason: 'the seeded EstateOwner belongs to the birth\'s owner');
+      expect(rows.first['data']?['estateName'], child,
+          reason: 'the estate self-committed its own workspace name (estate-<sha256(owner)>)');
+
+      // listWorkspaces now enumerates BOTH the parent and the newly-opened born child on the one plane.
+      final listed = await harness.bridge.listWorkspaces();
+      final sessions = listed.map((w) => w['session'].toString()).toSet();
+      expect(sessions, contains(child),
+          reason: 'listWorkspaces surfaces the born child as a live session');
+      expect(sessions, contains('estate-birth'),
+          reason: 'the parent workspace is still listed alongside its born child');
+    } finally {
+      await harness.dispose();
+    }
+  }, timeout: const Timeout(Duration(minutes: 3)));
+
+  test('birth FAILURE carries a typed reason to Dart (deliberate bad framework hash)', () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    // A well-formed but WRONG framework hash the parent does not fold → the child's step-0 install can't be
+    // satisfied → the genesis fold refuses. The offer still admits on the parent (the birth ORDER is valid);
+    // the child's fate comes back as a TYPED failure outcome, not a thrown error or a silent drop.
+    final badHash = 'deadbeef' * 8; // 64 hex chars, not a package the parent holds
+    final (harness, outcome) = await _birth(frameworkHash: badHash);
+    try {
+      expect(outcome.birthOutcomes, isNotEmpty,
+          reason: 'a failed birth still reports its typed verdict to Dart');
+      expect(outcome.birthOutcomes.first['status'], isNot('born'),
+          reason: 'an unresolvable framework hash cannot yield a born child');
+      expect((outcome.birthOutcomes.first['reason'] ?? '').toString(), isNotEmpty,
+          reason: 'the failure carries a human-legible reason (never a silent drop)');
+    } finally {
+      await harness.dispose();
+    }
+  }, timeout: const Timeout(Duration(minutes: 3)));
+}

package/dart/test/cluster_scale_test.dart

@@ -0,0 +1,117 @@
+// SCALE SANITY — DART LEG (task #42). "A device holds dozens of live workspaces" is a TESTED truth here,
+// not a slogan: one bridge / one runner / ONE shared engine plane mounts ~20 local-only workspaces, each with
+// the SAME tenant law installed offline (one compiled fixture's deploy.json, reused N times — same law, N
+// distinct workspaces), then writes + reads each in isolation and asserts `listWorkspaces` surfaces all 20.
+//
+// This is the colocation architecture the shared engine plane (openRealm) exists for: N workspaces on ONE
+// wasm engine, not N engines. The suite is deliberately DOZENS (CI-friendly), not hundreds — enough to pin
+// the "many live workspaces per device" claim while completing in sane wall-clock time (asserted below).
+@TestOn('vm')
+library;
+
+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 _guestbookDeploy => '$_root/examples/guestbook/build/guestbook.deploy.json';
+String get _runtimeDir => '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+
+/// How many colocated workspaces to open on the one plane. Dozens (CI-friendly), tunable via env for a
+/// heavier local soak (`NOMOS_SCALE_N=100 dart test test/cluster_scale_test.dart`).
+int get _n => int.tryParse(Platform.environment['NOMOS_SCALE_N'] ?? '') ?? 20;
+
+String? _missingPrereq() {
+  if (!File(_repoEntry).existsSync()) return 'in-repo runner not found at $_repoEntry';
+  if (!File(_guestbookDeploy).existsSync()) {
+    return 'compile the guestbook example: cd examples/guestbook && npx nomos-compile — missing $_guestbookDeploy';
+  }
+  if (!File('$_runtimeDir/holon.wasm').existsSync() ||
+      !File('$_runtimeDir/packages.json').existsSync()) {
+    return 'warm ~/.holon/runtime first (run any `githolon` command once)';
+  }
+  return null;
+}
+
+void main() {
+  test('a device holds dozens of live workspaces on ONE engine plane — write + read each, all listed',
+      () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+
+    final names = [for (var i = 0; i < _n; i++) 'ws-${i.toString().padLeft(2, '0')}'];
+    // Same law (one deploy.json), N distinct workspaces — the exact "one device, many workspaces" shape.
+    final workspaces = {for (final ws in names) ws: [_guestbookDeploy]};
+
+    final sw = Stopwatch()..start();
+    final harness = await NomosTestHarness.cluster(
+      workspaces: workspaces,
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      // Installing + mounting N workspaces takes longer than the single-session default; give it headroom.
+      readyTimeout: const Duration(seconds: 90),
+    );
+    final openMs = sw.elapsedMilliseconds;
+    try {
+      expect(harness.sessions.toSet(), names.toSet(),
+          reason: 'all $_n workspaces connected as sessions on the one bridge');
+
+      // WRITE one row into each workspace, keyed by its own name — so a cross-workspace read must come back
+      // EMPTY (isolation) and the own-workspace read must return exactly the one row (no bleed on the plane).
+      sw.reset();
+      for (final ws in names) {
+        await harness.session(ws).offerDirective(
+          domain: 'guestbook',
+          directiveId: 'signGuestbook',
+          payload: {
+            'author': ws,
+            'message': 'hello from $ws',
+            'mood': 'delighted',
+            'signedAt': '2026-07-05T00:00:00Z',
+          },
+          actor: ws,
+        );
+      }
+      final writeMs = sw.elapsedMilliseconds;
+
+      // READ each back — the own author returns its single row; a foreign author returns nothing (isolation).
+      sw.reset();
+      for (final ws in names) {
+        final own = await harness.session(ws).query('entriesByAuthor', {'author': ws});
+        expect(own, hasLength(1), reason: '$ws holds exactly its own 1 row');
+        expect(own.first['data']?['message'], 'hello from $ws');
+
+        final foreign = names.firstWhere((o) => o != ws);
+        final cross = await harness.session(ws).query('entriesByAuthor', {'author': foreign});
+        expect(cross, isEmpty, reason: '$ws does NOT see $foreign\'s data — per-workspace isolation');
+      }
+      final readMs = sw.elapsedMilliseconds;
+
+      // listWorkspaces enumerates the whole local plane — every one of the N is present + mounted.
+      final listed = await harness.bridge.listWorkspaces();
+      expect(listed.map((w) => w['session'].toString()).toSet(), names.toSet(),
+          reason: 'listWorkspaces surfaces all $_n live workspaces');
+      expect(listed.every((w) => w['mounted'] == true), isTrue,
+          reason: 'every listed workspace is mounted');
+
+      // Wall-clock sanity — dozens of live workspaces must open + drive in a CI-sane budget, not minutes.
+      // Generous ceilings (CI is slow); the point is "seconds per workspace is a bug", not a micro-benchmark.
+      // ignore: avoid_print
+      print('[scale] $_n workspaces: open+install ${openMs}ms, '
+          'write ${writeMs}ms (${(writeMs / _n).toStringAsFixed(1)}ms/ws), '
+          'read ${readMs}ms (${(readMs / _n).toStringAsFixed(1)}ms/ws)');
+      expect(writeMs, lessThan(_n * 5000),
+          reason: 'per-workspace write stays well under a 5s/ws ceiling (got ${(writeMs / _n).round()}ms/ws)');
+      expect(readMs, lessThan(_n * 5000),
+          reason: 'per-workspace read stays well under a 5s/ws ceiling (got ${(readMs / _n).round()}ms/ws)');
+    } finally {
+      await harness.dispose();
+    }
+    // The whole suite (open + install + write + read + teardown of N workspaces) completes in sane time.
+  }, timeout: const Timeout(Duration(minutes: 10)));
+}

package/package.json

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