@githolon/dsl 0.72.1 → 0.73.0

package/dart/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 0.49.0
+
+- **Fix: local-only `autoSync()` deadlocked the multi-workspace plane.** A `local://` session's
+  autoSync registered the full cloud machinery (doorbell WebSocket retry loop, fallback timers,
+  intent-offer POSTs that could never land) — the future never completed, the runner dispatcher
+  starved, sibling queries and `listWorkspaces()` hung, and teardown wedged. `autoSync()` on a
+  local-only session now registers nothing and returns immediately; `sync()` is a true no-op
+  (`localOnly: true` summary); a local:// holon performs ZERO network attempts. (co2's acceptance
+  test implemented verbatim; failed before, passes after.)
+- **New: `acquireSession(workspace, {ifAbsentCredentials})`** — atomic single-flight session
+  acquisition: reuses a connected session, joins an in-flight open (concurrent calls yield the
+  same handle, one connect), opens local-only for workspaces the plane already knows
+  (mounted/parked/resident custody — credentials never invoked), and only calls
+  `ifAbsentCredentials` (exactly once) when a genuine cloud open is required.
+
 ## 0.48.1
 
 - **Fix: `NomosSession.watchPendingConflicts()` never emitted.** The session overrode every other

package/dart/lib/src/webview_bridge.dart

@@ -661,6 +661,34 @@ class NomosOfferOutcome {
       .toList();
 }
 
