@githolon/dsl 0.59.0 → 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/dart_types/LICENSE

@@ -0,0 +1,45 @@
+# Nomos Pre-Release License (v1)
+
+Copyright © 2026 Captain App Ltd. All rights reserved.
+
+This is a pre-release of Nomos. This license gives you what you need to BUILD
+with it; we keep the rest for now.
+
+## You may
+
+- install and use these packages to author Nomos domains, compile them, and
+  deploy them to Nomos Cloud or any Nomos instance Captain App operates or
+  authorizes;
+- build, run, and ship applications on top of them — including commercial ones;
+- keep everything that's yours: code you write, and everything these tools
+  generate FOR you (scaffolds from `create-githolon` / `githolon generate`, generated
+  clients, compiled domain packages) carries NO restriction from us — it is
+  yours outright.
+
+## You may not
+
+- redistribute these packages or their source, in whole or in part, outside
+  your team;
+- modify them or build derivative tools, SDKs, or runtimes from their source;
+- offer the Nomos runtime, or anything materially similar, as a hosted service;
+- reverse-engineer the holon wasm runtime.
+
+## Data retention
+
+This is a pre-release we are actively evaluating. Workspaces you retire stop
+counting toward your quota but are NOT deleted: **we retain all workspace data
+(ledgers, law, intents) and may examine it to evaluate how the product is
+used.** Don't put anything in a pre-release workspace you wouldn't want the
+builders to read. If you need something truly expunged, ask:
+jack@captainapp.co.uk.
+
+## The rest
+
+Provided **as is**, with no warranty of any kind; to the maximum extent
+permitted by law, Captain App Ltd accepts no liability arising from your use.
+This license terminates automatically if you breach it.
+
+Want the kernel source, broader rights, or to do something this doesn't cover?
+**Ask: jack@captainapp.co.uk.** The plan is to open Nomos up gradually, with
+the people actually using it — telling us what you're building is how that
+happens faster.

package/dart_types/README.md

