@githolon/dsl 0.59.1 → 0.60.0

package/dart/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.39.0
+- `connect(maxMounted: …)` — the realm's mounted-workspace budget (LRU park/remount above it); useful on memory-constrained devices holding many local workspaces.
+- MULTI-WORKSPACE BY DEFAULT IN TESTS: `NomosTestHarness.ephemeral` now connects a DECOY session alongside the workspace under test, and `harness.bridge` is a `NomosSession` HANDLE pinned to it (existing tenant tests work unchanged). Sole-session inference therefore never silently passes under the harness — an op that forgot its session refuses in your first test with the same `multiple sessions connected — pass session` a real multi-workspace app raises. Opt out with `decoySession: false`.
+- `NomosBridge.open(...)` — connect + pinned `NomosSession` handle in one call (`final home = await bridge.open(workspace: …); HomeClient(home)`): the recommended plane/handle shape; the bare bridge methods remain one-workspace sugar.
+- Multi-session compat surface: `watchCompatibility` takes an optional `session`; `NomosSession` pins its compat watch, `compat`, and `onLawChanged` to ITS workspace (per-session `lawChanged` scoping — previously a multi-session plane's compat verdict was whichever session synced last, and a session's compat watch refused on a >1-session plane).
+
 ## 0.38.0
 - SPLIT: the pure data core (wire types, offer codec, NomosReads, aggregate meta, schema validation, error info) moved to the new `nomos_types` package; `nomos_client` depends on and re-exports it, so existing imports are unchanged. Frontend/UI code can now depend on `nomos_types` alone.
 

package/dart/lib/src/test_harness.dart

@@ -43,8 +43,15 @@ class NomosTestHarnessException implements Exception {
   String toString() => 'NomosTestHarnessException: $message';
 }
 
