@githolon/dsl 0.57.1 → 0.58.1

package/dart/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.37.1
+
+- Doc fix: `NomosBridge.attestedRead` docs now match the runtime — the call answers `{ entry: {queryId, result, attestation: …} }`; pass `result['entry']` as one `offerDirective` `attestations` element.
+
 ## 0.32.0
 
 - SPATIAL READS: `NomosBbox` + `NomosBridge.spatialWithin(spatialId, bbox)` + `watchSpatial(...)` — the R*Tree probe surfaces on the bridge; generated clients (tooling ≥0.46) emit typed `sitesByBounds({required NomosBbox bbox})` + watch accessors.

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/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.
@@ -1190,14 +1191,13 @@ class NomosBridge {
   /// ATTESTED READ — serve + SIGN a declared query over a COLOCATED source session's certified fold (the
   /// dynamic-source trust lane; architecture/dynamic_source_attested_reads.md). In a [NomosTestHarness.cluster]
   /// (one engine plane, many sessions) this fulfils the read IN-PROCESS from the [from] session and returns
-  /// the signed envelope `{ ok, rows, attestation:{ source_genesis, … } }` — hand it back as an
-  /// [offerDirective] `attestations` element, or read `attestation.source_genesis` to enrol the source in a
-  /// reader's allow-list. [args] are the query params. [session] is the caller/reader session (defaults to
-  /// this view's bound session).
+  /// `{ entry: {queryId, result, attestation:{source_genesis, public_key, …}} }` — pass `result['entry']`
+  /// (the whole entry map) as one [offerDirective] `attestations` element, or read
+  /// `entry['attestation']['source_genesis']` to enrol the source in a reader's allow-list. [args] are the
+  /// query params. [session] is the caller/reader session (defaults to this view's bound session).
   /// [attestorSecret] is the source's base64 read-attestor secret (from [authorKeygen]); when omitted the
   /// source session's connect-time `authorSecret` signs. [nowMs] stamps the freshness clock (defaults to the
-  /// source's own clock). The returned `entry` is `{queryId, result, attestation:{source_genesis, public_key,
-  /// …}}` — pass the whole `entry` as one [offerDirective] `attestations` element.
+  /// source's own clock).
   Future<Map<String, Object?>> attestedRead({
     required String from,
     required String queryId,

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.1
 
 environment:
   sdk: ^3.5.0

package/dart/test/cluster_births_test.dart

@@ -10,11 +10,14 @@
 //      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.
 //
-// THE NAMED GAP (task #42): opening the born child as a SIBLING SESSION (`bridge.session(child)` → typed
-// query) requires the SHARED ENGINE PLANE — today each runner session is its own single-workspace engine, so
-// a sibling session can't see the child custody born in another. We do NOT fake that loop; the child handle
-// is addressable, and we stop there.
+// (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;
 
@@ -93,8 +96,8 @@ void main() {
       expect(outcome.birthOutcomes.first['workspace'], outcome.born.single);
       expect(outcome.birthOutcomes.first['status'], isNotNull);
 
-      // NAMED GAP (#42): the child handle is addressable on the plane, but opening it as its own session
-      // across the runner's per-session engines needs the shared engine plane — we stop at the handle.
+      // 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();
@@ -121,6 +124,46 @@ void main() {
     }
   }, 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) {

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.1",
+  "version": "0.58.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_proof.ts

@@ -1499,6 +1499,21 @@ export function withBirthProbeGlobals<T>(run: () => T): T {
       for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 16777619) >>> 0; }
       return h.toString(16).padStart(8, "0").repeat(8);
     },
+    // A read STUB so a plan with a declared read()/read(…, {from}) PROBES cleanly instead of throwing
+    // "nomos.read is not provided" (which twin A would mis-report as a payload-dependent throw with an
+    // "add .reads(…)" hint — misleading for a correctly declared .readsFrom edge). Local reads answer no
+    // rows; foreign reads answer the {rows, attestation} wrapper the read() lane demands. The UNDECLARED
+    // read()/edge cases stay caught by their real gates (the compile lump-marker grep + attestedReadFindings).
+    read: (_q: string, _a: Record<string, string>, o?: { from?: string }) =>
+      o?.from !== undefined && o.from !== ""
+        ? {
+            rows: [],
+            attestation: {
+              source_genesis: "probe", source_head: "probe", source_epoch: 0,
+              attested_at_ms: 0, public_key: "", signature: "", result_hash: "",
+            },
+          }
+        : [],
   };
   // RELATION-NAMESPACING: a probed seed plan may build a relation OBJECT TOKEN (`selfWorkspace()`),
   // which qualifies its type by the dispatching domain. The proof generator's STATIC probe reads the

package/src/law_check.ts

@@ -379,6 +379,12 @@ function unreadPayloadFindings(domain: string, dir: Directive<unknown>, probe: P
   const objectFromField = (dir as { requiresRelationGate?: { objectFrom?: { idField?: string } } })
     .requiresRelationGate?.objectFrom?.idField;
   if (typeof objectFromField === "string") gateConsumed.add(objectFromField);
+  // A dynamic .readsFrom(fromPayload("<wsField>"), …) edge routes the foreign read by a payload field the
+  // ROUTING lane consumes (the plan may pass it straight to read(…, {from}) without a tracked property
+  // read on the sampled path) — a declared trust-edge field is never a dead field.
+  for (const e of (dir as { declaredForeignReads?: ForeignReadEdge[] }).declaredForeignReads ?? []) {
+    if ("fromPayload" in e && typeof e.fromPayload === "string") gateConsumed.add(e.fromPayload);
+  }
   const out: Finding[] = [];
   for (const f of requiredPayloadFields(dir.payloadSchema as z.ZodTypeAny)) {
     if (probe.readFields.has(f)) continue;