@githolon/dsl 0.84.0 → 0.85.0

package/dart/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 0.55.2
+
+- Session-state DX (co2): explicit workspace lifecycle `state` on `listWorkspaces()` —
+  `connected | resident | parked` — so a listed-but-unopened workspace (e.g. a locally-born
+  child) is distinguishable at a glance, ending the "listed but `session(ws)` fails on first op"
+  footgun.
+- `NomosRef.acquire(bridge)` — open a born/resident ref directly:
+  `await outcome.bornRefs.single.acquire(bridge)` (sugar over `acquireSession`, keyed by the
+  ref's workspace).
+- `NomosSession.isConnected` + `assertConnected()` — the fail-at-bind guard: a clear, actionable
+  `StateError` instead of an opaque "session is not connected" on the first read/write.
+- Patch bump — keeps the exact-minor `^0.55.0` pins valid, no generated-client re-pin needed.
+
 ## 0.55.1
 
 - Add `deriveWorkspaceName(namespace, key)` — re-derive the workspace name a keyed birth

package/dart/lib/src/webview_bridge.dart

@@ -689,6 +689,25 @@ class NomosOfferOutcome {
       .toList();
 }
 
+/// OPEN A REF'S WORKSPACE DIRECTLY (co2 DX ask) — `await outcome.bornRefs.single.acquire(bridge)`. Sugar over
+/// [NomosBridge.acquireSession] keyed by the ref's `workspace`: an already-open session returns as-is; a
+/// device-resident/parked/just-born workspace opens LOCAL-ONLY in place (no cloud, no credentials); only a
+/// genuinely-absent workspace needs [ifAbsentCredentials] (else a named [StateError]). Returns the live
+/// [NomosSession] — so the failure surfaces HERE (at open), never later on the client's first query. Defined
+/// in nomos_client (NOT on the pure `nomos_types` [NomosRef]) so the types package stays bridge-free.
+extension NomosRefAcquire on NomosRef {
+  Future<NomosSession> acquire(
+    NomosBridge bridge, {
+    Future<NomosSessionCredentials> Function()? ifAbsentCredentials,
+  }) {
+    if (workspace.isEmpty) {
+      throw ArgumentError.value(this, 'ref',
+          'NomosRef.acquire: the ref carries no workspace — only a workspace-complete ref is openable');
+    }
+    return bridge.acquireSession(workspace, ifAbsentCredentials: ifAbsentCredentials);
+  }
+}
+
 /// 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.
@@ -1026,13 +1045,28 @@ class NomosBridge {
   List<String> get connectedSessions =>
       List.unmodifiable(_eventPlane._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();
+  /// ENUMERATE THE LOCAL PLANE — every workspace on this device + its lifecycle STATE and sync posture:
+  /// `[{ session, workspace, state, mounted, parked, syncPosture }]`. The explicit **`state`** (co2 DX ask)
+  /// is the field to branch on — it removes the "listed but `session(ws)` fails on first op" footgun:
+  ///   • `"connected"` — a live open session; `bridge.session(ws)` works, reads/writes flow NOW;
+  ///   • `"resident"`  — custody is on the device but no session is open yet (e.g. a locally-born child) —
+  ///                     call `bridge.acquireSession(ws)` / `ref.acquire(bridge)` before using it;
+  ///     • `"parked"`  — custody resident but the holon is LRU-disposed; it re-mounts on demand (acquire).
+  /// `syncPosture` is `"local-only"` (no cloud counterpart) or `"cloud-bound"`.
+  Future<List<Map<String, Object?>>> listWorkspaces() async {
+    final connected = _eventPlane._sessionNames.toSet();
+    return (((_asMap(await _call('listWorkspaces'))['workspaces']) as List?) ?? const [])
+        .map((e) => (e as Map).cast<String, Object?>())
+        .map((w) {
+          final ws = w['workspace']?.toString() ?? '';
+          // `connected` is the app's own connect() truth; `parked`/resident come from the runner realm.
+          w['state'] = (w['parked'] == true)
+              ? 'parked'
+              : (connected.contains(ws) ? 'connected' : 'resident');
+          return w;
+        })
+        .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
@@ -2362,6 +2396,26 @@ class NomosSession extends NomosBridge {
   @override
   String? get _sessionName => workspace;
 
+  /// Whether this workspace has a LIVE open session on the plane (the app `connect`/`acquireSession`d it). A
+  /// lazily-created `bridge.session(ws)` handle is valid to HOLD before connect, but an op on it fails until
+  /// the workspace is open. Check this — or prefer `bridge.acquireSession(ws)` / `ref.acquire(bridge)`, which
+  /// open-then-return — so a not-connected mistake is caught at BIND, not on the client's first query.
+  bool get isConnected => parent.connectedSessions.contains(workspace);
+
+  /// Fail-at-bind guard (co2 DX ask): throw a CLEAR, actionable [StateError] if this workspace is not open
+  /// yet, so a generated client can call it in its constructor and surface the mistake immediately instead of
+  /// an opaque "session is not connected" on the first read/write.
+  void assertConnected() {
+    if (!isConnected) {
+      throw StateError(
+        'NomosSession("$workspace") is not connected — the workspace is not open on this device\'s plane. '
+        'Open it first: `await bridge.acquireSession("$workspace")` (or `await ref.acquire(bridge)` for a '
+        'born child), then bind the client to the returned session. A held-but-unopened session handle is '
+        'valid to construct but cannot serve ops until connected.',
+      );
+    }
+  }
+
   /// Sibling workspaces resolve on the shared plane — delegate to the parent's registry (never nest a
   /// session inside a session).
   @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.55.1
+version: 0.55.2
 
 environment:
   sdk: ^3.5.0

package/dart/test/acquire_session_test.dart

@@ -41,14 +41,21 @@ class FakeRunner implements BridgeTransport {
           result = {'workspace': args['workspace']};
           break;
         case 'listWorkspaces':
+          // Realm truth: a CONNECTED workspace is mounted (holon live); a resident-but-unconnected one is
+          // parked custody. Reflect connects so the derived lifecycle `state` is observable in both postures.
+          final connected = sent
+              .where((m) => m['op'] == 'connect')
+              .map((m) => ((m['args'] as Map)['workspace']).toString())
+              .toSet();
+          final all = {...resident, ...connected};
           result = {
             'workspaces': [
-              for (final ws in resident)
+              for (final ws in all)
                 {
                   'session': ws,
                   'workspace': ws,
-                  'mounted': false,
-                  'parked': true,
+                  'mounted': connected.contains(ws),
+                  'parked': !connected.contains(ws) && resident.contains(ws),
                   'syncPosture': 'local-only'
                 }
             ]
@@ -149,4 +156,64 @@ void main() {
     expect(identical(viaSession, bridge.session('estate')), isTrue);
     await bridge.dispose();
   });
+
+  // ── SESSION-STATE DX cluster (co2): explicit lifecycle state + fail-at-bind + openable refs ──
+
+  test('listWorkspaces() reports explicit state: resident/parked before open, connected after', () async {
+    final runner = FakeRunner(resident: ['estate']); // realm returns mounted:false, parked:true
+    final bridge = NomosBridge(runner);
+    await bridge.ready;
+
+    // Before any connect: the plane-resident (parked) workspace surfaces with an explicit non-connected state.
+    var list = await bridge.listWorkspaces();
+    final before = list.firstWhere((w) => w['workspace'] == 'estate');
+    expect(before['state'], 'parked', reason: 'parked custody is not connected — the app must acquire it first');
+
+    // After connecting it, the SAME workspace reports connected.
+    await bridge.connect(workspace: 'estate', session: 'estate');
+    list = await bridge.listWorkspaces();
+    final after = list.firstWhere((w) => w['workspace'] == 'estate');
+    expect(after['state'], 'connected');
+    await bridge.dispose();
+  });
+
+  test('NomosSession.isConnected + assertConnected: fail at BIND, not on first query', () async {
+    final runner = FakeRunner();
+    final bridge = NomosBridge(runner);
+    await bridge.ready;
+
+    // A held-but-unopened handle is valid to construct but not connected — assertConnected throws NOW.
+    final lazy = bridge.session('estate');
+    expect(lazy.isConnected, isFalse);
+    expect(lazy.assertConnected, throwsStateError);
+
+    await bridge.connect(workspace: 'estate', session: 'estate');
+    final live = bridge.session('estate');
+    expect(live.isConnected, isTrue);
+    expect(live.assertConnected, returnsNormally);
+    await bridge.dispose();
+  });
+
+  test('NomosRef.acquire(bridge) opens a born/resident ref directly → a live session', () async {
+    final runner = FakeRunner(resident: ['estate-42']);
+    final bridge = NomosBridge(runner);
+    await bridge.ready;
+
+    // The shape a `.births()` outcome yields: outcome.bornRefs.single is a NomosRef on the born workspace.
+    final ref = NomosRef(workspace: 'estate-42', type: 'nomos.Workspace', id: 'estate-42');
+    final session = await ref.acquire(bridge); // no credentials — resident opens local-only
+    expect(session.workspace, 'estate-42');
+    expect(session.isConnected, isTrue);
+    expect(identical(session, bridge.session('estate-42')), isTrue);
+    await bridge.dispose();
+  });
+
+  test('NomosRef.acquire refuses a workspace-less ref (a bad locator fails HERE, not later)', () async {
+    final runner = FakeRunner();
+    final bridge = NomosBridge(runner);
+    await bridge.ready;
+    final bad = NomosRef(workspace: '', type: 'nomos.Workspace', id: 'x');
+    expect(() => bad.acquire(bridge), throwsArgumentError);
+    await bridge.dispose();
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.84.0",
+  "version": "0.85.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/codegen_dart_client.ts

@@ -837,6 +837,21 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `    return ${className}(session, actor: actor${encPresent ? ", keyStore: keyStore" : ""}).._preflighted = true;`,
     `  }`,
     ``,
+    `  /// OPEN-THEN-BIND (session_bound_clients.md ask 3) — the ONE-CALL path for a born/resident workspace:`,
+    `  /// \`await ${className}.open(bridge, ref: outcome.bornRefs.single)\` (or \`workspace: 'estate-42'\`).`,
+    `  /// It ACQUIRES the workspace's session on [bridge] first (an already-open one is reused; a device-`,
+    `  /// resident/parked/just-born one opens local-only in place) and THEN binds — so a not-open workspace`,
+    `  /// fails HERE, at open, never later on the client's first query. For a genuinely-absent cloud workspace,`,
+    `  /// \`acquireSession(ws, ifAbsentCredentials: ...)\` it yourself then [bind].`,
+    `  static Future<${className}> open(NomosBridge bridge, {NomosRef? ref, String? workspace, String? actor${encPresent ? ", NomosKeyStore? keyStore" : ""}}) async {`,
+    `    final ws = ref?.workspace ?? workspace;`,
+    `    if (ws == null || ws.isEmpty) {`,
+    `      throw ArgumentError('${className}.open: pass a workspace: or ref: — the workspace to open and bind');`,
+    `    }`,
+    `    final session = await bridge.acquireSession(ws);`,
+    `    return bind(session, actor: actor${encPresent ? ", keyStore: keyStore" : ""});`,
+    `  }`,
+    ``,
     `  /// The session workspace this client is bound to (from the [NomosSession] handle, when constructed with`,
     `  /// one) — the \`workspace\` of every read row's canonical [NomosRef]. '' on a bare (non-session) bridge.`,
     `  String get _ws {`,

package/src/compile_package_main.ts

@@ -47,7 +47,7 @@
  */
 import { execFileSync } from "node:child_process";
 import { expandCapabilityExports, isCapabilityDecl } from "./capability_exports.js";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -684,6 +684,60 @@ function removeLegacyFlatDartLayout(dartOut: string, moduleNames: readonly strin
  * analyzer-clean plug-and-play entrypoint (zero `show`/`hide`; framework-shared
  * symbols dedup into `nomos_framework.dart`, so no export is ambiguous).
  */
+/**
+ * COMPILE ATOMICITY (co2 dev report) — a failed compile MUST NOT delete the tenant's already-good generated
+ * packages. Both Dart emit paths used to `rmSync(genDir)` up-front and then write; a mid-emit throw (a codegen
+ * error, a flow-gate refusal surfaced during emit) left the dir WIPED or partial, so the dev could no longer
+ * `dart analyze` / open the app. Instead, each generated dir is renamed ASIDE to `<dir>.nomos-bak`, a fresh
+ * empty dir is created, and the emit writes into it. On success the whole emit `commit()`s (drops the backups);
+ * on ANY throw it `rollback()`s (removes the partial dir, restores the backup). The transactions are collected
+ * module-side and committed/rolled-back once around the whole Dart emit (the CLI is single-threaded per run).
+ */
+const _genDirTx: { commit(): void; rollback(): void }[] = [];
+let _genDirTxHandlerInstalled = false;
+/** Install the ONE finalizer. A compile refusal is `fail()` → `process.exit(1)`, which BYPASSES try/catch —
+ *  so the only reliable place to finalize the transactional gen dirs is the process `exit` event (a clean
+ *  exit commits, any non-zero exit rolls back). Sync only (rmSync/renameSync are sync — required in `exit`). */
+function installGenDirTxHandler(): void {
+  if (_genDirTxHandlerInstalled) return;
+  _genDirTxHandlerInstalled = true;
+  process.on("exit", (code) => {
+    for (const t of _genDirTx) {
+      try {
+        if (code === 0) t.commit();
+        else t.rollback();
+      } catch {
+        /* best-effort finalize — never mask the real exit */
+      }
+    }
+  });
+}
+/** Begin a transactional regeneration of `genDir` (see {@link _genDirTx}): back the prior dir aside + create a
+ *  fresh one, and register idempotent commit/rollback finalized at process exit. Replaces the old destructive
+ *  `rmSync(genDir); mkdirSync(genDir)` so a mid-emit `fail()`/throw restores the prior good package. */
+function beginAtomicGenDir(genDir: string): void {
+  installGenDirTxHandler();
+  const bak = `${genDir}.nomos-bak`;
+  rmSync(bak, { recursive: true, force: true }); // clear any stale backup from a previously-killed run
+  const hadPrior = existsSync(genDir);
+  if (hadPrior) renameSync(genDir, bak);
+  mkdirSync(genDir, { recursive: true });
+  let done = false;
+  _genDirTx.push({
+    commit() {
+      if (done) return;
+      done = true;
+      rmSync(bak, { recursive: true, force: true });
+    },
+    rollback() {
+      if (done) return;
+      done = true;
+      rmSync(genDir, { recursive: true, force: true });
+      if (hadPrior) renameSync(bak, genDir);
+    },
+  });
+}
+
 function emitDart(
   modules: readonly DomainModule[],
   dartOut: string,
@@ -698,8 +752,8 @@ function emitDart(
   const sourceByFile = new Map<string, string>(); // fileBase → src, for precise alias-import selection
   const genDir = path.join(dartOut, DART_GENERATED_SUBDIR);
   removeLegacyFlatDartLayout(dartOut, modules.map((m) => m.name));
-  rmSync(genDir, { recursive: true, force: true });
-  mkdirSync(genDir, { recursive: true });
+  // Transactional: back the prior generated dir aside instead of destroying it (compile atomicity).
+  beginAtomicGenDir(genDir);
 
   // 1. optional vendored framework support (barrel + src/), copied byte-for-byte except
   //    the barrel's schema_validation export (see DART_SUPPORT_SRC).
@@ -1073,8 +1127,8 @@ function emitDartPackages(
   const pkgDir = (name: string): string => path.join(dartOut, name);
   const freshGenDir = (name: string): string => {
     const g = path.join(pkgDir(name), "lib", DART_GENERATED_SUBDIR);
-    rmSync(g, { recursive: true, force: true });
-    mkdirSync(g, { recursive: true });
+    // Transactional: back the prior dir aside instead of destroying it (compile atomicity).
+    beginAtomicGenDir(g);
     return g;
   };
 
@@ -2604,6 +2658,8 @@ async function main(): Promise<void> {
       cfgDir,
       typeof dartCfg === "object" && dartCfg.out !== undefined ? dartCfg.out : path.join(outDir, "dart"),
     );
+    // COMPILE ATOMICITY (co2): the Dart emit is transactional (beginAtomicGenDir) — a mid-emit fail()/throw
+    // restores the prior good packages instead of leaving them wiped/partial. Finalized at process exit.
     if (dartPackages !== undefined) {
       const r = emitDartPackages(domainModules, dartOut, domainHash, packageInterface, dartPackages, dartNames, nomosCompat);
       dartFiles = r.written;