+/// The decoy session [NomosTestHarness.ephemeral] connects alongside the workspace under test — it exists
+/// so the plane is ALWAYS multi-session in tests (sole-session inference never silently passes).
+const String _decoyWorkspace = '__nomos-decoy';
+
 class NomosTestHarness {
   /// The connected bridge — hand it to the generated typed clients (the same surface the app UI uses).
+  /// For [ephemeral] this is a [NomosSession] HANDLE pinned to [workspace] (the plane underneath also
+  /// holds a decoy session, so unpinned plane-level calls refuse the way they would in a real
+  /// multi-workspace app); for [cluster] it is the shared plane — name sessions via [session].
   final NomosBridge bridge;
 
   /// The local workspace name the law was installed into.
@@ -129,6 +136,7 @@ class NomosTestHarness {
     void Function(Future<void> Function())? registerTearDown,
     void Function(String line)? onDiagnostic,
     Duration readyTimeout = const Duration(seconds: 30),
+    bool decoySession = true,
   }) async {
     if (deployJsonPaths.isEmpty) {
       throw NomosTestHarnessException(
@@ -178,19 +186,36 @@ class NomosTestHarness {
         },
         onDiagnostic: onDiagnostic,
       );
-      final bridge = NomosBridge(transport);
-      await bridge.ready.timeout(readyTimeout,
+      final plane = NomosBridge(transport);
+      await plane.ready.timeout(readyTimeout,
           onTimeout: () => throw NomosTestHarnessException(
               'the offline runner never signalled ready within $readyTimeout '
               '(is `node` on PATH and ~/.holon/runtime warm?)'));
-      await bridge.connect(
+      await plane.connect(
         cloud: 'https://offline.invalid', // ignored: the offline runner serves everything locally
         workspace: workspace,
         clientId: clientId,
         allowUnborn: true,
       );
+      // THE DECOY SESSION (multi-workspace by default in tests): sole-session inference is how
+      // single-workspace assumptions ship — with one session connected, an op that forgot its session
+      // silently works in tests and only refuses in production when the app connects its second
+      // workspace. The decoy keeps the plane at ≥2 sessions so any unpinned op refuses HERE, in the
+      // dev's first test. [bridge] is a SESSION HANDLE pinned to [workspace], so tenant code written
+      // against the harness keeps working unchanged; only code that grabs the raw plane and assumes
+      // single-session trips. Opt out with `decoySession: false` (please don't).
+      if (decoySession) {
+        await plane.connect(
+          cloud: 'https://offline.invalid',
+          workspace: _decoyWorkspace,
+          session: _decoyWorkspace,
+          clientId: '$clientId-decoy',
+          allowUnborn: true,
+          restoreFrom: base64Encode(await File(snapshot).readAsBytes()),
+        );
+      }
       final harness = NomosTestHarness._(
-          bridge, workspace, transport, workdir, onDiagnostic, [workspace],
+          plane.session(workspace), workspace, transport, workdir, onDiagnostic, [workspace],
           frameworkHash: info['frameworkHash']?.toString(),
           lawHashes: {
             workspace: ((info['lawHashes'] as List?) ?? const [])

package/dart/lib/src/webview_bridge.dart

@@ -626,6 +626,10 @@ class NomosBridge {
   final Map<String, StreamController<Map<String, Object?>>> _compatWatches = {};
   // COMPAT SUPERPOWER (#72b): the last computed verdict + the live `lawChanged` event stream.
   NomosCompat? _lastCompat;
+  // per-session compat state — a multi-session plane syncs law changes on MANY workspaces; a
+  // [NomosSession]'s compat/onLawChanged must answer for ITS workspace, not whichever synced last.
+  final Map<String, NomosCompat> _lastCompatBySession = {};
+  final Map<String, StreamController<NomosCompat>> _lawChangedBySession = {};
   final StreamController<NomosCompat> _lawChanged =
       StreamController<NomosCompat>.broadcast();
   final StreamController<Map<String, Object?>> _syncEvents =
@@ -728,7 +732,10 @@ class NomosBridge {
       final c = NomosCompat.fromJson((m['compat'] as Map?)?.cast<String, Object?>());
       if (c != null) {
         _lastCompat = c;
+        final sess = m['session'] as String?;
+        if (sess != null) _lastCompatBySession[sess] = c;
         if (!_lawChanged.isClosed) _lawChanged.add(c);
+        if (sess != null) _lawChangedBySession[sess]?.add(c);
       }
       return;
     }
@@ -856,7 +863,8 @@ class NomosBridge {
       String? restoreFrom,
       bool allowUnborn = false,
       bool recover = false,
-      String? session}) async {
+      String? session,
+      int? maxMounted}) async {
     final ws = session ?? workspace;
     _sessionNames.add(ws);
     final r = _asMap(await _call('connect', {
@@ -875,6 +883,8 @@ class NomosBridge {
       if (authorSecret != null) 'authorSecret': authorSecret,
       if (restoreFrom != null) 'restoreFrom': restoreFrom,
       if (allowUnborn) 'allowUnborn': true,
+      // the realm's mounted-workspace budget (LRU park/remount above it) — first connect wins.
+      if (maxMounted != null) 'maxMounted': maxMounted,
       // RECOVER-IN-PLACE over a corrupt restoreFrom snapshot: salvage local-only writes + DLQ, refold fresh
       // from cloud, re-offer the salvaged work. The report lands on [lastRecovery]. Nothing local is lost.
       if (recover) 'recover': true,
@@ -1494,6 +1504,33 @@ class NomosBridge {
     return v;
   }
 
+  /// CONNECT AS A HANDLE (the recommended multi-workspace shape): [connect] + a [NomosSession] pinned to
+  /// the opened session in one call — `final home = await bridge.open(workspace: 'home-…');` then
+  /// `HomeClient(home)`. The bare [NomosBridge] methods remain the ONE-workspace sugar over an inferred
+  /// default session; an app that opens a second workspace should hold handles, not call the plane.
+  Future<NomosSession> open(
+      {String? cloud,
+      required String workspace,
+      String? clientId,
+      String? authToken,
+      String? authorSecret,
+      String? restoreFrom,
+      bool allowUnborn = false,
+      bool recover = false,
+      String? session}) async {
+    await connect(
+        cloud: cloud,
+        workspace: workspace,
+        clientId: clientId,
+        authToken: authToken,
+        authorSecret: authorSecret,
+        restoreFrom: restoreFrom,
+        allowUnborn: allowUnborn,
+        recover: recover,
+        session: session);
+    return this.session(session ?? workspace);
+  }
+
   /// The last computed compat verdict (set by [checkCompat] / a `lawChanged` event). Null until bind.
   NomosCompat? get compat => _lastCompat;
 
@@ -1513,7 +1550,8 @@ class NomosBridge {
   /// workspace's installed law changes (another peer installs/upgrades/retires a domain and it
   /// syncs in). The verdict carries `offerKnown`. The app degrades/prompts on `ok:false`.
   Stream<Map<String, Object?>> watchCompatibility(
-      Map<String, Object?> requirement) {
+      Map<String, Object?> requirement,
+      [String? session]) {
     final subId = 'c${++_seq}';
     late final StreamController<Map<String, Object?>> ctrl;
     ctrl = StreamController<Map<String, Object?>>(
@@ -1521,6 +1559,7 @@ class NomosBridge {
         'subId': subId,
         'kind': 'compat',
         'requirement': requirement,
+        if (session != null) 'session': session,
       }),
       onCancel: () async {
         _compatWatches.remove(subId);
@@ -1656,14 +1695,20 @@ class NomosSession extends NomosBridge {
       parent.watchSpatial(spatialId, bbox, session ?? workspace);
   @override
   Stream<Map<String, Object?>> watchCompatibility(
-          Map<String, Object?> requirement) =>
-      parent.watchCompatibility(requirement);
+          Map<String, Object?> requirement,
+          [String? session]) =>
+      parent.watchCompatibility(requirement, session ?? workspace);
 
   // Live snapshots / streams reflect the shared plane — read them off the parent's controllers.
+  // compat/onLawChanged are LAW-scoped, so a session answers for ITS workspace (falling back to the
+  // plane-wide value when the runner's events carry no session key — older bundles).
   @override
-  NomosCompat? get compat => parent.compat;
+  NomosCompat? get compat =>
+      parent._lastCompatBySession[workspace] ?? parent.compat;
   @override
-  Stream<NomosCompat> get onLawChanged => parent.onLawChanged;
+  Stream<NomosCompat> get onLawChanged => (parent._lawChangedBySession[
+          workspace] ??=
+      StreamController<NomosCompat>.broadcast()).stream;
   @override
   Map<String, Object?>? get lastRecovery => parent.lastRecovery;
   @override

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

package/dart/test/test_harness_test.dart

@@ -11,6 +11,7 @@ library;
 
 import 'dart:io';
 
+import 'package:nomos_client/nomos_client.dart';
 import 'package:nomos_client/nomos_headless.dart';
 import 'package:test/test.dart';
 
@@ -82,6 +83,30 @@ void main() {
     stdout.writeln('offline harness green: ws=${harness.workspace}');
   }, timeout: const Timeout(Duration(minutes: 2)));
 
+  test('DECOY: the harness plane is multi-session — an unpinned plane op refuses like production', () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final harness = await NomosTestHarness.ephemeral(
+      deployJsonPaths: [_guestbookDeployJson],
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      registerTearDown: addTearDown,
+    );
+    // harness.bridge is a SESSION HANDLE — pinned ops work as before…
+    expect(harness.bridge, isA<NomosSession>());
+    expect(await harness.bridge.query('entriesByAuthor', {'author': 'x'}), isEmpty);
+    // …but the RAW PLANE holds the decoy too, so an op that forgot its session refuses HERE —
+    // exactly the refusal a real multi-workspace app would hit (never a silent sole-session guess).
+    final plane = (harness.bridge as NomosSession).parent;
+    await expectLater(
+      plane.query('entriesByAuthor', {'author': 'x'}),
+      throwsA(predicate((e) => '$e'.contains('multiple sessions'))),
+    );
+  }, timeout: const Timeout(Duration(minutes: 2)));
+
   test('OFFLINE: dispose is idempotent and removes the temp dir', () async {
     final skip = _missingPrereq();
     if (skip != null) {

package/package.json

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