@githolon/dsl 0.73.0 → 0.75.0

package/dart/test/cluster_device_keyed_acceptance_test.dart

@@ -0,0 +1,108 @@
+// CO2'S ACCEPTANCE (verbatim, 2026-07): `NomosTestHarness.cluster(deviceKeyed: …)` re-opens the keyed
+// session (keygen → keyed reconnect) and MUST NEVER hang — the reported wedge was phase 3b, the second
+// `connect` on an already-open session. Acceptance:
+//   1. cluster(..., deviceKeyed: {workspace}) completes           (co2's exact shape: 4 sessions, one
+//      deviceKeyed, colon-namespaced workspace names)
+//   2. devicePublicKey(workspace) is populated
+//   3. a colocated attested read succeeds (served + SIGNED with the device key the re-open installed)
+//   4. harness disposal completes without being killed
+// Phase diagnostics (their ask 5) are asserted too: 3b logs enter/exit for keygen + keyed reconnect.
+@TestOn('vm')
+@Timeout(Duration(minutes: 3))
+library;
+
+import 'dart:io';
+
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+String get _root => '${Directory.current.path}/../..';
+String get _repoEntry => '$_root/cloud/web-client/runner/node-entry.mjs';
+String get _catDeploy => '$_root/bench/scale/fixtures/catalogue-src/build/cat.deploy.json';
+String get _estateDeploy => '$_root/bench/scale/fixtures/catalogue-reader/build/estate.deploy.json';
+String get _runtimeDir => '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+
+String? _missingPrereq() {
+  if (!File(_repoEntry).existsSync()) return 'in-repo runner not found at $_repoEntry';
+  for (final p in [_catDeploy, _estateDeploy]) {
+    if (!File(p).existsSync()) return 'missing fixture $p (compile bench/scale/fixtures first)';
+  }
+  if (!File('$_runtimeDir/holon.wasm').existsSync() ||
+      !File('$_runtimeDir/packages.json').existsSync()) {
+    return 'warm ~/.holon/runtime first (run any `githolon` command once)';
+  }
+  return null;
+}
+
+void main() {
+  test('cluster(deviceKeyed) completes: keyed re-open, device key populated, colocated attested read, disposal',
+      () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+
+    const keyed = 'catalogue:test-catalogue';
+    final log = <String>[];
+    // 1. cluster construction with a deviceKeyed workspace COMPLETES (the reported hang was here).
+    final harness = await NomosTestHarness.cluster(
+      workspaces: {
+        keyed: [_catDeploy],
+        'estate:a': [_estateDeploy],
+        'estate:b': [_estateDeploy],
+        'estate:c': [_estateDeploy],
+      },
+      deviceKeyed: {keyed},
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      onDiagnostic: log.add,
+    );
+    try {
+      expect(harness.sessions.toSet(),
+          {keyed, 'estate:a', 'estate:b', 'estate:c'});
+
+      // 2. devicePublicKey is populated for the keyed session.
+      final public = harness.devicePublicKey(keyed);
+      expect(public, isNotNull);
+      expect(public, isNotEmpty,
+          reason: 'the 3b keygen public half must be recorded on the harness');
+
+      // ask 5 — phase diagnostics: 3b logs enter AND exit for keygen + keyed reconnect.
+      expect(log.any((l) => l.contains('3b: device keygen')), isTrue,
+          reason: 'phase 3b keygen must log');
+      expect(log.any((l) => l.contains("3b: keyed reconnect of '$keyed'") && l.contains('…')),
+          isTrue, reason: 'phase 3b reconnect must log its enter line');
+      expect(log.any((l) => l.contains("3b: keyed reconnect of '$keyed'") && l.contains('done')),
+          isTrue, reason: 'phase 3b reconnect must log its exit line');
+
+      // 3. a COLOCATED ATTESTED READ succeeds, signed with the device key the re-open installed
+      //    (no attestorSecret injected — the source session signs with its connect authorSecret).
+      final cat = harness.session(keyed);
+      final seeded = await cat.offerCreates(
+        domain: 'cat',
+        directiveId: 'listCatalogue',
+        payload: {
+          'listingId': 'L-1',
+          'title': 'Walnut desk',
+          'priceGbp': '900',
+          'listedAt': '2026-07-11T00:00:00Z',
+        },
+        actor: 'user:seller',
+      );
+      expect(seeded.head, isNotEmpty);
+      final served = await harness.session('estate:a').attestedRead(
+        from: keyed,
+        queryId: 'listingById',
+        args: {'listingId': 'L-1'},
+      );
+      final entry = (served['entry'] as Map).cast<String, Object?>();
+      final attestation = (entry['attestation'] as Map).cast<String, Object?>();
+      expect((attestation['public_key'] ?? '').toString(), public,
+          reason: 'the colocated read is signed by the re-opened session device key');
+    } finally {
+      // 4. disposal completes (the harness deadline guarantees it can never wedge the test runner).
+      await harness.dispose();
+    }
+  });
+}

