@githolon/dsl 0.55.1 → 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 {