@githolon/dsl 0.56.0 → 0.57.0

package/dart/lib/nomos_headless.dart

@@ -1,6 +1,11 @@
 /// The HEADLESS transport library — `dart:io` only, so it lives outside the main
 /// `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.
+/// Open workspaces and hold their [NomosSession] handles:
+///
 /// ```dart
 /// import 'package:nomos_client/nomos_client.dart';
 /// import 'package:nomos_client/nomos_headless.dart';
@@ -8,9 +13,19 @@
 /// final transport = await NodeRunnerTransport.start(resolveFrom: 'path/to/app');
 /// final bridge = NomosBridge(transport);
 /// await bridge.ready;
-/// await bridge.connect(cloud: ..., workspace: ..., clientId: 'test-runner');
+/// // open each workspace on the plane (local-only here — no `cloud` needed):
+/// await bridge.connect(workspace: 'home', session: 'home', restoreFrom: homeBytes);
+/// await bridge.connect(workspace: 'estate-42', session: 'estate-42', restoreFrom: estateBytes);
+/// // bind a generated client to a workspace via its session handle:
+/// final estate = EstateClient(bridge.session('estate-42'));
+/// final plane = await bridge.listWorkspaces(); // enumerate + sync posture
 /// ```
 ///
+/// The single-workspace `bridge.connect(...)` / `bridge.query(...)` methods are sugar over an inferred
+/// default session (unchanged). For TESTS, [NomosTestHarness] is a thin wrapper: `.ephemeral(...)` installs
+/// one law + opens one session; `.cluster(...)` installs N laws + opens N sessions on ONE plane — it adds
+/// no session logic of its own, it just drives the same production [NomosBridge.session] surface.
+///
 /// The runner child process is the SAME `@githolon/client` every peer runs; the
 /// generated Dart clients drive it through [NomosBridge] exactly as in the app.
 library;

package/dart/lib/src/test_harness.dart

@@ -34,7 +34,7 @@ import 'dart:convert';
 import 'dart:io';
 
 import 'node_runner_transport.dart';