package/dart/test/dlq_session_surface_test.dart

@@ -0,0 +1,203 @@
+// THE DEAD-LETTER QUEUE FROM THE DART SESSION SURFACE (task #86 gap 7). The DLQ promise —
+// "refused-but-legitimate work is NEVER lost" — driven end-to-end through the Dart bridge:
+// real authored work (its full intent bytes, read back via the production `salvage` lane) is
+// parked as a dead letter on a workspace whose law cannot merge it (the exact shape a domain
+// rejection parks — same `deadLetter()` path the converge/recover lanes use), then:
+//   deadLetters() surfaces it with provenance → retry REFUSES while the law is absent (the
+//   entry stays, error refreshed) → the law fix ships (nomos/installDomain) → retry ADMITS and
+//   the work lands, readable → a second entry is explicitly DISCARDED → the queue drains.
+// Fully offline (local-only sessions) — which is itself a regression: retryDeadLetter/
+// absorbSalvage used to throw "no remote main" on a local-only holon (fixed with this test).
+@TestOn('vm')
+library;
+
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+String get _root => '${Directory.current.path}/../..';
+String get _repoEntry => '$_root/cloud/web-client/runner/node-entry.mjs';
+String get _geoDeploy => '$_root/bench/scale/fixtures/estate-geo/build/estate-geo.deploy.json';
+String get _docsDeploy => '$_root/bench/scale/fixtures/surfaced/build/surfaced.deploy.json';
+String get _runtimeDir =>
+    Platform.environment['NOMOS_DART_RUNTIME'] ??
+    '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+
+String? _missingPrereq() {
+  if (!File(_repoEntry).existsSync()) return 'in-repo runner not found at $_repoEntry';
+  for (final e in {
+    _geoDeploy: 'bench/scale/fixtures/estate-geo',
+    _docsDeploy: 'bench/scale/fixtures/surfaced',
+  }.entries) {
+    if (!File(e.key).existsSync()) {
+      return 'missing fixture ${e.key} — compile it: (cd ${e.value} && node ../../../../dsl/compile_package.mjs)';
+    }
+  }
+  if (!File('$_runtimeDir/holon.wasm').existsSync() ||
+      !File('$_runtimeDir/packages.json').existsSync()) {
+    return 'warm ~/.holon/runtime first (run any `githolon` command once)';
+  }
+  return null;
+}
+
+Future<T> _leg<T>(String name, Future<T> Function() body) async {
+  final sw = Stopwatch()..start();
+  // ignore: avoid_print
+  print('▶ DLQ $name …');
+  try {
+    final r = await body();
+    // ignore: avoid_print
+    print('✔ DLQ $name (${sw.elapsedMilliseconds}ms)');
+    return r;
+  } catch (e, st) {
+    throw TestFailure('DLQ $name FAILED after ${sw.elapsedMilliseconds}ms:\n$e\n$st');
+  }
+}
+
+void main() {
+  test('DLQ: park → surface → refused retry → law fix → retry admits → discard drains',
+      () async {
+    final missing = _missingPrereq();
+    if (missing != null) {
+      markTestSkipped(missing);
+      return;
+    }
+    final harness = await NomosTestHarness.cluster(
+      workspaces: {
+        'writer': [_geoDeploy], // holds the estate law — where the work is authored
+        'app': [_docsDeploy], // the jammed workspace — NO estate law yet
+      },
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      phaseTimeout: const Duration(seconds: 120),
+    );
+    try {
+      final writer = harness.session('writer');
+      final app = harness.session('app');
+      final geoHash = harness.lawHashes('writer').first;
+
+      // ── LEG 1: author REAL work under the estate law, and read its full intent bytes back
+      //    through the production salvage lane. ──
+      final work = await _leg('leg 1: author two writes + salvage their intent bytes', () async {
+        Future<void> place(String name) => writer.offerOutcome(
+              domain: 'estate',
+              directiveId: 'placeSite',
+              payload: {
+                'name': name,
+                'point': {
+                  'type': 'Point',
+                  'coordinates': [-2.24, 53.48]
+                },
+              },
+              actor: 'user:marta',
+              domainHash: geoHash,
+            );
+        await place('a day of work I refuse to lose');
+        await place('the second day');
+        final s = await writer.salvage();
+        final pending = ((s['pendingWrites'] as List?) ?? const [])
+            .whereType<Map>()
+            .map((m) => m.cast<String, Object?>())
+            .where((w) {
+          try {
+            final doc =
+                jsonDecode(utf8.decode(base64Decode(w['intentB64'].toString()))) as Map;
+            return (doc['payload'] as Map?)?['domain'] == 'estate';
+          } catch (_) {
+            return false;
+          }
+        }).toList();
+        expect(pending, hasLength(2),
+            reason: 'salvage() returns the authored estate intents with their full bytes');
+        expect(pending.every((w) => (w['id'] ?? '').toString().isNotEmpty), isTrue);
+        return pending;
+      });
+
+      // ── LEG 2: park both on the jammed workspace (the shape a domain rejection parks) and
+      //    assert deadLetters() surfaces them with full provenance. ──
+      await _leg('leg 2: park as dead letters → deadLetters() surfaces provenance', () async {
+        final r = await app.absorbSalvage(deadLetters: [
+          for (final w in work)
+            {
+              'id': w['id'],
+              'oid': w['id'], // provenance slot; the entry is deduped/looked up by id
+              'intentB64': w['intentB64'],
+              'source': 'local',
+              'error': "no active installed law declares domain 'estate'",
+            }
+        ]);
+        expect(r['requeuedDeadLetters'], 2);
+        final dead = await app.deadLetters();
+        expect(dead, hasLength(2));
+        final entry = dead.first;
+        expect(entry['domain'], 'estate',
+            reason: 'the DLQ decodes domain/directiveId provenance from the parked bytes');
+        expect(entry['directiveId'], 'placeSite');
+        expect(entry['source'], 'local');
+        expect(entry.containsKey('intentB64'), isFalse,
+            reason: 'deadLetters() is metadata-only; the bytes stay in the durable queue');
+      });
+
+      // ── LEG 3: retry while the law is still absent — a REFUSAL, not a loss (and, regression:
+      //    not a "no remote main" throw on this local-only session). ──
+      final firstId = work.first['id'].toString();
+      await _leg('leg 3: retry refuses while the law is absent; the entry stays', () async {
+        final r = await app.retryDeadLetter(firstId);
+        expect(r['ok'], isFalse, reason: 'the law still cannot merge it: $r');
+        final dead = await app.deadLetters();
+        expect(dead, hasLength(2), reason: 'a refused retry NEVER drops the work');
+        expect(
+            dead
+                .firstWhere((d) => d['id'] == firstId)['error']
+                .toString(),
+            isNotEmpty,
+            reason: 'the entry carries the fresh refusal');
+      });
+
+      // ── LEG 4: the domain dev ships the law fix; retry UNJAMS and the work lands, readable. ──
+      await _leg('leg 4: law fix (installDomain) → retry admits → the work is on the ledger',
+          () async {
+        final usda = (jsonDecode(File(_geoDeploy).readAsStringSync())
+                as Map)['packageUsda']
+            .toString();
+        await app.offerOutcome(
+          domain: 'nomos',
+          directiveId: 'installDomain',
+          payload: {
+            'domainHash': geoHash,
+            'packageUsda': usda,
+            'installedBy': 'dlq-test-law-fix',
+            'dependencies': <Object?>[],
+            'finalizers': <Object?>[],
+          },
+          domainHash: harness.frameworkHash,
+        );
+        final r = await app.retryDeadLetter(firstId);
+        expect(r['ok'], isTrue, reason: 'the unjam after the law fix: $r');
+        final dead = await app.deadLetters();
+        expect(dead, hasLength(1), reason: 'the retried entry resolved out of the queue');
+        final rows =
+            await app.query('sitesByName', {'name': 'a day of work I refuse to lose'});
+        expect(rows, hasLength(1), reason: "the user's work landed and reads back");
+      });
+
+      // ── LEG 5: discard is the app's explicit drop; the queue drains; a re-retry of a gone id
+      //    answers a typed refusal. ──
+      await _leg('leg 5: discard drains; retry of a gone id refuses by name', () async {
+        final secondId = work[1]['id'].toString();
+        final d = await app.discardDeadLetter(secondId);
+        expect(d['ok'], isTrue);
+        expect(await app.deadLetters(), isEmpty);
+        final gone = await app.retryDeadLetter(secondId);
+        expect(gone['ok'], isFalse);
+        expect(gone['error'].toString(), contains('no dead letter'));
+      });
+    } finally {
+      await harness.dispose().timeout(const Duration(seconds: 30),
+          onTimeout: () => throw StateError('harness disposal hung'));
+    }
+  }, timeout: const Timeout(Duration(minutes: 6)));
+}

