@githolon/dsl 0.46.0 → 0.48.0

package/dart/lib/src/test_harness.dart

@@ -1,31 +1,37 @@
-// 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.
+// NOMOS TEST HARNESS — an EPHEMERAL, FULLY-OFFLINE real-law fixture for headless app tests. One call
+// installs a tenant's compiled law into a FRESH LOCAL workspace (no cloud contact, ever), boots the REAL
+// githolon (the byte-identical wasm, the real ledger, the real gate) over [NodeRunnerTransport], and hands
+// out a [NomosBridge] the generated Dart clients drive — the SAME surface the app UI uses — under
+// `flutter test` / `dart test` / CI.
 //
 // ```dart
 // final harness = await NomosTestHarness.ephemeral(
 //   deployJsonPaths: ['build/guestbook.deploy.json'],
+//   registerTearDown: addTearDown,   // auto-disposes when the test ends (see below)
 // );
-// final bridge = await harness.connect(clientId: 'test-runner');
-// final app = GuestbookClient(bridge); // the generated client — same one the app uses
-// ...
-// await harness.dispose();
+// final app = guestbookClient(harness.bridge); // the generated client — same one the app uses
+// await app.signGuestbook(author: 'ada', message: 'hi', mood: 'happy', signedAt: ...);
+// final rows = await app.entriesByAuthor(author: 'ada');
+// await harness.dispose();   // DETERMINISTIC teardown (also auto-fired via registerTearDown)
 // ```
 //
-// 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).
+// HOW IT STAYS OFFLINE. Two node children, both talking only to the local disk:
+//   1. `offline-install.mjs` runs the PROVEN offline install lane (`githolon proof`'s adapter engine) —
+//      genesis → framework controller → each tenant package's `installDomain`, folded through the ONE gate —
+//      and serializes the workspace tree to a snapshot in a fresh temp dir.
+//   2. the node runner (`node-entry.mjs`) boots in `NOMOS_OFFLINE=1` mode: it serves the runtime wasm from the
+//      local cache (`~/.holon/runtime`, filled by any warm `githolon` run) and boots the holon from that
+//      snapshot (`restoreFrom`). Every other URL is REFUSED — a stray fetch fails loudly, never reaches the net.
 //
-// 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.
+// PREREQUISITES (documented so a failure is legible): `node` on PATH; a resolvable
+// `@githolon/client/runner/node-entry.mjs`; and a warm `~/.holon/runtime` cache (holon.wasm + packages.json —
+// one `githolon` run fills it). All local; no network at test time.
+//
+// PACKAGING NOTE: `offline-install.mjs` imports the adapter engine, which today lives beside the in-repo
+// runner. For a PUBLISHED harness this install belongs behind a `githolon` subcommand (the CLI already
+// bundles the engine + this exact sequence in `proof_offline`); [installHelper] is the one seam to repoint.
 import 'dart:convert';
 import 'dart:io';
-import 'dart:math';
 
 import 'node_runner_transport.dart';
 import 'webview_bridge.dart' show NomosBridge;
@@ -38,198 +44,199 @@ class NomosTestHarnessException implements Exception {
 }
 
 class NomosTestHarness {
-  /// The cloud base URL the harness (and every bridge it connects) talks to.
-  final String cloud;
+  /// The connected bridge — hand it to the generated typed clients (the same surface the app UI uses).
+  final NomosBridge bridge;
 
-  /// The ephemeral workspace name this harness birthed.
+  /// The local workspace name the law was installed into.
   final String workspace;
 
-  final String? _principal;
-  final String? _authToken;
-  final String? _nodeEntry;
-  final String? _resolveFrom;
+  final NodeRunnerTransport _transport;
+  final Directory _workdir;
   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);
+  NomosTestHarness._(this.bridge, this.workspace, this._transport, this._workdir,
+      this._onDiagnostic);
 
-  /// Birth a throwaway workspace and deploy the given compiled domain packages into it.
+  /// Install [deployJsonPaths] into a fresh LOCAL workspace and boot a bridge over it — NO cloud contact.
   ///
