@githolon/dsl 0.100.6 → 0.101.1

package/dart/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.63.0
+
+- Generated clients now expose business-first conflict policy, schema-aware merge continuation and recursive
+  organisation descriptions. The client privately owns lifecycle discovery, parent/child traversal, signer
+  custody and replay; applications follow typed business references rather than framework routes.
+
 ## 0.62.2
 
 - Make `NomosTestHarness` own a complete, verifiable local trust lineage. Tests still bind a business actor

package/dart/lib/src/dev_cloud.dart

@@ -49,10 +49,12 @@ class NomosTestCloud {
   final Uri _upstream; // the real dev-cloud origin the proxy forwards to
   final HttpClient _client;
   final void Function(String line)? _onDiagnostic;
+  final String? testKRootPublic;
   bool _online = true;
   bool _stopped = false;
 
-  NomosTestCloud._(this._server, this._proxy, this._upstream, this._client, this._onDiagnostic);
+  NomosTestCloud._(this._server, this._proxy, this._upstream, this._client,
+      this._onDiagnostic, this.testKRootPublic);
 
   /// The base URL a cloud-BOUND session connects to (`connect(cloud: cloud.origin)`). Points at the PARTITION
   /// PROXY, so [setOnline] deterministically severs/heals the whole plane's link to custody.
@@ -63,7 +65,8 @@ class NomosTestCloud {
   /// cloud and peers converge. Deterministic: no timing races, the test decides exactly when the link exists.
   void setOnline(bool online) {
     _online = online;
-    _log('partition: ${online ? "ONLINE (link up)" : "OFFLINE (link severed)"}');
+    _log(
+        'partition: ${online ? "ONLINE (link up)" : "OFFLINE (link severed)"}');
   }
 
   bool get online => _online;
@@ -72,8 +75,10 @@ class NomosTestCloud {
   /// live cloud state DIRECTLY (bypassing the partition proxy) — a test assertion about custody must see the
   /// truth even while the app's link is partitioned OFFLINE.
   Future<RemoteWorkspaceState> remoteHead(String workspace) async {
-    final body = await _getJson(_upstream.replace(path: '/v2/workspaces/$workspace'));
-    final ledger = (body['ledgerState'] as Map?)?.cast<String, Object?>() ?? const {};
+    final body =
+        await _getJson(_upstream.replace(path: '/v2/workspaces/$workspace'));
+    final ledger =
+        (body['ledgerState'] as Map?)?.cast<String, Object?>() ?? const {};
     return RemoteWorkspaceState(
       workspace: workspace,
       initialized: body['initialized'] == true,
@@ -109,7 +114,8 @@ class NomosTestCloud {
     final chosenPort = port == 0 ? await _freePort() : port;
     final args = <String>[
       serverEntry,
-      '--port', '$chosenPort',
+      '--port',
+      '$chosenPort',
       if (ephemeral) '--ephemeral',
       if (dataDir != null) ...['--data', dataDir],
       if (platform != null) ...['--platform', platform],
@@ -118,8 +124,14 @@ class NomosTestCloud {
     void log(String m) => onDiagnostic?.call('[nomos-test-cloud] $m');
     log('spawning: $node ${args.join(' ')}');
     final proc = await Process.start(node, args, mode: ProcessStartMode.normal);
-    proc.stdout.transform(utf8.decoder).transform(const LineSplitter()).listen((l) => log('server: $l'));
-    proc.stderr.transform(utf8.decoder).transform(const LineSplitter()).listen((l) => log('server!: $l'));
+    proc.stdout
+        .transform(utf8.decoder)
+        .transform(const LineSplitter())
+        .listen((l) => log('server: $l'));
+    proc.stderr
+        .transform(utf8.decoder)
+        .transform(const LineSplitter())
+        .listen((l) => log('server!: $l'));
 
     final upstream = Uri.parse('http://127.0.0.1:$chosenPort');
     final client = HttpClient();
@@ -128,6 +140,7 @@ class NomosTestCloud {
     // half-born platform's typed refusals.
     final deadline = DateTime.now().add(readyTimeout);
     var ready = false;
+    String? testKRootPublic;
     while (DateTime.now().isBefore(deadline)) {
       try {
         final req = await client.getUrl(upstream.replace(path: '/health'));
@@ -136,7 +149,11 @@ class NomosTestCloud {
         if (resp.statusCode == 200) {
           final health = jsonDecode(body) as Map<String, dynamic>;
           final platformReady = health['platformReady'];
-          if (platform == null || platformReady == true) { ready = true; break; }
+          if (platform == null || platformReady == true) {
+            testKRootPublic = health['testKRootPublic']?.toString();
+            ready = true;
+            break;
+          }
         }
       } catch (_) {/* not up yet */}
       await Future<void>.delayed(const Duration(milliseconds: 200));
@@ -150,7 +167,8 @@ class NomosTestCloud {
 
     // The partition proxy — forwards to the dev cloud when ONLINE, fails fast when OFFLINE.
     final proxy = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
-    final cloud = NomosTestCloud._(proc, proxy, upstream, client, onDiagnostic);
+    final cloud = NomosTestCloud._(
+        proc, proxy, upstream, client, onDiagnostic, testKRootPublic);
     proxy.listen(cloud._handleProxy);
     log('partition proxy at ${cloud.origin} → $upstream');
     return cloud;
@@ -168,16 +186,26 @@ class NomosTestCloud {
       return;
     }
     try {
-      final target = _upstream.replace(path: req.uri.path, query: req.uri.query.isEmpty ? null : req.uri.query);
+      final target = _upstream.replace(
+          path: req.uri.path,
+          query: req.uri.query.isEmpty ? null : req.uri.query);
       final fwd = await _client.openUrl(req.method, target);
-      req.headers.forEach((name, values) { if (name.toLowerCase() != 'host') for (final v in values) fwd.headers.add(name, v); });
+      req.headers.forEach((name, values) {
+        if (name.toLowerCase() != 'host')
+          for (final v in values) fwd.headers.add(name, v);
+      });
       await fwd.addStream(req); // forward the request body
       final resp = await fwd.close();
       req.response.statusCode = resp.statusCode;
-      resp.headers.forEach((name, values) { for (final v in values) req.response.headers.add(name, v); });
+      resp.headers.forEach((name, values) {
+        for (final v in values) req.response.headers.add(name, v);
+      });
       await resp.pipe(req.response);
     } catch (e) {
-      try { req.response.statusCode = 502; await req.response.close(); } catch (_) {}
+      try {
+        req.response.statusCode = 502;
+        await req.response.close();
+      } catch (_) {}
     }
   }
 
@@ -186,7 +214,8 @@ class NomosTestCloud {
     final resp = await req.close();
     final text = await resp.transform(utf8.decoder).join();
     if (resp.statusCode != 200) {
-      throw NomosTestCloudException('GET $url → ${resp.statusCode}: ${text.substring(0, text.length.clamp(0, 200))}');
+      throw NomosTestCloudException(
+          'GET $url → ${resp.statusCode}: ${text.substring(0, text.length.clamp(0, 200))}');
     }
     return (jsonDecode(text) as Map).cast<String, Object?>();
   }
@@ -198,7 +227,9 @@ class NomosTestCloud {
     if (_stopped) return;
     _stopped = true;
     _log('stopping');
-    try { await _proxy.close(force: true); } catch (_) {}
+    try {
+      await _proxy.close(force: true);
+    } catch (_) {}
     _server.kill(ProcessSignal.sigterm);
     // Give it a moment, then SIGKILL if still alive.
     try {

package/dart/lib/src/test_harness.dart

@@ -261,7 +261,7 @@ class NomosTestHarness {
   /// `packages.json`. The harness owns a throwaway test root; app code never handles its key material.
   /// [nodeEntry] — path to `node-entry.ts`; when omitted it is resolved from [resolveFrom] via
   /// `require.resolve('@githolon/client/runner/node-entry.ts')`.
-  /// [installHelper] — the offline law-install lane. An EXISTING `.mjs` file is run as a node script (the
+  /// [installHelper] — the offline law-install lane. An EXISTING `.ts` or `.mjs` file is run as a node script (the
   /// in-repo `offline-install.ts`, the default when it exists beside [nodeEntry]); anything else is a
   /// githolon COMMAND LINE whose `harness-install` subcommand is driven (the default `npx githolon` when the
   /// in-repo helper is absent — a published tenant needs nothing but `githolon`). E.g. force the subcommand
@@ -293,16 +293,20 @@ class NomosTestHarness {
     final entry = nodeEntry ??
         await _resolveEntry(node, resolveFrom ?? Directory.current.path);
     // THE INSTALL LANE. [installHelper] is the one seam (PACKAGING NOTE above): either the in-repo
-    // `offline-install.ts` node script, OR the published `githolon harness-install` subcommand (the CLI
+    // `offline-install.mjs` node script, OR the published `githolon harness-install` subcommand (the CLI
     // bundles the engine + this exact install sequence, so a published tenant needs nothing but `githolon`).
-    //  • an EXISTING `.mjs` file  ⇒ run it as a node script (the in-repo default when present);
+    //  • an EXISTING `.ts`/`.mjs` file ⇒ run it as a node script (the in-repo default when present);
     //  • anything else            ⇒ treat it as a githolon COMMAND LINE and drive `harness-install`
     //    (default `npx githolon` when the in-repo helper is absent; the test forces this lane by passing
     //    e.g. `installHelper: 'node /abs/cli/dist/cli.mjs'`).
-    final resolvedHelper =
-        installHelper ?? '${File(entry).parent.path}/offline-install.ts';
+    final adjacentInstaller = '${File(entry).parent.path}/offline-install.mjs';
+    final resolvedHelper = installHelper ??
+        (File(adjacentInstaller).existsSync()
+            ? adjacentInstaller
+            : '${File(entry).parent.path}/offline-install.ts');
     final useInRepoScript =
-        resolvedHelper.endsWith('.mjs') && File(resolvedHelper).existsSync();
+        (resolvedHelper.endsWith('.ts') || resolvedHelper.endsWith('.mjs')) &&
+            File(resolvedHelper).existsSync();
     final githolonCmd = installHelper == null ? 'npx githolon' : resolvedHelper;
 
     // A FRESH temp dir per harness — the snapshot + any transient runner state live here and nowhere else,
@@ -503,10 +507,14 @@ class NomosTestHarness {
     }
     final entry = nodeEntry ??
         await _resolveEntry(node, resolveFrom ?? Directory.current.path);
-    final resolvedHelper =
-        installHelper ?? '${File(entry).parent.path}/offline-install.ts';
+    final adjacentInstaller = '${File(entry).parent.path}/offline-install.mjs';
+    final resolvedHelper = installHelper ??
+        (File(adjacentInstaller).existsSync()
+            ? adjacentInstaller
+            : '${File(entry).parent.path}/offline-install.ts');
     final useInRepoScript =
-        resolvedHelper.endsWith('.mjs') && File(resolvedHelper).existsSync();
+        (resolvedHelper.endsWith('.ts') || resolvedHelper.endsWith('.mjs')) &&
+            File(resolvedHelper).existsSync();
     final githolonCmd = installHelper == null ? 'npx githolon' : resolvedHelper;
 
     final workdir = await Directory.systemTemp.createTemp('nomos-cluster-');
@@ -780,6 +788,8 @@ class NomosTestHarness {
       //       server's in-process operator lane). Booting a born workspace is idempotent; an unborn one
       //       refuses 409, surfaced here with the fix.
       String? frameworkHash;
+      final frameworkPostRoutes =
+          <({String domain, String directive, String path})>[];
       final lawHashes = <String>[];
       await _phased(
           phase: '1/6: boot the born platform + deploy law on the test cloud',
@@ -806,9 +816,32 @@ class NomosTestHarness {
             for (final p in deployJsonPaths) {
               final body = await File(p).readAsString();
               await post('/v2/workspaces/$platformWorkspace/domains', body);
-              final summary = ((jsonDecode(body) as Map)['summary'] as Map?);
+              final deploy = (jsonDecode(body) as Map);
+              final summary = (deploy['summary'] as Map?);
               final h = summary?['domainHash']?.toString();
               if (h != null && h.isNotEmpty) lawHashes.add(h);
+              final openapi = deploy['openapi'] as Map?;
+              final pathSets = <Map>[
+                (openapi?['paths'] as Map?) ?? const {},
+                (((openapi?['x-nomos-framework-routes'] as Map?)?['paths'])
+                        as Map?) ??
+                    const {},
+              ];
+              for (final paths in pathSets) {
+                for (final entry in paths.entries) {
+                  final post = (entry.value as Map?)?['post'] as Map?;
+                  final route = post?['x-nomos'] as Map?;
+                  final domain = route?['domain']?.toString() ?? '';
+                  final directive = route?['directiveId']?.toString() ?? '';
+                  if (domain.isNotEmpty && directive.isNotEmpty) {
+                    frameworkPostRoutes.add((
+                      domain: domain,
+                      directive: directive,
+                      path: entry.key.toString(),
+                    ));
+                  }
+                }
+              }
             }
           });
       if (frameworkHash == null || frameworkHash!.isEmpty) {
@@ -819,6 +852,27 @@ class NomosTestHarness {
         throw NomosTestHarnessException(
             'cloudBound: no deploy.json carried a summary.domainHash — cannot run the birth ceremony (lawHash unknown)');
       }
+      final birthRoutes = frameworkPostRoutes
+          .where((route) => route.directive == 'birthHome')
+          .toSet()
+          .toList();
+      if (birthRoutes.length != 1) {
+        throw NomosTestHarnessException(
+            'cloudBound: the deployed package must expose exactly one semantic birthHome route; found ${birthRoutes.length}');
+      }
+      final applicationHomeDomain = birthRoutes.single.domain;
+      final birthHomePath = birthRoutes.single.path;
+      final enrollmentRoutes = frameworkPostRoutes
+          .where((route) =>
+              route.directive == 'enrollFirstDevice' &&
+              route.domain == applicationHomeDomain)
+          .toSet()
+          .toList();
+      if (enrollmentRoutes.length != 1) {
+        throw NomosTestHarnessException(
+            "cloudBound: application/home domain '$applicationHomeDomain' must expose exactly one semantic enrollFirstDevice route; found ${enrollmentRoutes.length}");
+      }
+      final enrollFirstDevicePath = enrollmentRoutes.single.path;
       // 2/6 — the LOCAL engine plane, CLOUD-BOUND, spawned BEFORE the birth: the runner's local kernel is
       //       what mints the device key + signs the birth cert (era-0: a birth is ATTESTED or not at all).
       transport = await _phased(
@@ -830,6 +884,12 @@ class NomosTestHarness {
               entry: entry,
               resolveFrom: resolveFrom,
               node: node,
+              environment: cloud.testKRootPublic == null
+                  ? null
+                  : {
+                      ...Platform.environment,
+                      'NOMOS_TEST_K_ROOT_PUBLIC': cloud.testKRootPublic!,
+                    },
               onDiagnostic: onDiagnostic));
       final plane = NomosBridge(transport!);
       await _phased(
@@ -895,7 +955,8 @@ class NomosTestHarness {
               'capturedClock': DateTime.now().toUtc().millisecondsSinceEpoch,
               'epoch': 0,
             }, secret);
-            await post('/v2/workspaces/$platformWorkspace/enrollFirstDevice', {
+            await post(
+                '/v2/workspaces/$platformWorkspace$enrollFirstDevicePath', {
               'keyHash': keyHash,
               'verifiedVia': issuer,
               'validFromEpoch': 0,
@@ -904,9 +965,10 @@ class NomosTestHarness {
               'actor': subject,
               'authorSecret': secret,
               'delegationCert': jsonEncode(delegationCert),
-            }, headers: {
-              'x-nomos-auth': idpToken
-            });
+            },
+                headers: {
+                  'x-nomos-auth': idpToken
+                });
             return (
               publicB64: publicB64,
               secret: secret,
@@ -922,7 +984,7 @@ class NomosTestHarness {
       await _phased(
           phase: '5/6: remote home-birth ceremony (attested)',
           workspace: platformWorkspace,
-          awaiting: 'POST /v2/workspaces/$platformWorkspace/birthHome',
+          awaiting: 'POST /v2/workspaces/$platformWorkspace$birthHomePath',
           timeout: phaseTimeout ?? _kInstallDeadline,
           onDiagnostic: onDiagnostic,
           run: () async {
@@ -938,7 +1000,7 @@ class NomosTestHarness {
               'epoch': 0,
             }, device.secret);
             final out =
-                await post('/v2/workspaces/$platformWorkspace/birthHome', {
+                await post('/v2/workspaces/$platformWorkspace$birthHomePath', {
               'owner': subject,
               'ownerKeyHash': device.keyHash,
               'frameworkHash': frameworkHash,