@@ -0,0 +1,15 @@
+# nomos_types
+
+The pure data core for Nomos Dart frontends — kernel wire types, the offer codec,
+the `NomosReads` typed-read seam, aggregate metadata, schema validation, and the
+structured error surface. **No transport, no bridge, no runtime**: this package is
+safe to depend on from UI code.
+
+It is the foundation of the Nomos layered-packages emit (`dart.packages` in
+`nomos-compile`): generated per-domain TYPES packages depend only on `nomos_types`,
+while the effectful runtime rides `nomos_client` (which depends on and re-exports
+this package). The layering line: generated types may flow to the UI; generated
+clients/runtime may not.
+
+Part of [Nomos](https://github.com/Captain-App/nomos2) — a local-first domain
+runtime where every peer runs the same deterministic wasm holon.

package/package.json

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

package/src/codegen_proof.ts

@@ -1878,6 +1878,10 @@ export interface ProofLegs {
    *  When this domain is itself the BORN child's law (no standalone create), the index also registers the
    *  child domain key pointing at the SAME leg, so `proof --domain <child>` resolves through the parent birth. */
   readonly childBirth?: ChildBirthLeg;
+  /** ALL child-birth legs, when this domain declares MORE THAN ONE `.births()` directive (`childBirth` is
+   *  always the first of these). Emitted only in the >1 case so single-birth output is byte-unchanged;
+   *  readers should treat `childBirths ?? (childBirth ? [childBirth] : [])` as the canonical set. */
+  readonly childBirths?: readonly ChildBirthLeg[];
   /** THE RELATION-BOOTSTRAP LEG — present iff this domain has a `.requires(R)`-gated directive AND a
    *  discoverable granter of R (a `.grants(R)` marker, or a plan-probed granting `writeTuple`). Proves the
    *  gated write SUCCEEDS once R is granted (the seed-then-prove positive). Additive: absent ⇒ older/ungated. */
@@ -2014,9 +2018,9 @@ export function proofLegsForModule(mod: DomainModule): ProofLegs | null {
   };
 }
 
-/** The first `.births()` directive in a module (with a synthesizable payload), or undefined. */
-function birthDirectiveOf(mod: DomainModule): Directive<unknown> | undefined {
-  return (mod.directives as Directive<unknown>[]).find((d) => d?.birthsChild === true && typeof d.payloadSchema === "object");
+/** Whether a module carries any `.births()` directive (with a synthesizable payload). */
+function hasBirthDirective(mod: DomainModule): boolean {
+  return (mod.directives as Directive<unknown>[]).some((d) => d?.birthsChild === true && typeof d.payloadSchema === "object");
 }
 
 /** Build the legs for ONE domain module — every leg it carries (compile-valid always; standalone-provable
@@ -2034,10 +2038,11 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
   } catch {
     standalone = null;
   }
-  // The child-birth leg (when the domain has a `.births()` directive) — discovered by running its plan.
-  const birthDir = birthDirectiveOf(mod);
-  const childBirth = birthDir !== undefined ? allBirths.find((b) => b.parentDomain === domain && b.birthDirectiveId === birthDir.id) : undefined;
-  const childBirthWithSetup = childBirth !== undefined ? attachParentSetup(childBirth, allBirths) : undefined;
+  // The child-birth legs (one per `.births()` directive) — discovered by running each plan. A parent
+  // with SEVERAL births (co2: birthCatalogueWorkspace + birthEstateWorkspace) keeps EVERY leg; keeping
+  // only the first left the other children compile-valid-only (unprovable through their birth).
+  const childBirths = allBirths.filter((b) => b.parentDomain === domain).map((b) => attachParentSetup(b, allBirths));
+  const childBirthWithSetup = childBirths[0];
 
   // The relation-bootstrap leg (when the domain has a `.requires(R)`-gated directive AND a discoverable
   // granter of R). FAIL SOFT: no granter → no leg (the negative conformance leg still covers the gate).
@@ -2120,6 +2125,7 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
         }
       : {}),
     ...(childBirthWithSetup !== undefined ? { childBirth: childBirthWithSetup } : {}),
+    ...(childBirths.length > 1 ? { childBirths } : {}),
     ...(relationBootstrap !== undefined ? { relationBootstrap } : {}),
   };
 }
@@ -2142,17 +2148,18 @@ export function proofLegsIndex(modules: readonly DomainModule[]): { default: str
   // no standalone leg of its own. Register that child domain key pointing at the PARENT's child-birth leg
   // (so `proof --domain estate` proves it THROUGH the birth that installs it — the only way it comes to be).
   for (const legs of [...Object.values(domains)]) {
-    const cb = legs.childBirth;
-    if (cb === undefined) continue;
-    const existing = domains[cb.childDomain];
-    if (existing === undefined) {
-      // A pure child-only domain whose ONLY proof is the parent birth: register it as child-birth-provable.
-      domains[cb.childDomain] = { domain: cb.childDomain, legs: ["compile-valid", "child-birth-provable"], childBirth: cb };
-      if (!order.includes(cb.childDomain)) order.push(cb.childDomain);
-    } else if (existing.childBirth === undefined) {
-      // The child domain ALSO compiled standalone (e.g. it has its own create) — add the child-birth leg to it.
-      const mergedLegs = [...new Set([...(existing.legs ?? ["compile-valid"]), "child-birth-provable" as const])];
-      domains[cb.childDomain] = { ...existing, legs: mergedLegs, childBirth: cb };
+    // EVERY birth leg fans out to its child (a parent with several `.births()` registers each child).
+    for (const cb of legs.childBirths ?? (legs.childBirth !== undefined ? [legs.childBirth] : [])) {
+      const existing = domains[cb.childDomain];
+      if (existing === undefined) {
+        // A pure child-only domain whose ONLY proof is the parent birth: register it as child-birth-provable.
+        domains[cb.childDomain] = { domain: cb.childDomain, legs: ["compile-valid", "child-birth-provable"], childBirth: cb };
+        if (!order.includes(cb.childDomain)) order.push(cb.childDomain);
+      } else if (existing.childBirth === undefined) {
+        // The child domain ALSO compiled standalone (e.g. it has its own create) — add the child-birth leg to it.
+        const mergedLegs = [...new Set([...(existing.legs ?? ["compile-valid"]), "child-birth-provable" as const])];
+        domains[cb.childDomain] = { ...existing, legs: mergedLegs, childBirth: cb };
+      }
     }
   }
   if (order.length === 0) return null;
@@ -2473,7 +2480,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   // domain's FULL legs (so the offline runner + the index never describe different directives).
   const hasStandaloneCreate = (m: DomainModule): boolean =>
     (m.directives as Directive<unknown>[]).some((d) => isStandaloneCreate(d));
-  const hasBirth = (m: DomainModule): boolean => birthDirectiveOf(m) !== undefined;
+  const hasBirth = (m: DomainModule): boolean => hasBirthDirective(m);
   const isBootstrapProvable = (m: DomainModule): boolean => {
     try { return discoverRelationBootstrapLeg(m) !== undefined; } catch { return false; }
   };