-  /// [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].
+  /// [deployJsonPaths] — the `build/<name>.deploy.json` files `nomos-compile` emits (installed in order;
+  /// framework/platform law before a domain that depends on it).
+  /// [workspace] — the local workspace name (default `test-ws`; law-only, never leaves the machine).
+  /// [runtimeDir] — the runtime cache (default `~/.holon/runtime`); must hold `holon.wasm` + `packages.json`.
+  /// [nodeEntry] — path to `node-entry.mjs`; when omitted it is resolved from [resolveFrom] via
+  /// `require.resolve('@githolon/client/runner/node-entry.mjs')`.
+  /// [installHelper] — path to `offline-install.mjs`; defaults to the file beside [nodeEntry].
+  /// [registerTearDown] — pass the test framework's `addTearDown` to auto-[dispose] when the test ends
+  /// (feature-detecting `package:test` from a library is not clean in Dart, so this is explicit and safe).
+  /// [autoTearDown] — when true (default) and [registerTearDown] is given, registers [dispose] as a teardown.
   static Future<NomosTestHarness> ephemeral({
-    List<String> deployJsonPaths = const [],
-    String cloud = 'https://nomos.captainapp.co.uk',
-    String? workspace,
-    String? principal,
-    String? authToken,
+    required List<String> deployJsonPaths,
+    String workspace = 'test-ws',
+    String clientId = 'test-runner',
+    String? runtimeDir,
     String? nodeEntry,
+    String? installHelper,
     String? resolveFrom,
+    String node = 'node',
+    bool autoTearDown = true,
+    void Function(Future<void> Function())? registerTearDown,
     void Function(String line)? onDiagnostic,
+    Duration readyTimeout = const Duration(seconds: 30),
   }) 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()) {
+    if (deployJsonPaths.isEmpty) {
       throw NomosTestHarnessException(
-          'deploy json not found: $deployJsonPath — run `npx githolon compile` first');
+          'no deployJsonPaths — pass the build/<name>.deploy.json `npx githolon compile` emits');
     }
-    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)}');
+    final entry = nodeEntry ??
+        await _resolveEntry(node, resolveFrom ?? Directory.current.path);
+    final helper = installHelper ??
+        '${File(entry).parent.path}/offline-install.mjs';
+
+    // A FRESH temp dir per harness — the snapshot + any transient runner state live here and nowhere else,
+    // so dispose() leaves nothing behind.
+    final workdir = await Directory.systemTemp.createTemp('nomos-harness-');
+    // Total-ordered teardown even on a mid-setup failure: build the transport lazily and clean up on throw.
+    NodeRunnerTransport? transport;
+    try {
+      final snapshot = '${workdir.path}/snapshot.bin';
+      await _runInstall(
+          node: node,
+          helper: helper,
+          deployJsonPaths: deployJsonPaths,
+          workspace: workspace,
+          snapshot: snapshot,
+          runtimeDir: runtimeDir,
+          onDiagnostic: onDiagnostic);
+
+      transport = await NodeRunnerTransport.start(
+        entry: entry,
+        resolveFrom: resolveFrom,
+        node: node,
+        environment: {
+          'NOMOS_OFFLINE': '1',
+          'NOMOS_OFFLINE_RESTORE': snapshot,
+          if (runtimeDir != null) 'NOMOS_OFFLINE_RUNTIME': runtimeDir,
+        },
+        onDiagnostic: onDiagnostic,
+      );
+      final bridge = NomosBridge(transport);
+      await bridge.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(
+        cloud: 'https://offline.invalid', // ignored: the offline runner serves everything locally
+        workspace: workspace,
+        clientId: clientId,
+        allowUnborn: true,
+      );
+      final harness =
+          NomosTestHarness._(bridge, workspace, transport, workdir, onDiagnostic);
+      if (autoTearDown && registerTearDown != null) {
+        registerTearDown(harness.dispose);
+      }
+      return harness;
+    } catch (_) {
+      // Setup failed — tear down deterministically so nothing is left running or on disk.
+      if (transport != null) {
+        try {
+          await transport.dispose();
+        } catch (_) {}
+      }
+      try {
+        await workdir.delete(recursive: true);
+      } catch (_) {}
+      rethrow;
     }
   }
 