package/dart/test/event_plane_seam_test.dart

@@ -0,0 +1,188 @@
+// THE EVENT-PLANE TRIPWIRE (source-level, no mirrors).
+//
+// THE BUG CLASS THIS CLOSES: NomosSession extends NomosBridge but shares the parent's transport —
+// _onMessage only ever runs on the PARENT, so any Stream-returning member (or stateful snapshot) that
+// touches `this`'s controller registries registers on a session's DEAD registry and never emits
+// (shipped instances: watchPendingConflicts pre-0.48.1 + the five hand-written session watch overrides).
+// The structural fix: ONE overridable seam — `NomosBridge get _eventPlane` — and every event-dispatch /
+// plane-state access goes through it.
+//
+// WHAT THIS TEST ASSERTS (each chosen to FAIL if the bug class is re-opened):
+//  1. Every public Stream-returning member declared on NomosBridge routes through the seam: its body
+//     either references `_eventPlane` directly or delegates to `_watchStream` (whose own body must).
+//  2. The controller registries (`_watches[` / `_compatWatches[`) are only ever indexed via
+//     `_eventPlane.` inside Stream-returning members — a new method with its own local registry, or a
+//     bare `this._watches[subId] = ctrl`, trips it.
+//  3. NomosSession declares NO Stream-returning members and NO StreamController state of its own — a
+//     re-added per-method override (the old workaround, i.e. the smell) trips it.
+//  4. The seam override on NomosSession chases to the root (`parent._eventPlane`, not `parent`).
+//
+// HONESTY NOTE: this is a text-level check, not semantic analysis. It cannot prove an `_eventPlane`
+// mention is the LOAD-BEARING one — but every re-occurrence of the bug so far shipped as a member whose
+// body never named the parent plane at all, which this catches. Keep the seam's doc comment in
+// webview_bridge.dart in sync if the routing rule ever changes.
+
+import 'dart:io';
+
+import 'package:test/test.dart';
+
+/// Extract `class <name> ... { ... }`'s body via brace matching.
+String classBody(String src, String name) {
+  final decl = RegExp('class $name[\\s<]').firstMatch(src);
+  if (decl == null) fail('class $name not found');
+  final open = src.indexOf('{', decl.start);
+  var depth = 0;
+  for (var i = open; i < src.length; i++) {
+    final c = src[i];
+    if (c == '{') depth++;
+    if (c == '}') {
+      depth--;
+      if (depth == 0) return src.substring(open + 1, i);
+    }
+  }
+  fail('unbalanced braces for class $name');
+}
+
+class Member {
+  Member(this.name, this.body);
+  final String name;
+  final String body; // the full text from `=>`/`{` to the member's end
+}
+
+/// Collect every member whose declared return type is `Stream<...>` (methods AND getters).
+/// Text-level: finds `Stream<` at member position, then captures the arrow-or-block body.
+List<Member> streamMembers(String body) {
+  final out = <Member>[];
+  final decl = RegExp(
+      r'\n  Stream<[^=;{]*?(?:get\s+(\w+)|(\w+)\s*\()',
+      dotAll: true);
+  for (final m in decl.allMatches(body)) {
+    final name = m.group(1) ?? m.group(2)!;
+    // scan from the end of the declaration match to the member's end (arrow → `;` at depth 0;
+    // block → matching `}`), tracking (), {}, [] together so `=>` inside args doesn't confuse it.
+    // for a method the regex consumed the opening `(` — rewind one so paren depth balances.
+    var i = m.group(2) != null ? m.end - 1 : m.end;
+    var depth = 0;
+    var start = -1; // where the body proper begins
+    var isBlock = false;
+    for (; i < body.length; i++) {
+      final c = body[i];
+      if (c == '(' || c == '[') depth++;
+      if (c == ')' || c == ']') depth--;
+      if (depth == 0 && start < 0) {
+        if (c == '=' && i + 1 < body.length && body[i + 1] == '>') {
+          start = i;
+          continue;
+        }
+        if (c == '{') {
+          start = i;
+          isBlock = true;
+          depth = 1;
+          continue;
+        }
+        continue;
+      }
+      if (start < 0) continue;
+      if (isBlock) {
+        if (c == '{') depth++;
+        if (c == '}') {
+          depth--;
+          if (depth == 0) break;
+        }
+      } else {
+        if (c == '{') depth++;
+        if (c == '}') depth--;
+        if (c == ';' && depth == 0) break;
+      }
+    }
+    out.add(Member(name, body.substring(m.start, i + 1)));
+  }
+  return out;
+}
+
+void main() {
+  final src = File('lib/src/webview_bridge.dart').readAsStringSync();
+  final bridge = classBody(src, 'NomosBridge');
+  final session = classBody(src, 'NomosSession');
+  final bridgeStreams = streamMembers(bridge);
+
+  test('found the known Stream surface on NomosBridge (parser sanity)', () {
+    final names = bridgeStreams.map((m) => m.name).toSet();
+    // if one of these is renamed/removed, update this list deliberately.
+    for (final expected in [
+      'custodyEvents', 'syncEvents', 'transferProgress', 'syncStatus',
+      'signalEvents', 'flameEvents', 'spanEvents', 'onLawChanged',
+      'watch', 'watchById', 'watchSpatial', 'watchPendingConflicts',
+      'watchActivity', 'watchCompatibility', '_watchStream',
+    ]) {
+      expect(names, contains(expected),
+          reason: 'the source parser lost sight of $expected — fix the '
+              'parser (or update the list if the member was deliberately '
+              'renamed)');
+    }
+  });
+
+  test('every NomosBridge Stream member routes through the _eventPlane seam',
+      () {
+    for (final m in bridgeStreams) {
+      final routed = m.body.contains('_eventPlane') ||
+          RegExp(r'\b_watchStream\(').hasMatch(m.body);
+      expect(routed, isTrue,
+          reason: 'NomosBridge.${m.name} returns a Stream but its body '
+              'references neither _eventPlane nor _watchStream — on a '
+              'NomosSession its events would resolve against a DEAD '
+              'registry (the watchPendingConflicts 0.48.1 bug class). '
+              'Register controllers/state on _eventPlane.<field>.');
+    }
+    // and the shared helper itself must land its registry on the plane.
+    final ws = bridgeStreams.firstWhere((m) => m.name == '_watchStream');
+    expect(ws.body, contains('_eventPlane._watches[subId] = ctrl'),
+        reason: '_watchStream must register its controller on the event '
+            'plane\'s registry');
+    final wc = bridgeStreams.firstWhere((m) => m.name == 'watchCompatibility');
+    expect(wc.body, contains('_eventPlane._compatWatches[subId] = ctrl'),
+        reason: 'watchCompatibility must register its controller on the '
+            'event plane\'s registry');
+  });
+
+  test('controller registries are only indexed via the seam in Stream members',
+      () {
+    for (final m in bridgeStreams) {
+      for (final reg in ['_watches[', '_compatWatches[']) {
+        var from = 0;
+        while (true) {
+          final at = m.body.indexOf(reg, from);
+          if (at < 0) break;
+          from = at + reg.length;
+          final prefix =
+              m.body.substring(at < 12 ? 0 : at - 12, at);
+          expect(prefix, endsWith('_eventPlane.'),
+              reason: 'NomosBridge.${m.name} indexes $reg without the '
+                  '_eventPlane. prefix — a bare registry access is the '
+                  'dead-registry bug on sessions');
+        }
+      }
+    }
+  });
+
+  test('NomosSession declares no Stream members and no controller state', () {
+    final sessionStreams = streamMembers(session);
+    expect(sessionStreams, isEmpty,
+        reason: 'NomosSession re-declares Stream member(s) '
+            '${sessionStreams.map((m) => m.name).toList()} — the per-method '
+            'override was the WORKAROUND for the dead-registry bug, not the '
+            'fix. Make the base implementation _eventPlane-correct instead.');
+    expect(session.contains('StreamController'), isFalse,
+        reason: 'NomosSession holds StreamController state of its own — '
+            'event state belongs on the plane (_eventPlane)');
+  });
+
+  test('the session seam chases to the root plane', () {
+    expect(
+        RegExp(r'NomosBridge get _eventPlane => parent\._eventPlane;')
+            .hasMatch(session),
+        isTrue,
+        reason: 'NomosSession._eventPlane must be parent._eventPlane (not '
+            'parent) so nested delegation stays correct');
+  });
+}