@githolon/dsl 0.36.0 → 0.37.0

package/dart/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.28.0
+
+- `NomosTestHarness` (`nomos_headless.dart`): ephemeral real-law fixtures — one call births a throwaway cloud workspace, deploys compiled `*.deploy.json` law, and hands out independent client replicas (`connect(clientId:)`) over the node runner. Identity defaults to the `githolon login --agent` session (`~/.holon/credentials.json`). Live-proven: birth → deploy → write on one replica → converge + typed read on another, 14s end-to-end.
+- HEADLESS TRANSPORT (`package:nomos_client/nomos_headless.dart`): `NodeRunnerTransport` — a `BridgeTransport` over the `@githolon/client` node runner (`runner/node-entry.mjs`) as a plain child process (NDJSON stdio). `flutter test` / `dart test` / CI drive the REAL githolon (byte-identical wasm, real ledger, real gate) through `NomosBridge` + the generated typed clients — no Flutter plugins, no WebView, no assets. Requires `node` on PATH + a resolvable `@githolon/client` (auto-resolved from the app's node_modules, or pass `entry:`). Proven end-to-end: connect → offerDirective → sync(admit) → typed query, and the same test green under both `dart test` and `flutter test`.
+
 ## 0.27.0
 
 - TYPED SNAPSHOT RECOVERY (corrupt local custody): `NomosBridge.connect(recover: true)` recovers IN-PLACE from a corrupt restoreFrom snapshot — salvages local-only authored writes (via the fallible `intents_above`, which stops at a missing-ancestor gap) + the DLQ, refolds FRESH from cloud, re-offers the salvaged work (deduped), re-queues the DLQ. The report rides `bridge.lastRecovery` = `{salvagedWrites, requeuedDeadLetters, unsalvageable}` — a write the current law refuses lands in `unsalvageable` + the DLQ (surfaced, never dropped). Also `holon.salvage()` / `holon.absorbSalvage()`. Closes the restoreFrom-leaves-read-model-empty case.

package/dart/lib/nomos_headless.dart

@@ -0,0 +1,19 @@
+/// The HEADLESS transport library — `dart:io` only, so it lives outside the main
+/// `package:nomos_client/nomos_client.dart` barrel (which stays web-safe).
+///
+/// ```dart
+/// import 'package:nomos_client/nomos_client.dart';
+/// import 'package:nomos_client/nomos_headless.dart';
+///
+/// final transport = await NodeRunnerTransport.start(resolveFrom: 'path/to/app');
+/// final bridge = NomosBridge(transport);
+/// await bridge.ready;
+/// await bridge.connect(cloud: ..., workspace: ..., clientId: 'test-runner');
+/// ```
+///
+/// The runner child process is the SAME `@githolon/client` every peer runs; the
+/// generated Dart clients drive it through [NomosBridge] exactly as in the app.
+library;
+
+export 'src/node_runner_transport.dart';
+export 'src/test_harness.dart';

package/dart/lib/src/node_runner_transport.dart

@@ -0,0 +1,125 @@
+// THE HEADLESS (NODE) TRANSPORT — a [BridgeTransport] over the `@githolon/client` node runner
+// (`runner/node-entry.mjs`), spawned as a plain child process speaking the ONE bridge protocol as
+// newline-delimited JSON on stdio. This is what lets `dart test` / `flutter test` / CI drive the REAL
+// githolon (the byte-identical wasm, the real ledger, the real gate) through [NomosBridge] and the
+// generated typed clients — no Flutter plugins, no WebView, no assets. The only environment requirement
+// is `node` on PATH plus a resolvable `@githolon/client` (any app that compiles domains already has both).
+//
+// This file is a PURE RELAY: no orchestration, no op knowledge — the protocol implementation lives in
+// createWebviewRunner (shared with the WebView path) and the orchestration in index.mjs, same as every peer.
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+import 'webview_bridge.dart' show BridgeTransport;
+
+class NodeRunnerTransport implements BridgeTransport {
+  final Process _proc;
+  final StreamController<Map<String, Object?>> _incoming =
+      StreamController<Map<String, Object?>>.broadcast();
+  final void Function(String line)? _onDiagnostic;
+  bool _disposed = false;
+
+  NodeRunnerTransport._(this._proc, this._onDiagnostic) {
+    _proc.stdout
+        .transform(utf8.decoder)
+        .transform(const LineSplitter())
+        .listen((line) {
+      final s = line.trim();
+      if (s.isEmpty) return;
+      Object? decoded;
+      try {
+        decoded = jsonDecode(s);
+      } catch (_) {
+        _diag('[nomos-node-runner stdout] $line');
+        return;
+      }
+      if (decoded is Map && !_incoming.isClosed) {
+        _incoming.add(decoded.cast<String, Object?>());
+      }
+    }, onDone: () {
+      if (!_disposed && !_incoming.isClosed) {
+        _incoming.addError(
+            StateError('the nomos node runner exited unexpectedly'));
+      }
+    });
+    _proc.stderr
+        .transform(utf8.decoder)
+        .transform(const LineSplitter())
+        .listen((line) => _diag('[nomos-node-runner] $line'));
+  }
+
+  void _diag(String line) {
+    final f = _onDiagnostic;
+    if (f != null) {
+      f(line);
+    } else {
+      stderr.writeln(line);
+    }
+  }
+
+  /// Spawn the node runner and return the connected transport. Wrap it in a
+  /// [NomosBridge] and `await bridge.ready` (the runner posts `{event:'ready'}`
+  /// on boot), then `connect(...)` as any other transport.
+  ///
+  /// [entry] — path to `node-entry.mjs`. When omitted it is resolved with
+  /// `require.resolve('@githolon/client/runner/node-entry.mjs')` from
+  /// [resolveFrom] (default: the current directory), i.e. the consuming app's
+  /// own `node_modules`.
+  static Future<NodeRunnerTransport> start({
+    String? entry,
+    String? resolveFrom,
+    String node = 'node',
+    Map<String, String>? environment,
+    void Function(String line)? onDiagnostic,
+  }) async {
+    final entryPath = entry ??
+        await _resolveEntry(node, resolveFrom ?? Directory.current.path);
+    final proc = await Process.start(
+      node,
+      [entryPath],
+      environment: environment,
+      workingDirectory: resolveFrom,
+    );
+    return NodeRunnerTransport._(proc, onDiagnostic);
+  }
+
+  static Future<String> _resolveEntry(String node, String from) async {
+    final r = await Process.run(
+      node,
+      ['-p', "require.resolve('@githolon/client/runner/node-entry.mjs')"],
+      workingDirectory: from,
+    );
+    final out = (r.stdout as String).trim();
+    if (r.exitCode != 0 || out.isEmpty) {
+      throw StateError(
+          'cannot resolve @githolon/client/runner/node-entry.mjs from $from — '
+          'is @githolon/client installed (npm install)? stderr: ${r.stderr}');
+    }
+    return out;
+  }
+
+  @override
+  Stream<Map<String, Object?>> get messages => _incoming.stream;
+
+  @override
+  void send(Map<String, Object?> message) {
+    if (_disposed) throw StateError('NodeRunnerTransport is disposed');
+    _proc.stdin.writeln(jsonEncode(message));
+  }
+
+  /// Tear down: stop the runner process and close the message stream.
+  Future<void> dispose() async {
+    if (_disposed) return;
+    _disposed = true;
+    try {
+      await _proc.stdin.close();
+    } catch (_) {}
+    _proc.kill(ProcessSignal.sigterm);
+    await _proc.exitCode.timeout(const Duration(seconds: 5), onTimeout: () {
+      _proc.kill(ProcessSignal.sigkill);
+      return -9;
+    });
+    await _incoming.close();
+  }
+}

package/dart/lib/src/test_harness.dart

@@ -0,0 +1,235 @@
+// NOMOS TEST HARNESS — ephemeral real-law fixtures for headless app tests. One call births a throwaway
+// workspace on the cloud, deploys the given compiled domain packages (`build/<name>.deploy.json`), and hands
+// out [NomosBridge]s over [NodeRunnerTransport] — the REAL githolon (byte-identical wasm, real ledger, real
+// gate) driven by the same generated Dart clients the app UI uses, under `flutter test` / `dart test` / CI.
+//
+// ```dart
+// final harness = await NomosTestHarness.ephemeral(
+//   deployJsonPaths: ['build/guestbook.deploy.json'],
+// );
+// final bridge = await harness.connect(clientId: 'test-runner');
+// final app = GuestbookClient(bridge); // the generated client — same one the app uses
+// ...
+// await harness.dispose();
+// ```
+//
+// Identity: a birth needs a principal. Pass [principal]/[authToken] explicitly, or the harness falls back to
+// the `githolon` CLI session (`~/.holon/credentials.json`, minted by `npx githolon login --agent`) — the same
+// self-onboarded verified identity the compile/deploy tooling uses. The token rides `x-nomos-auth` as proof;
+// its `sub` claim rides `x-nomos-principal` (the transitional bare claim the birth lane requires until kernel
+// birth-verify lands).
+//
+// The harness is HOST-LANE plumbing only (create + deploy are the open, kernel-gated cloud endpoints — the
+// same calls `githolon ws create` / `githolon deploy` make); everything after rides the one bridge protocol.
+// Workspaces are throwaway: there is no open destroy lane (reclaim is law-gated), so `dispose()` tears down
+// the local transports and leaves the ledger — name them uniquely (the default) and let them age out.
+import 'dart:convert';
+import 'dart:io';
+import 'dart:math';
+
+import 'node_runner_transport.dart';
+import 'webview_bridge.dart' show NomosBridge;
+
+class NomosTestHarnessException implements Exception {
+  final String message;
+  NomosTestHarnessException(this.message);
+  @override
+  String toString() => 'NomosTestHarnessException: $message';
+}
+
+class NomosTestHarness {
+  /// The cloud base URL the harness (and every bridge it connects) talks to.
+  final String cloud;
+
+  /// The ephemeral workspace name this harness birthed.
+  final String workspace;
+
+  final String? _principal;
+  final String? _authToken;
+  final String? _nodeEntry;
+  final String? _resolveFrom;
+  final void Function(String line)? _onDiagnostic;
+  final List<NodeRunnerTransport> _transports = [];
+  bool _disposed = false;
+
+  NomosTestHarness._(this.cloud, this.workspace, this._principal,
+      this._authToken, this._nodeEntry, this._resolveFrom, this._onDiagnostic);
+
+  /// Birth a throwaway workspace and deploy the given compiled domain packages into it.
+  ///
+  /// [deployJsonPaths] — the `build/<name>.deploy.json` files `nomos-compile` emits (deployed in order;
+  /// platform/framework law first when one domain's law depends on another's).
+  /// [workspace] — override the minted `test-<hex>` name (e.g. to reuse a workspace across a suite).
+  /// [principal]/[authToken] — the identity the workspace is born for; defaults to the `githolon` CLI
+  /// session (`~/.holon/credentials.json`).
+  /// [nodeEntry]/[resolveFrom] — forwarded to [NodeRunnerTransport.start].
+  static Future<NomosTestHarness> ephemeral({
+    List<String> deployJsonPaths = const [],
+    String cloud = 'https://nomos.captainapp.co.uk',
+    String? workspace,
+    String? principal,
+    String? authToken,
+    String? nodeEntry,
+    String? resolveFrom,
+    void Function(String line)? onDiagnostic,
+  }) async {
+    final id = _identity(principal, authToken);
+    final ws = workspace ?? 'test-${_hex(12)}';
+    final harness = NomosTestHarness._(_stripSlash(cloud), ws, id.principal,
+        id.authToken, nodeEntry, resolveFrom, onDiagnostic);
+    await harness._create();
+    for (final p in deployJsonPaths) {
+      await harness.deployLaw(p);
+    }
+    return harness;
+  }
+
+  static String _brief(String s) => s.length > 600 ? '${s.substring(0, 600)}…[+${s.length - 600} chars]' : s;
+
+  /// Deploy one more compiled package (`<name>.deploy.json`) into the workspace — e.g. a law evolve mid-test.
+  Future<void> deployLaw(String deployJsonPath) async {
+    final f = File(deployJsonPath);
+    if (!f.existsSync()) {
+      throw NomosTestHarnessException(
+          'deploy json not found: $deployJsonPath — run `npx githolon compile` first');
+    }
+    final r = await _post('/v2/workspaces/$workspace/domains',
+        body: await f.readAsString(), contentType: 'application/json');
+    if (r.$1 >= 300 || !(r.$2['ok'] == true)) {
+      throw NomosTestHarnessException(
+          'deploy of $deployJsonPath to $workspace refused (${r.$1}): ${_brief(r.$3)}');
+    }
+  }
+
+  /// Spawn a fresh runner + bridge connected to the harness workspace. Each call is an independent
+  /// client replica (own clientId → own session branch), so multi-client convergence is testable.
+  Future<NomosBridge> connect({
+    String clientId = 'test-runner',
+    String? authToken,
+    String? authorSecret,
+    bool allowUnborn = false,
+  }) async {
+    if (_disposed) throw StateError('harness is disposed');
+    final transport = await NodeRunnerTransport.start(
+      entry: _nodeEntry,
+      resolveFrom: _resolveFrom,
+      onDiagnostic: _onDiagnostic,
+    );
+    _transports.add(transport);
+    final bridge = NomosBridge(transport);
+    await bridge.ready.timeout(const Duration(seconds: 30));
+    await bridge.connect(
+      cloud: cloud,
+      workspace: workspace,
+      clientId: clientId,
+      authToken: authToken ?? _authToken,
+      authorSecret: authorSecret,
+      allowUnborn: allowUnborn,
+    );
+    return bridge;
+  }
+
+  /// Tear down every runner this harness spawned. The throwaway workspace's ledger stays on the cloud
+  /// (there is no open destroy lane — reclaim is law-gated); its unique name keeps it inert.
+  Future<void> dispose() async {
+    if (_disposed) return;
+    _disposed = true;
+    for (final t in _transports) {
+      await t.dispose();
+    }
+    _transports.clear();
+  }
+
+  // ── host-lane plumbing ──
+
+  Future<void> _create() async {
+    final r = await _post('/v2/workspaces/$workspace');
+    if (r.$1 >= 300 || !(r.$2['ok'] == true)) {
+      throw NomosTestHarnessException(
+          'workspace birth for $workspace refused (${r.$1}): ${_brief(r.$3)} — '
+          'a birth needs a principal (npx githolon login --agent, or pass principal:/authToken:)');
+    }
+  }
+
+  Future<(int, Map<String, Object?>, String)> _post(String path,
+      {String? body, String? contentType}) async {
+    final client = HttpClient();
+    try {
+      final req = await client.postUrl(Uri.parse('$cloud$path'));
+      if (_authToken != null) req.headers.set('x-nomos-auth', _authToken);
+      if (_principal != null) req.headers.set('x-nomos-principal', _principal);
+      if (contentType != null) {
+        req.headers.contentType = ContentType.parse('$contentType; charset=utf-8');
+      }
+      if (body != null) req.add(utf8.encode(body));
+      final res = await req.close();
+      final text = await res.transform(utf8.decoder).join();
+      Map<String, Object?> decoded = const {};
+      try {
+        final d = jsonDecode(text);
+        if (d is Map) decoded = d.cast<String, Object?>();
+      } catch (_) {}
+      return (res.statusCode, decoded, text);
+    } finally {
+      client.close();
+    }
+  }
+
+  static ({String? principal, String? authToken}) _identity(
+      String? principal, String? authToken) {
+    var p = principal;
+    var t = authToken;
+    if (p == null && t == null) {
+      final creds = _holonCreds();
+      p = creds.principal;
+      t = creds.authToken;
+    }
+    // the token's own `sub` claim is the transitional bare principal claim the birth lane requires.
+    p ??= t != null ? _jwtSub(t) : null;
+    if (p == null && t == null) {
+      throw NomosTestHarnessException(
+          'no identity for the workspace birth — run `npx githolon login --agent` '
+          '(the harness reads ~/.holon/credentials.json) or pass principal:/authToken:');
+    }
+    return (principal: p, authToken: t);
+  }
+
+  static ({String? principal, String? authToken}) _holonCreds() {
+    try {
+      final home = Platform.environment['HOME'] ??
+          Platform.environment['USERPROFILE'] ??
+          '';
+      final f = File('$home/.holon/credentials.json');
+      if (!f.existsSync()) return (principal: null, authToken: null);
+      final d = jsonDecode(f.readAsStringSync()) as Map;
+      final session = (d['session'] as Map?)?.cast<String, Object?>();
+      return (
+        principal: session?['uid']?.toString() ?? d['principal']?.toString(),
+        authToken: session?['accessToken']?.toString(),
+      );
+    } catch (_) {
+      return (principal: null, authToken: null);
+    }
+  }
+
+  static String? _jwtSub(String token) {
+    final parts = token.split('.');
+    if (parts.length != 3) return null;
+    try {
+      final d = jsonDecode(
+          utf8.decode(base64Url.decode(base64Url.normalize(parts[1])))) as Map;
+      final sub = d['sub'];
+      return sub is String && sub.isNotEmpty ? sub : null;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  static String _stripSlash(String s) =>
+      s.endsWith('/') ? s.substring(0, s.length - 1) : s;
+
+  static String _hex(int n) {
+    final rng = Random.secure();
+    return List.generate(n, (_) => rng.nextInt(16).toRadixString(16)).join();
+  }
+}

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

package/dart/test/node_runner_transport_test.dart

@@ -0,0 +1,74 @@
+// The headless transport against the REAL node runner (`cloud/web-client/runner/node-entry.mjs`):
+// protocol round-trip through NomosBridge without touching the cloud — ready handshake, typed refusal
+// on a pre-connect op, unknown-op error. The live connect path is covered by the env-gated smoke below.
+@TestOn('vm')
+library;
+
+import 'dart:io';
+
+import 'package:nomos_client/nomos_client.dart';
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+String _repoEntry() {
+  // In-repo the runner lives beside us; consumers resolve it from node_modules instead.
+  final here = Directory.current.path;
+  final p = '$here/../../cloud/web-client/runner/node-entry.mjs';
+  if (!File(p).existsSync()) {
+    throw StateError('node-entry.mjs not found at $p');
+  }
+  return p;
+}
+
+void main() {
+  late NodeRunnerTransport transport;
+  late NomosBridge bridge;
+
+  setUp(() async {
+    transport = await NodeRunnerTransport.start(entry: _repoEntry());
+    bridge = NomosBridge(transport);
+  });
+
+  tearDown(() async {
+    await transport.dispose();
+  });
+
+  test('posts the ready handshake', () async {
+    await bridge.ready.timeout(const Duration(seconds: 15));
+  });
+
+  test('a pre-connect op answers a typed bridge error', () async {
+    await bridge.ready.timeout(const Duration(seconds: 15));
+    await expectLater(
+      bridge.head(),
+      throwsA(isA<NomosBridgeError>().having((e) => e.message, 'message',
+          contains('not connected'))),
+    );
+  });
+
+  test('requests are id-correlated (two in flight)', () async {
+    await bridge.ready.timeout(const Duration(seconds: 15));
+    final a = bridge.head().then((_) => 'ok', onError: (_) => 'err');
+    final b = bridge.metrics().then((_) => 'ok', onError: (_) => 'err');
+    expect(await a, 'err');
+    expect(await b, 'err');
+  });
+
+  test(
+    'LIVE smoke: connect + query against a real workspace',
+    skip: Platform.environment['NOMOS_HEADLESS_E2E'] == null
+        ? 'set NOMOS_HEADLESS_E2E=<workspace> (and optionally NOMOS_CLOUD) to run'
+        : null,
+    () async {
+      final ws = Platform.environment['NOMOS_HEADLESS_E2E']!;
+      final cloud = Platform.environment['NOMOS_CLOUD'] ??
+          'https://nomos.captainapp.co.uk';
+      await bridge.ready.timeout(const Duration(seconds: 15));
+      await bridge.connect(
+          cloud: cloud, workspace: ws, clientId: 'headless-test');
+      final head = await bridge.head();
+      expect(head, isNotEmpty);
+    },
+    timeout: const Timeout(Duration(minutes: 3)),
+  );
+}

package/dart/test/test_harness_test.dart

@@ -0,0 +1,70 @@
+// NomosTestHarness: unit coverage for the identity/jwt plumbing, plus the LIVE ephemeral fixture loop
+// (birth a throwaway ws → deploy real law → two client replicas → write on one, converge on the other).
+// The live test needs a `githolon login --agent` session (or NOMOS_PRINCIPAL) and is opt-in via NOMOS_LIVE=1.
+@TestOn('vm')
+library;
+
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+String _repoEntry() =>
+    '${Directory.current.path}/../../cloud/web-client/runner/node-entry.mjs';
+
+String _guestbookDeployJson() =>
+    '${Directory.current.path}/../../examples/guestbook/build/guestbook.deploy.json';
+
+void main() {
+  test('ephemeral without any identity refuses with a named remedy', () async {
+    // isolate from a real ~/.holon by pointing HOME at an empty dir
+    // (can't re-env the current isolate — so only run when no creds file exists).
+    final home = Platform.environment['HOME'] ?? '';
+    if (File('$home/.holon/credentials.json').existsSync()) {
+      markTestSkipped('a githolon session exists — the fallback would find it');
+      return;
+    }
+    await expectLater(
+      NomosTestHarness.ephemeral(),
+      throwsA(isA<NomosTestHarnessException>()),
+    );
+  });
+
+  test(
+    'LIVE: ephemeral fixture — birth, deploy law, write on one replica, read it on another',
+    skip: Platform.environment['NOMOS_LIVE'] != '1'
+        ? 'set NOMOS_LIVE=1 (needs a githolon login --agent session)'
+        : null,
+    () async {
+      final harness = await NomosTestHarness.ephemeral(
+        deployJsonPaths: [_guestbookDeployJson()],
+        nodeEntry: _repoEntry(),
+      );
+      try {
+        final writer = await harness.connect(clientId: 'writer');
+        final reader = await harness.connect(clientId: 'reader');
+        await writer.offerDirective(
+            domain: 'guestbook',
+            directiveId: 'signGuestbook',
+            payload: {
+              'author': 'harness',
+              'message': 'ephemeral fixture green',
+              'mood': 'delighted',
+              'signedAt': DateTime.now().toUtc().toIso8601String(),
+            });
+        await writer.sync(admit: true);
+        await reader.sync(admit: false);
+        final rows = await reader.query('entriesByAuthor', {'author': 'harness'});
+        expect(rows, hasLength(1));
+        expect(
+            (rows.first['data'] as Map)['message'], 'ephemeral fixture green');
+        stdout.writeln(
+            'live harness green: ws=${harness.workspace} rows=${jsonEncode(rows.first['data'])}');
+      } finally {
+        await harness.dispose();
+      }
+    },
+    timeout: const Timeout(Duration(minutes: 5)),
+  );
+}

package/package.json

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