-  /// 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.
+  /// Deterministic, idempotent, total-ordered teardown: stop the runner (SIGTERM → 5s deadline → SIGKILL,
+  /// via [NodeRunnerTransport.dispose]), then delete the temp dir. Safe to call twice; safe to call after a
+  /// failed setup. Nothing left running, nothing left on disk.
   Future<void> dispose() async {
     if (_disposed) return;
     _disposed = true;
-    for (final t in _transports) {
-      await t.dispose();
+    try {
+      await _transport.dispose();
+    } catch (e) {
+      _diag('[nomos-test-harness] transport dispose error (continuing to temp-dir cleanup): $e');
     }
-    _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:)');
+    try {
+      if (await _workdir.exists()) await _workdir.delete(recursive: true);
+    } catch (e) {
+      _diag('[nomos-test-harness] temp-dir cleanup error: $e');
     }
   }
 
-  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();
+  void _diag(String line) {
+    final f = _onDiagnostic;
+    if (f != null) {
+      f(line);
+    } else {
+      stderr.writeln(line);
     }
   }
 
-  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;
+  // ── offline install (a short-lived node child; produces the restore snapshot) ──
+
+  static Future<void> _runInstall({
+    required String node,
+    required String helper,
+    required List<String> deployJsonPaths,
+    required String workspace,
+    required String snapshot,
+    String? runtimeDir,
+    void Function(String line)? onDiagnostic,
+  }) async {
+    if (!File(helper).existsSync()) {
+      throw NomosTestHarnessException(
+          'offline-install helper not found at $helper — pass installHelper: explicitly '
+          '(it ships beside node-entry.mjs)');
+    }
+    final r = await Process.run(node, [
+      helper,
+      '--deploy', deployJsonPaths.join(','),
+      '--workspace', workspace,
+      '--out', snapshot,
+      if (runtimeDir != null) ...['--runtime', runtimeDir],
+    ]);
+    final err = (r.stderr as String).trim();
+    if (err.isNotEmpty) {
+      for (final line in err.split('\n')) {
+        (onDiagnostic ?? stderr.writeln)('[offline-install] $line');
+      }
     }
-    // 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) {
+    if (r.exitCode != 0) {
       throw NomosTestHarnessException(
-          'no identity for the workspace birth — run `npx githolon login --agent` '
-          '(the harness reads ~/.holon/credentials.json) or pass principal:/authToken:');
+          'offline law install failed (exit ${r.exitCode}): ${err.isEmpty ? "(no stderr)" : err}');
     }
-    return (principal: p, authToken: t);
-  }
-
-  static ({String? principal, String? authToken}) _holonCreds() {
+    // The helper prints one JSON line on success; verify it before spawning the runner.
+    final out = (r.stdout as String).trim();
+    final last = out.isEmpty ? '' : out.split('\n').last;
+    Map<String, Object?> decoded = const {};
     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);
+      final d = jsonDecode(last);
+      if (d is Map) decoded = d.cast<String, Object?>();
+    } catch (_) {}
+    if (decoded['ok'] != true || !File(snapshot).existsSync()) {
+      throw NomosTestHarnessException(
+          'offline law install produced no snapshot (stdout: ${out.isEmpty ? "(empty)" : out})');
     }
   }
 
-  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 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 NomosTestHarnessException(
+          'cannot resolve @githolon/client/runner/node-entry.mjs from $from — '
+          'is @githolon/client installed (npm install)? Pass nodeEntry: to override. stderr: ${r.stderr}');
     }
-  }
-
-  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();
+    return out;
   }
 }

package/dart/test/errors_test.dart