-import 'webview_bridge.dart' show NomosBridge;
+import 'webview_bridge.dart' show NomosBridge, NomosSession;
 
 class NomosTestHarnessException implements Exception {
   final String message;
@@ -55,8 +55,50 @@ class NomosTestHarness {
   final void Function(String line)? _onDiagnostic;
   bool _disposed = false;
 
+  /// The workspace names this harness connected. For [ephemeral] this is the one [workspace]; for [cluster]
+  /// it is every workspace named in the call. Use [session] to get its handle.
+  final List<String> _sessionNames;
+
+  /// workspace → the base64 device PUBLIC key it was opened with (only for [cluster]'s `deviceKeyed` set).
+  final Map<String, String> _devicePublics;
+
+  /// The nomos framework controller's content hash from the offline install — the `frameworkHash` a
+  /// `.births()` genesis installs (not derivable client-side). Same for every workspace on the plane.
+  final String? frameworkHash;
+
+  /// workspace → the tenant law hashes installed into it (in deploy order); `lawHashes[ws].first` is that
+  /// package's domainHash — the `lawHash` a `.births()` recipe names for the child's law install.
+  final Map<String, List<String>> _lawHashes;
+
+  /// The tenant law hashes installed into [workspace] (deploy order); empty if unknown.
+  List<String> lawHashes(String workspace) =>
+      List.unmodifiable(_lawHashes[workspace] ?? const []);
+
   NomosTestHarness._(this.bridge, this.workspace, this._transport, this._workdir,
-      this._onDiagnostic);
+      this._onDiagnostic, this._sessionNames,
+      {Map<String, String> devicePublics = const {},
+      this.frameworkHash,
+      Map<String, List<String>> lawHashes = const {}})
+      : _devicePublics = devicePublics,
+        _lawHashes = lawHashes;
+
+  /// The base64 device PUBLIC key a `deviceKeyed` [cluster] session was opened with (null otherwise). Its
+  /// `sha256(base64decode(...))` is the attestor keyHash a reader enrols to trust this source's signed reads.
+  String? devicePublicKey(String workspace) => _devicePublics[workspace];
+
+  /// The workspace names on this device's local plane (one for [ephemeral], N for [cluster]).
+  List<String> get sessions => List.unmodifiable(_sessionNames);
+
+  /// A [NomosSession] handle pinned to one connected [workspace] — hand it to a generated typed client
+  /// (`EstateClient(harness.session('estate'))`). A THIN delegate to the production [NomosBridge.session]:
+  /// the harness owns no session logic, it just installs the laws + opens the sessions on the one plane.
+  NomosSession session(String workspace) {
+    if (!_sessionNames.contains(workspace)) {
+      throw NomosTestHarnessException(
+          'no session "$workspace" on this harness — connected sessions: $_sessionNames');
+    }
+    return bridge.session(workspace);
+  }
 
   /// Install [deployJsonPaths] into a fresh LOCAL workspace and boot a bridge over it — NO cloud contact.
   ///
@@ -114,7 +156,7 @@ class NomosTestHarness {
     NodeRunnerTransport? transport;
     try {
       final snapshot = '${workdir.path}/snapshot.bin';
-      await _runInstall(
+      final info = await _runInstall(
           node: node,
           useInRepoScript: useInRepoScript,
           inRepoScript: resolvedHelper,
@@ -147,8 +189,8 @@ class NomosTestHarness {
         clientId: clientId,
         allowUnborn: true,
       );
-      final harness =
-          NomosTestHarness._(bridge, workspace, transport, workdir, onDiagnostic);
+      final harness = NomosTestHarness._(
+          bridge, workspace, transport, workdir, onDiagnostic, [workspace]);
       if (autoTearDown && registerTearDown != null) {
         registerTearDown(harness.dispose);
       }
@@ -167,6 +209,139 @@ class NomosTestHarness {
     }
   }
 
+  /// A COLOCATED TEST CLUSTER — install MANY workspaces' law offline and connect one SESSION per workspace on
+  /// ONE engine plane (one runner, one transport, one [bridge]), so a cross-workspace scenario (attested
+  /// reads, foreign-source imports) runs in-process with ZERO network. Each workspace's law is installed via
+  /// the SAME offline lane [ephemeral] uses (one snapshot per workspace), then `connect`ed as its own session;
+  /// the per-connect restore snapshot loads it into the shared plane.
+  ///
+  /// [workspaces] — `{ workspaceName: [deployJsonPaths] }` (installed in order per workspace). Get a
+  /// session-scoped view with [session] and bind it to a generated client: `EstateClient(harness.session(
+  /// 'estate'))`. All other params mirror [ephemeral]. [clientId] is suffixed per session.
+  /// [deviceKeyed] names workspaces to open WITH a fresh in-kernel device key as their signing `authorSecret`
+  /// (the warrant default — every write is signed, replay-provably). Required for a source of ATTESTED READS:
+  /// the colocation resolver serves+signs a foreign read with the source session's device key, so a reader
+  /// enrols `sha256(that device public key)`. Get the public via [devicePublicKey].
+  static Future<NomosTestHarness> cluster({
+    required Map<String, List<String>> workspaces,
+    Set<String> deviceKeyed = const {},
+    String clientId = 'test-runner',
+    String? runtimeDir,
+    String? nodeEntry,
+    String? installHelper,
+    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),
+  }) async {
+    if (workspaces.isEmpty) {
+      throw NomosTestHarnessException(
+          'no workspaces — pass { workspaceName: [build/<name>.deploy.json] } for each colocated workspace');
+    }
+    for (final e in workspaces.entries) {
+      if (e.value.isEmpty) {
+        throw NomosTestHarnessException(
+            'workspace "${e.key}" has no deployJsonPaths — pass its build/<name>.deploy.json');
+      }
+    }
+    final entry = nodeEntry ??
+        await _resolveEntry(node, resolveFrom ?? Directory.current.path);
+    final resolvedHelper =
+        installHelper ?? '${File(entry).parent.path}/offline-install.mjs';
+    final useInRepoScript =
+        resolvedHelper.endsWith('.mjs') && File(resolvedHelper).existsSync();
+    final githolonCmd = installHelper == null ? 'npx githolon' : resolvedHelper;
+
+    final workdir = await Directory.systemTemp.createTemp('nomos-cluster-');
+    NodeRunnerTransport? transport;
+    try {
+      // 1. install each workspace's law offline → one snapshot per workspace (colocated, still separate law).
+      final snapshots = <String, String>{};
+      for (final e in workspaces.entries) {
+        final snap = '${workdir.path}/${e.key}.bin';
+        await _runInstall(
+            node: node,
+            useInRepoScript: useInRepoScript,
+            inRepoScript: resolvedHelper,
+            githolonCmd: githolonCmd,
+            deployJsonPaths: e.value,
+            workspace: e.key,
+            snapshot: snap,
+            runtimeDir: runtimeDir,
+            onDiagnostic: onDiagnostic);
+        snapshots[e.key] = snap;
+      }
+
+      // 2. ONE runner / ONE bridge for the whole plane — no env restore default; each connect brings its own.
+      transport = await NodeRunnerTransport.start(
+        entry: entry,
+        resolveFrom: resolveFrom,
+        node: node,
+        environment: {
+          'NOMOS_OFFLINE': '1',
+          if (runtimeDir != null) 'NOMOS_OFFLINE_RUNTIME': runtimeDir,
+        },
+        onDiagnostic: onDiagnostic,
+      );
+      final bridge = NomosBridge(transport);
+      await bridge.ready.timeout(readyTimeout,
+          onTimeout: () => throw NomosTestHarnessException(
+              'the offline runner never signalled ready within $readyTimeout '
+              '(is `node` on PATH and ~/.holon/runtime warm?)'));
+
+      // 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>{};
+      for (final e in workspaces.entries) {
+        snapshotB64[e.key] = base64Encode(await File(snapshots[e.key]!).readAsBytes());
+        await bridge.connect(
+          workspace: e.key,
+          session: e.key,
+          clientId: '$clientId-${e.key}',
+          restoreFrom: snapshotB64[e.key],
+          allowUnborn: true,
+        );
+      }
+
+      // 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.
+      final devicePublics = <String, String>{};
+      for (final ws in deviceKeyed) {
+        final kp = await bridge.session(ws).authorKeygen();
+        devicePublics[ws] = (kp['public'] ?? '').toString();
+        await bridge.connect(
+          workspace: ws,
+          session: ws,
+          clientId: '$clientId-$ws',
+          restoreFrom: snapshotB64[ws],
+          authorSecret: (kp['secret'] ?? '').toString(),
+          allowUnborn: true,
+        );
+      }
+
+      final names = workspaces.keys.toList();
+      final harness = NomosTestHarness._(
+          bridge, names.first, transport, workdir, onDiagnostic, names,
+          devicePublics);
+      if (autoTearDown && registerTearDown != null) {
+        registerTearDown(harness.dispose);
+      }
+      return harness;
+    } catch (_) {
+      if (transport != null) {
+        try {
+          await transport.dispose();
+        } catch (_) {}
+      }
+      try {
+        await workdir.delete(recursive: true);
+      } catch (_) {}
+      rethrow;
+    }
+  }
+
   /// Deterministic, idempotent, total-ordered teardown: stop the runner (SIGTERM → 5s deadline → SIGKILL,
   /// via [NodeRunnerTransport.dispose]), then delete the temp dir. Safe to call twice; safe to call after a
   /// failed setup. Nothing left running, nothing left on disk.
@@ -196,7 +371,7 @@ class NomosTestHarness {
 
   // ── offline install (a short-lived node child; produces the restore snapshot) ──
 
-  static Future<void> _runInstall({
+  static Future<Map<String, Object?>> _runInstall({
     required String node,
     required bool useInRepoScript,
     required String inRepoScript,
@@ -255,6 +430,9 @@ class NomosTestHarness {
       throw NomosTestHarnessException(
           'offline law install produced no snapshot (stdout: ${out.isEmpty ? "(empty)" : out})');
     }
+    // { ok, snapshot, workspace, lawHashes, frameworkHash } — the caller keeps lawHashes/frameworkHash so a
+    // `.births()` directive can be driven (its genesis installs the framework + law by hash).
+    return decoded;
   }
 
   static Future<String> _resolveEntry(String node, String from) async {

package/dart/lib/src/webview_bridge.dart

@@ -765,11 +765,26 @@ class NomosEncryption {
           openedAt: openedAt);
 }
 
-/// The result of [NomosBridge.offerCreates]: the new local [head] plus every aggregate the plan minted.
+/// The result of [NomosBridge.offerCreates]: the new local [head], every aggregate the plan minted, and —
+/// for a `.births()` directive — the child workspace(s) the offer brought into being on this local plane.
 class NomosOfferOutcome {
   final String head;
   final List<NomosCreated> created;
-  const NomosOfferOutcome({required this.head, required this.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.)
+  final List<String> born;
+
+  /// The raw per-child birth outcomes the holon reported (`{ workspace, genesisHead, … }`), when present.
+  final List<Map<String, Object?>> birthOutcomes;
+
+  const NomosOfferOutcome({
+    required this.head,
+    required this.created,
+    this.born = const [],
+    this.birthOutcomes = const [],
+  });
 }
 
 /// THE BRIDGE. Construct over a [BridgeTransport], `await ready`, then `connect(...)` and drive the holon.
@@ -805,6 +820,11 @@ class NomosBridge {
   SyncStatus _status = const SyncStatus();
   Timer? _metricsTimer;
   final Completer<void> _ready = Completer<void>();
+  // THE LOCAL PLANE'S WORKSPACES. A NomosBridge is a device's local holarchy plane; each connected
+  // workspace is a live session on it. [_sessionNames] tracks what [connect] has opened; [_sessionViews]
+  // caches the per-workspace [NomosSession] handle so `bridge.session(ws)` is stable + cheap.
+  final Set<String> _sessionNames = {};
+  final Map<String, NomosSession> _sessionViews = {};
   int _seq = 0;
   final String _traceId = _newTraceId();
   late final StreamSubscription<Map<String, Object?>> _sub;
@@ -813,6 +833,10 @@ class NomosBridge {
     _sub = _transport.messages.listen(_onMessage);
   }
 
+  /// A SESSION VIEW's super-constructor: shares the parent's [_transport] but does NOT subscribe (the parent
+  /// owns the one message loop + all correlation). Only [NomosSession] uses it.
+  NomosBridge._view(this._transport);
+
   static Random _traceRandom() {
     try {
       return Random.secure();
@@ -941,6 +965,7 @@ class NomosBridge {
 
   /// Send one request and await the typed reply (the runner answers ok/error). The ONLY low-level call —
   /// every typed method below is a thin wrapper, so the request/reply contract lives in exactly one place.
+  /// A [NomosSession] overrides this to stamp `args.session` and route through the parent's ONE transport.
   Future<Object?> _call(String op, [Map<String, Object?> args = const {}]) {
     final id = ++_seq;
     final completer = Completer<Object?>();
@@ -971,19 +996,50 @@ class NomosBridge {
 
   // ── the runtime-aware surface (the boundary the generated Dart client wraps) ──
 
-  /// Open the user/estate workspace: pull its ledger, boot the local holon under the installed law.
+  /// THE PRIMARY MULTI-WORKSPACE ENTRY. Return a [NomosSession] handle pinned to [workspace] — the object a
+  /// Flutter app holds one of per live workspace (home, each estate, each catalogue, …). The handle is
+  /// stable + cheap (cached) and can be created BEFORE the workspace is connected (lazy): construct it, hand
+  /// it to a generated client (`EstateClient(bridge.session('estate'))`), and `connect` the workspace when
+  /// ready — reads/writes flow once it is open. A device typically holds many: `bridge.session('home')`,
+  /// `bridge.session('estate-42')`, … all on ONE bridge/transport (this device's local plane).
+  NomosSession session(String workspace) =>
+      _sessionViews.putIfAbsent(workspace, () => NomosSession(this, workspace));
+
+  /// The workspace names [connect] has opened on this plane (the live sessions).
+  List<String> get connectedSessions => List.unmodifiable(_sessionNames);
+
+  /// ENUMERATE THE LOCAL PLANE — every workspace open on this device + its sync posture:
+  /// `[{ session, workspace, mounted, syncPosture: "local-only" | "cloud-bound" }]`. A local-only workspace
+  /// has no cloud counterpart (it was opened with no `cloud`); a cloud-bound one syncs per its own posture.
+  Future<List<Map<String, Object?>>> listWorkspaces() async =>
+      (((_asMap(await _call('listWorkspaces'))['workspaces']) as List?) ?? const [])
+          .map((e) => (e as Map).cast<String, Object?>())
+          .toList();
+
+  /// Open a workspace on this plane: boot its LOCAL githolon under the installed law (from [restoreFrom]
+  /// custody, or a cloud pull when [cloud] is given). This is the sugar the single-workspace path uses; a
+  /// multi-workspace app names a [session] per workspace and holds their [session] handles.
   Future<void> connect(
-      {required String cloud,
+      {String? cloud,
       required String workspace,
       String? clientId,
       String? authToken,
       String? authorSecret,
       String? restoreFrom,
       bool allowUnborn = false,
-      bool recover = false}) async {
+      bool recover = false,
+      String? session}) async {
+    final ws = session ?? workspace;
+    _sessionNames.add(ws);
     final r = _asMap(await _call('connect', {
-      'cloud': cloud,
+      // [cloud] is OPTIONAL — omit it to open a LOCAL-ONLY workspace (a local githolon with no cloud
+      // counterpart; the runner uses a `local://` sentinel and sync is a no-op). Pass it to make the
+      // workspace cloud-bound (per-workspace sync posture). A device's plane freely mixes both.
+      if (cloud != null) 'cloud': cloud,
       'workspace': workspace,
+      // MULTI-WORKSPACE: name the [session] this connect opens on this device's local plane (default =
+      // [workspace]). Omitted on the single-workspace sugar path (byte-identical wire to before).
+      if (session != null) 'session': session,
       if (clientId != null) 'clientId': clientId,
       if (authToken != null) 'authToken': authToken,
       // The device signing secret (base64, from [authorKeygen]) — the warrant default for every offer.
@@ -1015,12 +1071,20 @@ class NomosBridge {
   /// `encodeIntentOfferBytes`, with `security.actor` included iff [actor] is set). The generated Dart client
   /// calls THIS — it never hand-builds offer bytes, so there is exactly ONE copy of the wire format. Returns
   /// the new local head; durable on [sync]. ([offer] with opaque bytes stays for back-compat carriers.)
+  /// [attestations] hand-injects the signed foreign-read envelopes a captured-read directive consumes
+  /// (each `{queryId, result, attestation}` — the shape the kernel's attested-read gate re-derives against
+  /// its trust policy); [force] carries the deploy/evolve force flag through. Both are OMITTED from the wire
+  /// when absent, so a plain offer is byte-identical to before. [session] pins the colocated workspace in a
+  /// cluster harness (absent ⇒ the runner's sole-session default).
   Future<String> offerDirective({
     required String domain,
     required String directiveId,
     required Object? payload,
     String? actor,
     String? domainHash,
+    List<Map<String, Object?>>? attestations,
+    bool? force,
+    String? session,
   }) async {
     final r = _asMap(await _call('offerDirective', {
       'domain': domain,
@@ -1028,6 +1092,9 @@ class NomosBridge {
       'payload': payload,
       if (actor != null) 'actor': actor,
       if (domainHash != null) 'domainHash': domainHash,
+      if (attestations != null) 'attestations': attestations,
+      if (force != null) 'force': force,
+      if (session != null) 'session': session,
     }));
     return r['head'].toString();
   }
@@ -1042,6 +1109,9 @@ class NomosBridge {
     required Object? payload,
     String? actor,
     String? domainHash,
+    List<Map<String, Object?>>? attestations,
+    bool? force,
+    String? session,
   }) async {
     final r = _asMap(await _call('offerDirective', {
       'domain': domain,
@@ -1049,7 +1119,22 @@ class NomosBridge {
       'payload': payload,
       if (actor != null) 'actor': actor,
       if (domainHash != null) 'domainHash': domainHash,
+      if (attestations != null) 'attestations': attestations,
+      if (force != null) 'force': force,
+      if (session != null) 'session': session,
     }));
+    final births = ((r['birthOutcomes'] as List?) ?? const [])
+        .whereType<Map>()
+        .map((m) => m.cast<String, Object?>())
+        .toList();
+    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)
+        ...births
+            .map((m) => (m['workspace'] ?? '').toString())
+            .where((s) => s.isNotEmpty),
+    ];
     return NomosOfferOutcome(
       head: r['head'].toString(),
       created: ((r['created'] as List?) ?? const [])
@@ -1058,6 +1143,8 @@ class NomosBridge {
               type: (m['type'] ?? '').toString(),
               id: (m['id'] ?? '').toString()))
           .toList(),
+      born: bornNames,
+      birthOutcomes: births,
     );
   }
 
@@ -1082,13 +1169,47 @@ class NomosBridge {
     required Object? payload,
     String? actor,
     String? domainHash,
+    List<Map<String, Object?>>? attestations,
+    bool? force,
+    String? session,
   }) =>
       offerDirective(
           domain: domain,
           directiveId: directiveId,
           payload: payload,
           actor: actor,
-          domainHash: domainHash);
+          domainHash: domainHash,
+          attestations: attestations,
+          force: force,
+          session: session);
+
+  /// 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).
+  /// [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.
+  Future<Map<String, Object?>> attestedRead({
+    required String from,
+    required String queryId,
+    Map<String, Object?> args = const {},
+    String? attestorSecret,
+    int? nowMs,
+    String? session,
+  }) async =>
+      _asMap(await _call('attestedRead', {
+        'from': from,
+        'queryId': queryId,
+        'args': args,
+        if (attestorSecret != null) 'attestorSecret': attestorSecret,
+        if (nowMs != null) 'nowMs': nowMs,
+        if (session != null) 'session': session,
+      }));
 
   /// MAKE A WORKSPACE — the one-call tenant path. A child workspace under a platform/[parent] is a SIGNED
   /// control-plane offer; the holon seals `createWorkspace` (or [directiveId] `birthChild`) with the
@@ -1265,19 +1386,22 @@ class NomosBridge {
   Future<List<Map<String, dynamic>>> query(String queryId,
           [Map<String, Object?> params = const {},
           List<NomosScopeKey>? keys,
-          String? principal]) async =>
+          String? principal,
+          String? session]) async =>
       _asRows(await _call('query', {
         'queryId': queryId,
         'params': params,
         ...?_readAuthArgs(keys, principal),
+        if (session != null) 'session': session,
       }));
 
   /// A single aggregate by id (the by-id read). `keys`/`principal`: see [query].
   Future<List<Map<String, dynamic>>> queryById(String id,
-          [List<NomosScopeKey>? keys, String? principal]) async =>
+          [List<NomosScopeKey>? keys, String? principal, String? session]) async =>
       _asRows(await _call('queryById', {
         'id': id,
         ...?_readAuthArgs(keys, principal),
+        if (session != null) 'session': session,
       }));
 
   /// The read auth sidecar (private reads + E2E): `keys`/`principal` as top-level call args, or null when
@@ -1334,23 +1458,36 @@ class NomosBridge {
   /// THE SPATIAL READ: rows of the declared spatial index's of-type whose geometry
   /// intersects [bbox] — an R*Tree probe on the local projection, same row shape as [query].
   Future<List<Map<String, dynamic>>> spatialWithin(
-          String spatialId, NomosBbox bbox) async =>
-      _asRows(await _call(
-          'spatialWithin', {'spatialId': spatialId, 'bbox': bbox.toJson()}));
+          String spatialId, NomosBbox bbox,
+          [String? session]) async =>
+      _asRows(await _call('spatialWithin', {
+        'spatialId': spatialId,
+        'bbox': bbox.toJson(),
+        if (session != null) 'session': session,
+      }));
 
   /// A maintained O(1) count / sum.
-  Future<int> count(String countId, [String group = '']) async =>
-      ((_asMap(await _call('count', {'countId': countId, 'group': group}))[
-              'count']) as num)
+  Future<int> count(String countId, [String group = '', String? session]) async =>
+      ((_asMap(await _call('count', {
+        'countId': countId,
+        'group': group,
+        if (session != null) 'session': session,
+      }))['count']) as num)
           .toInt();
-  Future<int> sum(String sumId, [String group = '']) async =>
-      ((_asMap(await _call('sum', {'sumId': sumId, 'group': group}))['sum'])
-              as num)
+  Future<int> sum(String sumId, [String group = '', String? session]) async =>
+      ((_asMap(await _call('sum', {
+        'sumId': sumId,
+        'group': group,
+        if (session != null) 'session': session,
+      }))['sum']) as num)
           .toInt();
 
   /// Push local writes → the session branch → cloud admission, and pull canonical main back.
-  Future<Map<String, Object?>> sync({bool admit = true}) async =>
-      _asMap(await _call('sync', {'admit': admit}));
+  Future<Map<String, Object?>> sync({bool admit = true, String? session}) async =>
+      _asMap(await _call('sync', {
+        'admit': admit,
+        if (session != null) 'session': session,
+      }));
 
   /// PERSIST: a base64 snapshot of the whole local holon (the bare nomos.git incl. un-synced writes + the
   /// DLQ). Store it on disk and pass it back as `connect(restoreFrom:)` next launch — the app then boots from
@@ -1469,8 +1606,10 @@ class NomosBridge {
   }
 
   /// Ledger size (commits) + branch-vs-main (ahead) + projection bytes — the dashboard's slow state.
-  Future<Map<String, Object?>> metrics() async =>
-      _asMap(await _call('metrics'));
+  Future<Map<String, Object?>> metrics([String? session]) async =>
+      _asMap(await _call('metrics', {
+        if (session != null) 'session': session,
+      }));
 
   /// TIER-2 SYNC SIZE — how many bytes this workspace would transfer to catch up to main, WITHOUT downloading
   /// them (a HEAD on the serving pack; the host answers Content-Length only, cached ~15s). Sum across your open
@@ -1486,14 +1625,15 @@ class NomosBridge {
   /// Reactive local read: a stream of row-sets that re-emits on every local change. Cancelling the
   /// subscription tells the runner to drop the watch.
   Stream<List<dynamic>> watch(String queryId,
-          [Map<String, Object?> params = const {}]) =>
-      _watchStream(kind: 'query', queryId: queryId, params: params);
-  Stream<List<dynamic>> watchById(String id) =>
-      _watchStream(kind: 'byId', id: id);
+          [Map<String, Object?> params = const {}, String? session]) =>
+      _watchStream(kind: 'query', queryId: queryId, params: params, session: session);
+  Stream<List<dynamic>> watchById(String id, [String? session]) =>
+      _watchStream(kind: 'byId', id: id, session: session);
 
   /// Reactive SPATIAL read: re-emits the R*Tree probe's rows whenever they change locally.
-  Stream<List<dynamic>> watchSpatial(String spatialId, NomosBbox bbox) =>
-      _watchStream(kind: 'spatial', spatialId: spatialId, bbox: bbox);
+  Stream<List<dynamic>> watchSpatial(String spatialId, NomosBbox bbox,
+          [String? session]) =>
+      _watchStream(kind: 'spatial', spatialId: spatialId, bbox: bbox, session: session);
 
   /// SHAPE COMPATIBILITY (#72): one-shot verdict for this client's structural [requirement]
   /// (its baked `…InterfaceJson`, decoded) against the workspace's ON-LEDGER offer (auto-sourced).
@@ -1568,7 +1708,8 @@ class NomosBridge {
       Map<String, Object?>? params,
       String? id,
       String? spatialId,
-      NomosBbox? bbox}) {
+      NomosBbox? bbox,
+      String? session}) {
     final subId = 'w${++_seq}';
     late final StreamController<List<dynamic>> ctrl;
     ctrl = StreamController<List<dynamic>>(
@@ -1580,6 +1721,7 @@ class NomosBridge {
         if (id != null) 'id': id,
         if (spatialId != null) 'spatialId': spatialId,
         if (bbox != null) 'bbox': bbox.toJson(),
+        if (session != null) 'session': session,
       }),
       onCancel: () async {
         _watches.remove(subId);
@@ -1626,3 +1768,87 @@ class NomosBridge {
     if (!_syncStatusCtrl.isClosed) await _syncStatusCtrl.close();
   }
 }
+
+/// A LIVE WORKSPACE on a device's local plane — the FIRST-CLASS multi-workspace object. Everything about
+/// Nomos is multi-workspace: a running app holds ONE [NomosBridge] (this device's local holarchy plane) and
+/// MANY [NomosSession]s on it — the user's home, each estate, each catalogue, any locally-born child — a
+/// dozen or hundreds, interacting offline. Get one with `bridge.session('estate')` and hand it to a generated
+/// typed client: `EstateClient(bridge.session('estate'))`.
+///
+/// A session is a LOCAL githolon (the real byte-identical kernel + ledger + gate), NOT a cloud connection —
+/// cloud sync is an OPTIONAL per-workspace posture (a workspace opened with no `cloud` is local-only and
+/// never converges upstream). Its authority and truth are LOCAL; a hosted remote is replaceable custody.
+///
+/// Implementation: it EXTENDS [NomosBridge] (so it IS a `NomosBridge` wherever a generated client expects
+/// `final NomosBridge bridge;` — ZERO codegen change) but holds NO state of its own: it shares the [parent]
+/// plane's ONE transport, correlation, and watch streams, and overrides the sole low-level [_call] to stamp
+/// `args.session` and route through the parent — so request/reply, watches, and telemetry all resolve on the
+/// one message loop with no aliasing. The single-workspace [NomosBridge] methods are documented sugar over an
+/// inferred default session; a multi-workspace app works through session handles.
+class NomosSession extends NomosBridge {
+  /// The device's local plane every op routes through (the shared [NomosBridge]).
+  final NomosBridge parent;
+
+  /// The workspace name this session is pinned to.
+  final String workspace;
+
+  NomosSession(this.parent, this.workspace) : super._view(parent._transport);
+
+  /// Sibling workspaces resolve on the shared plane — delegate to the parent's registry (never nest a
+  /// session inside a session).
+  @override
+  NomosSession session(String workspace) => parent.session(workspace);
+
+  @override
+  Future<Object?> _call(String op, [Map<String, Object?> args = const {}]) =>
+      parent._call(op,
+          args.containsKey('session') ? args : {...args, 'session': workspace});
+
+  // The parent owns the ONE message loop + lifecycle; a session never subscribes, never signals ready of its
+  // own, and never tears the plane down (the harness owns `parent.dispose()`).
+  @override
+  Future<void> get ready => parent.ready;
+  @override
+  Future<void> dispose() async {}
+
+  // Reactive reads register on the PARENT (which listens) so watch events land — route with our session.
+  @override
+  Stream<List<dynamic>> watch(String queryId,
+          [Map<String, Object?> params = const {}, String? session]) =>
+      parent.watch(queryId, params, session ?? workspace);
+  @override
+  Stream<List<dynamic>> watchById(String id, [String? session]) =>
+      parent.watchById(id, session ?? workspace);
+  @override
+  Stream<List<dynamic>> watchSpatial(String spatialId, NomosBbox bbox,
+          [String? session]) =>
+      parent.watchSpatial(spatialId, bbox, session ?? workspace);
+  @override
+  Stream<Map<String, Object?>> watchCompatibility(
+          Map<String, Object?> requirement) =>
+      parent.watchCompatibility(requirement);
+
+  // Live snapshots / streams reflect the shared plane — read them off the parent's controllers.
+  @override
+  NomosCompat? get compat => parent.compat;
+  @override
+  Stream<NomosCompat> get onLawChanged => parent.onLawChanged;
+  @override
+  Map<String, Object?>? get lastRecovery => parent.lastRecovery;
+  @override
+  Stream<Map<String, Object?>> get syncEvents => parent.syncEvents;
+  @override
+  Stream<TransferProgress> get transferProgress => parent.transferProgress;
+  @override
+  Stream<SyncStatus> get syncStatus => parent.syncStatus;
+  @override
+  SyncStatus get currentStatus => parent.currentStatus;
+  @override
+  Stream<Map<String, Object?>> get signalEvents => parent.signalEvents;
+  @override
+  Stream<Map<String, Object?>> get flameEvents => parent.flameEvents;
+  @override
+  Stream<Map<String, Object?>> get spanEvents => parent.spanEvents;
+  @override
+  List<Map<String, Object?>> get recentSpans => parent.recentSpans;
+}

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

package/dart/test/cluster_attested_test.dart

@@ -0,0 +1,185 @@
+// THE CLUSTER / ATTESTED-READ ACCEPTANCE — DART LEG (co2's test-cluster ask). Prove the exact
+// dynamic-source attested-read scenario (architecture/dynamic_source_attested_reads.md) end-to-end from
+// Dart, ONE engine plane, TWO colocated workspaces, ZERO network:
+//
+//   • NomosTestHarness.cluster boots ONE runner holding a `catalogue` session (the source) and an `estate`
+//     session (the reader), each with its own law installed offline.
+//   • the catalogue session seeds a listing; the estate session serves + SIGNS it via the in-process
+//     `attestedRead` op (the colocated source lane) and reads the source's GENESIS off the envelope.
+//   • NEGATIVE arm: offering `importListing` with that envelope BEFORE enrolling the catalogue refuses
+//     `AttestedReadUntrustedSource` — surfaced to Dart as a NomosBridgeError carrying that name.
+//   • HAPPY arm: enrol the source genesis + attestor key, offer `importListing` carrying the signed
+//     envelope, and read the imported row back through the TYPED EstateClient bound to `harness.session
+//     ('estate')` — proving a NomosSession satisfies the generated client's `NomosBridge` constructor.
+@TestOn('vm')
+library;
+
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:crypto/crypto.dart';
+import 'package:nomos_client/nomos_client.dart' show NomosOfferOutcome;
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+// estate.client.dart re-exports estate.dart (payloads/read-models) AND the nomos_client symbols it needs
+// (NomosBridgeError, NomosBridge, …), so this one import carries the whole typed surface.
+import '../../../bench/scale/fixtures/catalogue-reader/build/dart/src/generated/estate.client.dart';
+
+String get _root => '${Directory.current.path}/../..';
+String get _repoEntry => '$_root/cloud/web-client/runner/node-entry.mjs';
+String get _catDeploy => '$_root/bench/scale/fixtures/catalogue-src/build/cat.deploy.json';
+String get _estateDeploy => '$_root/bench/scale/fixtures/catalogue-reader/build/estate.deploy.json';
+String get _estateClientDart =>
+    '$_root/bench/scale/fixtures/catalogue-reader/build/dart/src/generated/estate.client.dart';
+String get _runtimeDir => '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+
+String? _missingPrereq() {
+  if (!File(_repoEntry).existsSync()) return 'in-repo runner not found at $_repoEntry';
+  for (final p in [_catDeploy, _estateDeploy, _estateClientDart]) {
+    if (!File(p).existsSync()) {
+      return 'compile the catalogue fixtures with dart output: '
+          'cd bench/scale/fixtures/<catalogue-src|catalogue-reader> && node ../../../../dsl/compile_package.mjs '
+          '(needs `dart: { support: "package" }` in nomos.package.mjs) — missing $p';
+    }
+  }
+  if (!File('$_runtimeDir/holon.wasm').existsSync() ||
+      !File('$_runtimeDir/packages.json').existsSync()) {
+    return 'warm ~/.holon/runtime first (run any `githolon` command once)';
+  }
+  return null;
+}
+
+/// sha256hex of the attestor's raw public bytes — the `keyHash` the reader enrolls (parity with the
+/// smoke's `sha256hexBytes(base64decode(public))`).
+String _keyHashOf(String base64Public) =>
+    sha256.convert(base64Decode(base64Public)).toString();
+
+void main() {
+  test('cluster attested reads: colocated source served + signed → enrolled → typed import read back',
+      () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+
+    final harness = await NomosTestHarness.cluster(
+      workspaces: {
+        'catalogue': [_catDeploy],
+        'estate': [_estateDeploy],
+      },
+      // The catalogue SOURCE signs its attested reads with its device key — the colocation resolver uses it,
+      // and the reader enrols sha256(that public key). (The reader needs no device key: it authors as an actor.)
+      deviceKeyed: {'catalogue'},
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+    );
+    try {
+      expect(harness.sessions.toSet(), {'catalogue', 'estate'});
+
+      // THE PRODUCTION MULTI-WORKSPACE SURFACE: one bridge = this device's local plane; `bridge.session(ws)`
+      // is the first-class handle. Enumerate the plane — both workspaces are LOCAL-ONLY (no cloud posture).
+      final plane = await harness.bridge.listWorkspaces();
+      expect(plane.map((w) => w['workspace']).toSet(), {'catalogue', 'estate'});
+      expect(plane.every((w) => w['syncPosture'] == 'local-only'), isTrue,
+          reason: 'the cluster opens local githolons, not cloud connections');
+
+      // Get the session handles through the production entry (the harness delegates to bridge.session).
+      final catalogue = harness.bridge.session('catalogue');
+      final estate = harness.bridge.session('estate');
+      expect(identical(estate, harness.session('estate')), isTrue,
+          reason: 'session handles are stable + cached on the plane');
+
+      // 1. seed a listing in the CATALOGUE source (raw offer — the source's own law).
+      final seeded = await catalogue.offerCreates(
+        domain: 'cat',
+        directiveId: 'listCatalogue',
+        payload: {
+          'listingId': 'L-100',
+          'title': 'Oak dresser',
+          'priceGbp': '420',
+          'listedAt': '2026-07-03T00:00:00Z',
+        },
+        actor: 'user:seller',
+      );
+      expect(seeded.head, isNotEmpty);
+
+      // 2. Read the source's GENESIS (its true identity) + its signing key off ONE attested read. No attestor
+      //    secret: the source session signs with its DEVICE key (its connect authorSecret), which the
+      //    colocation resolver also uses — so the enrolled keyHash matches what the zero-injection lane signs.
+      final served = await estate.attestedRead(
+        from: 'catalogue',
+        queryId: 'listingById',
+        args: {'listingId': 'L-100'},
+      );
+      final entry = (served['entry'] as Map).cast<String, Object?>();
+      final attestation = (entry['attestation'] as Map).cast<String, Object?>();
+      final sourceGenesis = (attestation['source_genesis'] ?? '').toString();
+      final signingKey = (attestation['public_key'] ?? '').toString();
+      final keyHash = _keyHashOf(signingKey);
+      expect(sourceGenesis.length, greaterThanOrEqualTo(40),
+          reason: 'the source genesis oid resolves off the signed envelope');
+      expect(signingKey, harness.devicePublicKey('catalogue'),
+          reason: 'the read is signed by the source session device key the resolver will use');
+
+      // The one importListing offer, offered TWICE (unenrolled then enrolled). ZERO injection: the payload
+      // names `catalogueWs`, and the runner's colocation resolver serves+signs the foreign read IN-PROCESS —
+      // NO `attestations` param. The gate judges the served envelope's genesis against the reader's allow-list.
+      Future<NomosOfferOutcome> importOnce(String importedAt) => estate.offerCreates(
+            domain: 'estate',
+            directiveId: 'importListing',
+            payload: ImportListingPayload(
+              listingId: 'L-100',
+              catalogueWs: 'catalogue',
+              importedAt: importedAt,
+            ).toPayloadJson(),
+            actor: 'user:estate-owner',
+          );
+
+      // 3. NEGATIVE — BEFORE enrolment the source genesis is not in the allow-list → UntrustedSource
+      //    (the resolver still serves+signs; the gate refuses on the untrusted genesis).
+      Object? negError;
+      try {
+        await importOnce('2026-07-03T12:00:00Z');
+      } catch (e) {
+        negError = e;
+      }
+      expect(negError, isA<NomosBridgeError>(),
+          reason: 'an unenrolled source must refuse the import');
+      expect(negError.toString(), contains('AttestedReadUntrustedSource'),
+          reason: 'the typed refusal name must surface to Dart');
+
+      // 4. ENROL the catalogue: its genesis + the source device keyHash become folded law-state in the
+      //    reader's own chain (typed write — the reader's own directive, no attestation).
+      final app = EstateClient(estate, actor: 'user:estate-owner');
+      final enrolled = await app.enrollCatalogue(EnrollCataloguePayload(
+        sourceGenesis: sourceGenesis,
+        keyHashes: [keyHash],
+        label: 'Acme Catalogue',
+        enrolledAt: '2026-07-03T10:00:00Z',
+      ));
+      expect(enrolled.head, isNotEmpty);
+
+      // 5. HAPPY — the SAME zero-injection offer now admits: the resolver serves+signs, the gate judges the
+      //    genesis against the folded allow-list, and the catalogue title lands on EstateListing.
+      final imported = await importOnce('2026-07-03T12:05:00Z');
+      expect(imported.head, isNotEmpty);
+      expect(imported.created, isNotEmpty,
+          reason: 'the importListing plan minted the EstateListing');
+      final createdId = imported.created.first.id;
+
+      // 6. TYPED read-back through the EstateClient bound to the estate SESSION (by the minted id).
+      final rows = await app.estateListingById(createdId);
+      expect(rows, isNotEmpty,
+          reason: 'the imported EstateListing reads back on the estate session');
+      final row = rows.first;
+      expect(row.title, 'Oak dresser',
+          reason: 'the imported title was read through the policy edge, typed');
+      expect(row.catalogue, 'catalogue');
+      expect(row.listingRef, 'L-100');
+    } finally {
+      await harness.dispose();
+    }
+  }, timeout: const Timeout(Duration(minutes: 3)));
+}

package/dart/test/co2_acceptance_test.dart

@@ -10,7 +10,6 @@ import 'dart:io';
 import 'package:nomos_client/nomos_headless.dart';
 import 'package:test/test.dart';
 
-import '../../../bench/scale/fixtures/co2-acceptance/build/dart/src/generated/estate.dart';
 import '../../../bench/scale/fixtures/co2-acceptance/build/dart/src/generated/estate.client.dart';
 
 String get _root => '${Directory.current.path}/../..';

package/dart/test/vo_read_typing_test.dart

@@ -12,7 +12,6 @@ library;
 
 import 'dart:io';
 
-import 'package:nomos_client/nomos_client.dart';
 import 'package:nomos_client/nomos_headless.dart';
 import 'package:test/test.dart';
 

package/dart/test/webview_bridge_test.dart

@@ -239,6 +239,18 @@ Future<Object?> _invoke(
       return b.sync(admit: a['admit'] as bool);
     case 'lawStatus':
       return b.lawStatus(a['hash'] as String);
+    case 'offerDirective':
+      return b.offerDirective(
+        domain: a['domain'] as String,
+        directiveId: a['directiveId'] as String,
+        payload: a['payload'],
+        actor: a['actor'] as String?,
+        domainHash: a['domainHash'] as String?,
+        attestations: (a['attestations'] as List?)
+            ?.map((e) => (e as Map).cast<String, Object?>())
+            .toList(),
+        force: a['force'] as bool?,
+      );
     default:
       fail('corpus op not wired into the Dart bridge: $op');
   }
@@ -248,6 +260,7 @@ Future<Object?> _invoke(
 Object? _expectedTyped(String op, Map<String, Object?> result) {
   switch (op) {
     case 'offer':
+    case 'offerDirective':
       return result['head'];
     case 'query':
     case 'queryById':

package/package.json

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