+/// What a GENUINE cloud open needs — returned by an [NomosBridge.acquireSession] `ifAbsentCredentials`
+/// callback, invoked ONLY when the workspace is nowhere on the local plane (never for a local-only or
+/// already-mounted workspace). Mirrors the cloud-shaped subset of [NomosBridge.connect]'s parameters.
+class NomosSessionCredentials {
+  /// The cloud base URL the workspace syncs from (e.g. `https://nomos.captainapp.co.uk`).
+  final String cloud;
+
+  /// The verified principal's access token (`x-nomos-auth`), when the workspace requires one.
+  final String? authToken;
+
+  /// The client id for this device's replica (defaults per the runner when omitted).
+  final String? clientId;
+
+  /// The device signing secret (base64, from `authorKeygen`) — the warrant default for every offer.
+  final String? authorSecret;
+
+  /// Open even when the workspace has no remote main yet (an unborn workspace reads empty).
+  final bool allowUnborn;
+
+  const NomosSessionCredentials({
+    required this.cloud,
+    this.authToken,
+    this.clientId,
+    this.authorSecret,
+    this.allowUnborn = false,
+  });
+}
+
 /// THE BRIDGE. Construct over a [BridgeTransport], `await ready`, then `connect(...)` and drive the holon.
 class NomosBridge {
   final BridgeTransport _transport;
@@ -708,6 +736,9 @@ class NomosBridge {
   // caches the per-workspace [NomosSession] handle so `bridge.session(ws)` is stable + cheap.
   final Set<String> _sessionNames = {};
   final Map<String, NomosSession> _sessionViews = {};
+  // [acquireSession]'s per-workspace single-flight: workspace → the in-flight open every concurrent
+  // acquirer joins (removed when it completes; a live session then hits the fast path instead).
+  final Map<String, Future<NomosSession>> _acquiring = {};
   int _seq = 0;
   final String _traceId = _newTraceId();
   late final StreamSubscription<Map<String, Object?>> _sub;
@@ -1205,6 +1236,60 @@ class NomosBridge {
     return session(ws);
   }
 
+  /// ACQUIRE A SESSION ATOMICALLY — the plug-and-play multi-workspace open (co2 DX ask). Semantics:
+  ///   • an already-connected session is returned as-is (no work, no credentials);
+  ///   • a workspace the local plane already holds (mounted by another path, LRU-parked, or with resident
+  ///     custody — e.g. a locally-born child) is opened LOCAL-ONLY, in place (no cloud, no credentials);
+  ///   • two concurrent [acquireSession] calls for the same workspace SINGLE-FLIGHT: the second joins the
+  ///     first's in-flight open and both yield the SAME [NomosSession] — one connect, never two;
+  ///   • ONLY when a genuine cloud open is required (the workspace is nowhere on this device) is
+  ///     [ifAbsentCredentials] invoked — exactly once — and the connect made with what it returns.
+  /// Omitting [ifAbsentCredentials] makes a genuinely-absent workspace a named [StateError] instead of a
+  /// silent cloudless mount.
+  Future<NomosSession> acquireSession(String workspace,
+      {Future<NomosSessionCredentials> Function()? ifAbsentCredentials}) {
+    // Fast path: a live session needs no runner round-trip (and never asks for credentials).
+    if (_sessionNames.contains(workspace)) return Future.value(session(workspace));
+    // SINGLE-FLIGHT: one in-flight open per workspace per plane; concurrent callers join it.
+    return _acquiring.putIfAbsent(workspace, () async {
+      try {
+        if (_sessionNames.contains(workspace)) return session(workspace);
+        // Consult the plane's TRUTHFUL registry (mounted ∪ parked ∪ resident custody — the runner's
+        // realm.list()): anything the device already holds opens locally, no cloud, no credentials.
+        var resident = false;
+        try {
+          resident = (await listWorkspaces())
+              .any((w) => w['workspace']?.toString() == workspace);
+        } catch (_) {
+          // a pre-connect plane has no registry yet — fall through to the credentials decision below.
+        }
+        if (resident) {
+          await connect(workspace: workspace, session: workspace, allowUnborn: true);
+          return session(workspace);
+        }
+        if (ifAbsentCredentials == null) {
+          throw StateError(
+              'acquireSession("$workspace"): the workspace is not on this device\'s plane and no '
+              'ifAbsentCredentials was given — a cloud open is genuinely required');
+        }
+        final c = await ifAbsentCredentials();
+        await connect(
+          cloud: c.cloud,
+          workspace: workspace,
+          session: workspace,
+          clientId: c.clientId,
+          authToken: c.authToken,
+          authorSecret: c.authorSecret,
+          allowUnborn: c.allowUnborn,
+        );
+        return session(workspace);
+      } finally {
+        // completed (either way) — the next acquire re-evaluates fresh (a live session hits the fast path).
+        _acquiring.remove(workspace);
+      }
+    });
+  }
+
   /// Reserve a KERNEL-MINTED typed id (`<TypeTag>_<uuidv7>`) via the holon's front-door mint — for app-side
   /// references (routing keys, optimistic UI). `.creates` payloads still carry NO id: the LAW mints those
   /// (see [offerCreates], which returns them).
@@ -1947,6 +2032,13 @@ class NomosSession extends NomosBridge {
   @override
   NomosSession session(String workspace) => parent.session(workspace);
 
+  /// An acquired session mounts on the SHARED plane — delegate to the parent (the plane owns the
+  /// single-flight registry; a session never owns mounts).
+  @override
+  Future<NomosSession> acquireSession(String workspace,
+          {Future<NomosSessionCredentials> Function()? ifAbsentCredentials}) =>
+      parent.acquireSession(workspace, ifAbsentCredentials: ifAbsentCredentials);
+
   /// A followed ref mounts on the SHARED plane — delegate to the parent (a session never owns mounts).
   @override
   Future<NomosSession> follow(NomosRef ref,

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

package/dart/test/acquire_session_test.dart

@@ -0,0 +1,152 @@
+// acquireSession — the ATOMIC session-open (co2 DX ask): reuses a mounted session, opens a plane-resident
+// (parked / resident-custody) workspace locally, JOINS an in-flight open (single-flight per workspace), and
+// invokes the credentials callback ONLY when a cloud open is genuinely required. Proven hermetically over a
+// fake transport (the same style as webview_bridge_test.dart) — the live-runner leg rides
+// cluster_local_autosync_test.dart.
+import 'dart:async';
+
+import 'package:nomos_client/nomos_client.dart';
+import 'package:test/test.dart';
+
+/// A fake runner: answers connect (after a real async gap, so concurrency is observable) and
+/// listWorkspaces (from [resident]); records every request.
+class FakeRunner implements BridgeTransport {
+  final _incoming = StreamController<Map<String, Object?>>.broadcast();
+  final List<Map<String, Object?>> sent = [];
+  final List<String> resident; // workspaces the plane already holds (realm.list())
+
+  FakeRunner({this.resident = const []}) {
+    scheduleMicrotask(
+        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready'}));
+  }
+
+  int get connectCount => sent.where((m) => m['op'] == 'connect').length;
+  Map<String, Object?> connectArgs(int i) =>
+      (sent.where((m) => m['op'] == 'connect').elementAt(i)['args'] as Map)
+          .cast<String, Object?>();
+
+  @override
+  Stream<Map<String, Object?>> get messages => _incoming.stream;
+
+  @override
+  void send(Map<String, Object?> message) {
+    sent.add(message);
+    final id = message['id'] as int;
+    final op = message['op'] as String;
+    final args = (message['args'] as Map).cast<String, Object?>();
+    Future<void>.delayed(const Duration(milliseconds: 5), () {
+      Object? result;
+      switch (op) {
+        case 'connect':
+          result = {'workspace': args['workspace']};
+          break;
+        case 'listWorkspaces':
+          result = {
+            'workspaces': [
+              for (final ws in resident)
+                {
+                  'session': ws,
+                  'workspace': ws,
+                  'mounted': false,
+                  'parked': true,
+                  'syncPosture': 'local-only'
+                }
+            ]
+          };
+          break;
+        default:
+          result = {};
+      }
+      _incoming
+          .add({'v': kWebviewBridgeVersion, 'id': id, 'ok': true, 'result': result});
+    });
+  }
+}
+
+void main() {
+  test('an already-connected session is reused — credentials NEVER invoked, no second connect', () async {
+    final runner = FakeRunner();
+    final bridge = NomosBridge(runner);
+    await bridge.ready;
+    await bridge.connect(workspace: 'home', session: 'home');
+    expect(runner.connectCount, 1);
+
+    final s = await bridge.acquireSession('home',
+        ifAbsentCredentials: () async =>
+            fail('credentials must not be requested for a mounted session'));
+    expect(identical(s, bridge.session('home')), isTrue);
+    expect(runner.connectCount, 1, reason: 'no re-connect for a live session');
+    await bridge.dispose();
+  });
+
+  test('a plane-resident (parked) workspace opens LOCALLY — no cloud, credentials NOT invoked', () async {
+    final runner = FakeRunner(resident: ['estate']);
+    final bridge = NomosBridge(runner);
+    await bridge.ready;
+
+    var asked = false;
+    final s = await bridge.acquireSession('estate', ifAbsentCredentials: () async {
+      asked = true;
+      return const NomosSessionCredentials(cloud: 'https://never.invalid');
+    });
+    expect(asked, isFalse, reason: 'a resident workspace never asks for credentials');
+    expect(s.workspace, 'estate');
+    expect(runner.connectCount, 1);
+    expect(runner.connectArgs(0).containsKey('cloud'), isFalse,
+        reason: 'a resident open is local-only — no cloud in the connect');
+    await bridge.dispose();
+  });
+
+  test('concurrent acquisition SINGLE-FLIGHTS: one open, one credentials call, the same session', () async {
+    final runner = FakeRunner();
+    final bridge = NomosBridge(runner);
+    await bridge.ready;
+
+    var credentialCalls = 0;
+    Future<NomosSessionCredentials> creds() async {
+      credentialCalls++;
+      await Future<void>.delayed(const Duration(milliseconds: 10));
+      return const NomosSessionCredentials(
+          cloud: 'https://cloud.example', authToken: 'tok', allowUnborn: true);
+    }
+
+    final results = await Future.wait([
+      bridge.acquireSession('cloudy', ifAbsentCredentials: creds),
+      bridge.acquireSession('cloudy', ifAbsentCredentials: creds),
+      bridge.acquireSession('cloudy', ifAbsentCredentials: creds),
+    ]);
+    expect(credentialCalls, 1, reason: 'the credentials callback fires exactly once');
+    expect(runner.connectCount, 1, reason: 'ONE connect for three concurrent acquires');
+    expect(identical(results[0], results[1]), isTrue);
+    expect(identical(results[1], results[2]), isTrue);
+    final args = runner.connectArgs(0);
+    expect(args['cloud'], 'https://cloud.example');
+    expect(args['authToken'], 'tok');
+    expect(args['allowUnborn'], isTrue);
+    await bridge.dispose();
+  });
+
+  test('genuinely absent + no credentials callback → a named StateError (never a silent cloudless mount)',
+      () async {
+    final runner = FakeRunner();
+    final bridge = NomosBridge(runner);
+    await bridge.ready;
+    await expectLater(bridge.acquireSession('nowhere'), throwsStateError);
+    expect(runner.connectCount, 0);
+    await bridge.dispose();
+  });
+
+  test('a NomosSession delegates acquireSession to the parent plane (one registry)', () async {
+    final runner = FakeRunner();
+    final bridge = NomosBridge(runner);
+    await bridge.ready;
+    await bridge.connect(workspace: 'home', session: 'home');
+    await bridge.connect(workspace: 'estate', session: 'estate');
+
+    final viaSession = await bridge.session('home').acquireSession('estate',
+        ifAbsentCredentials: () async =>
+            fail('estate is already mounted — no credentials'));
+    expect(identical(viaSession, bridge.session('estate')), isTrue);
+    await bridge.dispose();
+  });
+}

package/dart/test/cluster_local_autosync_test.dart

@@ -0,0 +1,119 @@
+// CO2 ACCEPTANCE — local-only autoSync must not block the multi-workspace plane (their report, verbatim):
+//   - Open multiple local-only sessions with NomosTestHarness.cluster.
+//   - await homeSession.autoSync() completes promptly.
+//   - await bridge.listWorkspaces() and a query on a sibling estate session still complete.
+//   - stopAutoSync() and harness disposal complete.
+//   - No local://.../intent-offers fetch attempts occur.
+// autoSync() REGISTERS background behavior and returns immediately; for a local-only (local://) session it
+// performs NO network work and must not monopolize the runner request dispatcher.
+@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';
+
+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(
+      'local-only autoSync() returns promptly, never fetches, and does not block the plane (co2 acceptance)',
+      () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+
+    // 1. Open multiple local-only sessions with NomosTestHarness.cluster (four, one bridge).
+    final names = ['home', 'estate-a', 'estate-b', 'estate-c'];
+    final diagnostics = <String>[];
+    final harness = await NomosTestHarness.cluster(
+      workspaces: {for (final ws in names) ws: [_guestbookDeploy]},
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      onDiagnostic: diagnostics.add,
+    );
+    try {
+      final home = harness.session('home');
+
+      // A realistic home holds local writes (ahead of any base) — this is what drives the up-leg machinery.
+      await home.offerDirective(
+        domain: 'guestbook',
+        directiveId: 'signGuestbook',
+        payload: {
+          'author': 'ada',
+          'message': 'offline write before autoSync',
+          'mood': 'delighted',
+          'signedAt': '2026-07-11T00:00:00Z',
+        },
+        actor: 'ada',
+      );
+
+      // 2. await homeSession.autoSync() completes promptly.
+      await home.autoSync().timeout(const Duration(seconds: 10),
+          onTimeout: () => throw StateError(
+              'autoSync() on a local-only session did not complete within 10s (the reported deadlock)'));
+
+      // 3. await bridge.listWorkspaces() and a query on a sibling estate session still complete.
+      final listed = await harness.bridge.listWorkspaces().timeout(
+          const Duration(seconds: 10),
+          onTimeout: () => throw StateError(
+              'listWorkspaces() hung after a local-only autoSync (dispatcher monopolized)'));
+      expect(listed.map((w) => w['session'].toString()).toSet(),
+          containsAll(names.toSet()));
+      final sibling = await harness
+          .session('estate-a')
+          .query('entriesByAuthor', {'author': 'nobody'}).timeout(
+              const Duration(seconds: 10),
+              onTimeout: () => throw StateError(
+                  'a sibling estate query hung after a local-only autoSync'));
+      expect(sibling, isEmpty);
+
+      // Give any wrongly-registered background sync machinery time to fire so its fetch attempts would show.
+      await Future<void>.delayed(const Duration(seconds: 2));
+
+      // 4. stopAutoSync() and harness disposal complete (disposal asserted in finally / teardown).
+      await home.stopAutoSync().timeout(const Duration(seconds: 10),
+          onTimeout: () =>
+              throw StateError('stopAutoSync() hung on a local-only session'));
+
+      // Bonus (live-runner leg of the acquireSession DX ask): a mounted local workspace is acquired
+      // WITHOUT credentials, and yields the same cached session handle.
+      final acquired = await harness.bridge.acquireSession('estate-b',
+          ifAbsentCredentials: () async =>
+              fail('estate-b is mounted on the plane — credentials must not be requested'));
+      expect(identical(acquired, harness.session('estate-b')), isTrue);
+
+      // 5. No local://.../intent-offers fetch attempts occur (attempted-and-refused still counts as attempted).
+      final offending = diagnostics
+          .where((l) => l.contains('intent-offers') || l.contains('refusing network fetch'))
+          .toList();
+      expect(offending, isEmpty,
+          reason:
+              'a local-only session must perform NO network work — saw:\n${offending.join('\n')}');
+    } finally {
+      await harness
+          .dispose()
+          .timeout(const Duration(seconds: 20), onTimeout: () {
+        throw StateError('harness disposal hung (the reported teardown hang)');
+      });
+    }
+  }, timeout: const Timeout(Duration(minutes: 3)));
+}

package/package.json

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

package/src/compile_package_main.ts

@@ -904,7 +904,7 @@ const NOMOS_TYPES_DEP = "^0.3.0";
 // 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
-const NOMOS_CLIENT_DEP = "^0.48.1";
+const NOMOS_CLIENT_DEP = "^0.49.0";
 // DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in dsl/dart/pubspec.yaml
 // and dsl/dart_types/pubspec.yaml — a Dart release without this bump fails the suite, so tenants never
 // land back in dependency_overrides (the exact co2 report this closes, third occurrence).