@@ -0,0 +1,77 @@
+// NOMOS — TYPED ERROR MINTING (§7 structured runtime error DX). `nomosErrorFromInfo` routes a structured
+// `NomosErrorInfo` to the MOST SPECIFIC typed class by stable code prefix, so an app's `errorBuilder` branches
+// on `is` and reads structured fields (not scraped prose). Every typed error still extends `NomosBridgeError`.
+import 'package:nomos_client/nomos_client.dart';
+import 'package:test/test.dart';
+
+NomosErrorInfo info(String code, {Map<String, Object?> attrs = const {}, String? workspace, String? operation}) =>
+    NomosErrorInfo(code: code, message: 'refused', workspace: workspace, operation: operation, attributes: attrs);
+
+void main() {
+  test('law.* mints LawMismatchError with both sides + compat verdict + the exact message', () {
+    final e = nomosErrorFromInfo(info(
+      'nomos.law.mismatch',
+      workspace: 'ws-1',
+      operation: 'signGuestbook',
+      attrs: {
+        'nomos.law.generatedFor': 'aaaa',
+        'nomos.law.workspaceRuns': 'bbbb',
+        'nomos.law.structurallyCompatible': false,
+        'nomos.law.incompatibleMember': 'mood',
+      },
+    ));
+    expect(e, isA<NomosBridgeError>()); // still catchable generically
+    expect(e, isA<LawMismatchError>());
+    final m = e as LawMismatchError;
+    expect(m.code, 'nomos.law.mismatch');
+    expect(m.workspace, 'ws-1');
+    expect(m.generatedFor, 'aaaa');
+    expect(m.workspaceRuns, 'bbbb');
+    expect(m.operation, 'signGuestbook');
+    expect(m.structurallyCompatible, isFalse);
+    expect(m.incompatibleMember, 'mood');
+    expect(m.recommendedAction, NomosRecommendedAction.recompileClient);
+    expect(
+      m.mismatchMessage,
+      'client generated for law aaaa, workspace runs law bbbb; structurally incompatible on mood — '
+      'recompile the client (githolon compile / npx nomos-compile) against the deployed law',
+    );
+  });
+
+  test('law.* compatible verdict says "proceeding"', () {
+    final m = nomosErrorFromInfo(info('nomos.law.drift', attrs: {
+      'nomos.law.generatedFor': 'aaaa',
+      'nomos.law.workspaceRuns': 'bbbb',
+      'nomos.law.structurallyCompatible': true,
+    })) as LawMismatchError;
+    expect(m.mismatchMessage, startsWith('client generated for law aaaa, workspace runs law bbbb; structurally compatible — proceeding —'));
+  });
+
+  test('auth.* mints AuthError with reauth as the remedy', () {
+    final e = nomosErrorFromInfo(info('nomos.auth.issuer_mismatch', workspace: 'ws-1', attrs: {'nomos.auth.issuer': 'https://evil'}));
+    expect(e, isA<AuthError>());
+    final a = e as AuthError;
+    expect(a.code, 'nomos.auth.issuer_mismatch');
+    expect(a.issuer, 'https://evil');
+    expect(a.recommendedAction, NomosRecommendedAction.reauth);
+  });
+
+  test('load.* mints LoadError carrying the artifact + source URL', () {
+    final e = nomosErrorFromInfo(info('nomos.load.wasm_fetch_failed', attrs: {
+      'nomos.load.artifact': 'holon.wasm',
+      'nomos.load.sourceUrl': 'https://nomos/runtime/holon.wasm',
+    }));
+    expect(e, isA<LoadError>());
+    final l = e as LoadError;
+    expect(l.artifact, 'holon.wasm');
+    expect(l.sourceUrl, 'https://nomos/runtime/holon.wasm');
+    expect(l.recommendedAction, NomosRecommendedAction.retry);
+  });
+
+  test('custody.* still mints CustodyError (unchanged), unknown codes stay generic', () {
+    expect(nomosErrorFromInfo(info('nomos.custody.missing_object')), isA<CustodyError>());
+    final g = nomosErrorFromInfo(info('nomos.bridge.error'));
+    expect(g, isA<NomosBridgeError>());
+    expect(g, isNot(isA<LawMismatchError>()));
+  });
+}