@githolon/dsl 0.73.0 → 0.75.0

package/dart/test/first_app_gauntlet_test.dart

@@ -0,0 +1,301 @@
+// THE FIRST-FIVE-MINUTES GAUNTLET — one sequential journey through EVERYTHING the test harness +
+// session-bound client surface promises a NEW app developer, using ONLY the public API (the way a
+// tenant would). Every lifecycle bug co2 found in their first minutes (session watch delegation,
+// local autoSync deadlock, the keyed-reconnect lane, …) has a leg here, so the NEXT one is found
+// by CI, not by a tenant.
+//
+// Structure: ONE test, numbered legs, fail-fast — a failure names its leg, so CI output reads as
+// a checklist. Reuses the existing fixtures (estate-birth, surfaced, catalogue-src/-reader); no
+// new law.
+//
+// Prereqs (fixtures compiled + a warm ~/.holon/runtime): locally the test SKIPS with the recipe
+// when they are missing; in CI the job sets NOMOS_GAUNTLET_REQUIRED=1 so a missing prereq is a
+// LOUD FAILURE, never a silently-green skip.
+@TestOn('vm')
+library;
+
+import 'dart:io';
+
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+import '../../../bench/scale/fixtures/estate-birth/build/dart/src/generated/home.client.dart';
+import '../../../bench/scale/fixtures/estate-birth/build/dart/src/generated/estate.client.dart'
+    show EstateClient, SeedEstateWorkspacePayload;
+
+String get _root => '${Directory.current.path}/../..';
+String get _repoEntry => '$_root/cloud/web-client/runner/node-entry.mjs';
+String get _homeDeploy =>
+    '$_root/bench/scale/fixtures/estate-birth/build/estate-birth.deploy.json';
+String get _docsDeploy => '$_root/bench/scale/fixtures/surfaced/build/surfaced.deploy.json';
+String get _catDeploy => '$_root/bench/scale/fixtures/catalogue-src/build/cat.deploy.json';
+String get _readerDeploy =>
+    '$_root/bench/scale/fixtures/catalogue-reader/build/estate.deploy.json';
+String get _runtimeDir =>
+    Platform.environment['NOMOS_DART_RUNTIME'] ??
+    '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+
+const _owner = 'user:gauntlet-owner';
+const _keyed = 'catalogue';
+
+String? _missingPrereq() {
+  if (!File(_repoEntry).existsSync()) return 'in-repo runner not found at $_repoEntry';
+  final fixtures = {
+    _homeDeploy: 'bench/scale/fixtures/estate-birth',
+    _docsDeploy: 'bench/scale/fixtures/surfaced',
+    _catDeploy: 'bench/scale/fixtures/catalogue-src',
+    _readerDeploy: 'bench/scale/fixtures/catalogue-reader',
+  };
+  for (final e in fixtures.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, or curl '
+        '/v1/runtime/holon.wasm + /v1/runtime/packages from the cloud)';
+  }
+  return null;
+}
+
+/// Run one numbered leg fail-fast: log enter/exit so CI output reads as a checklist, and wrap any
+/// failure so the failing LEG is named at the top of the report.
+Future<T> _leg<T>(String name, Future<T> Function() body) async {
+  final sw = Stopwatch()..start();
+  // ignore: avoid_print
+  print('▶ GAUNTLET $name …');
+  try {
+    final r = await body();
+    // ignore: avoid_print
+    print('✔ GAUNTLET $name (${sw.elapsedMilliseconds}ms)');
+    return r;
+  } catch (e, st) {
+    throw TestFailure('GAUNTLET $name FAILED after ${sw.elapsedMilliseconds}ms:\n$e\n$st');
+  }
+}
+
+void main() {
+  test('THE FIRST-FIVE-MINUTES GAUNTLET: harness → blessed shape → local posture → '
+      'acquire → reactive reads → attested read → diagnostics → disposal', () async {
+    final required = Platform.environment['NOMOS_GAUNTLET_REQUIRED'] == '1';
+    final missing = _missingPrereq();
+    if (missing != null) {
+      if (required) {
+        fail('NOMOS_GAUNTLET_REQUIRED=1 but a prereq is missing — the CI job must provide it: '
+            '$missing');
+      }
+      markTestSkipped(missing);
+      return;
+    }
+
+    final diagnostics = <String>[];
+
+    // ── LEG 1: harness up — a 4-workspace cluster, one deviceKeyed, phase diagnostics on. ──
+    final harness = await _leg('leg 1: NomosTestHarness.cluster (4 ws, one deviceKeyed)', () async {
+      final h = await NomosTestHarness.cluster(
+        workspaces: {
+          'home': [_homeDeploy],
+          'docs-ws': [_docsDeploy],
+          _keyed: [_catDeploy],
+          'reader': [_readerDeploy],
+        },
+        deviceKeyed: {_keyed},
+        nodeEntry: _repoEntry,
+        runtimeDir: _runtimeDir,
+        onDiagnostic: diagnostics.add,
+        phaseTimeout: const Duration(seconds: 120),
+      );
+      // Phase diagnostics (the "no silent hangs" promise): install, ready, connect, and the
+      // keyed 3b legs all log enter AND exit lines.
+      expect(diagnostics.any((l) => l.contains('offline law install')), isTrue,
+          reason: 'phase 1 install diagnostics must appear');
+      expect(diagnostics.any((l) => l.contains('runner ready') && l.contains('done')), isTrue,
+          reason: 'the runner-ready phase must log its exit');
+      expect(diagnostics.any((l) => l.contains('3b: device keygen')), isTrue,
+          reason: 'the deviceKeyed keygen phase must log');
+      expect(
+          diagnostics.any(
+              (l) => l.contains("3b: keyed reconnect of '$_keyed'") && l.contains('done')),
+          isTrue,
+          reason: 'the keyed reconnect phase must log its exit (the reported wedge)');
+      expect(h.sessions.toSet(), {'home', 'docs-ws', _keyed, 'reader'});
+      return h;
+    });
+
+    try {
+      // ── LEG 2: the blessed session-bound shape — mount → bind (preflight) → PARENTLESS birth
+      //    → follow(ref) → second client → typed read + a directive. Zero routing strings. ──
+      final home = harness.session('home');
+      final estate = await _leg(
+          'leg 2: blessed shape (bind → parentless birth → follow → 2nd client → read+directive)',
+          () async {
+        final homeClient = await HomeClient.bind(home, actor: _owner);
+        expect(homeClient.session!.workspace, home.workspace,
+            reason: 'inspectable session context');
+        final birth = await homeClient.birthEstateWorkspace(
+          payload: BirthEstateWorkspacePayload(
+            owner: _owner,
+            frameworkHash: harness.frameworkHash!,
+            lawHash: harness.lawHashes(home.workspace).first,
+            bornAt: DateTime.now().toUtc().toIso8601String(),
+          ),
+        );
+        expect(birth.workspace, home.workspace,
+            reason: 'the parentless birth lands in the SESSION workspace');
+        expect(birth.born, hasLength(1));
+        expect(birth.birthOutcomes.first['status'], 'born');
+
+        final estateSession = await harness.bridge.follow(birth.bornRefs.single);
+        expect(estateSession.workspace, birth.born.single);
+
+        final estateClient = await EstateClient.bind(estateSession, actor: _owner);
+        final rows = await estateClient.estatesByOwner(owner: _owner);
+        expect(rows, hasLength(1), reason: 'the child genesis seed reads back typed');
+        final seeded = rows.single;
+        final reseed = await estateClient.seedEstateWorkspace(SeedEstateWorkspacePayload(
+          owner: seeded.owner!,
+          estateName: seeded.estateName!,
+          bornAt: seeded.bornAt!,
+        ));
+        expect(reseed.head, isNotEmpty, reason: 'a directive on the followed second client');
+        return estateSession;
+      });
+
+      // ── LEG 3: local posture — autoSync on a local-only session returns promptly and never
+      //    monopolizes the plane; zero network fetch attempts (asserted again at the end). ──
+      await _leg('leg 3: local-only autoSync completes promptly, plane stays responsive',
+          () async {
+        await home.autoSync().timeout(const Duration(seconds: 10),
+            onTimeout: () => throw StateError(
+                'autoSync() on a local-only session did not return within 10s (the deadlock class)'));
+        // The plane is NOT blocked: a sibling session still answers.
+        final listed = await harness.bridge.listWorkspaces().timeout(const Duration(seconds: 10),
+            onTimeout: () =>
+                throw StateError('listWorkspaces() hung after a local-only autoSync'));
+        expect(listed.map((w) => w['session'].toString()).toSet(),
+            containsAll({'home', 'docs-ws', _keyed, 'reader'}));
+        await home.stopAutoSync().timeout(const Duration(seconds: 10),
+            onTimeout: () => throw StateError('stopAutoSync() hung on a local-only session'));
+      });
+
+      // ── LEG 4: acquireSession — concurrent double-acquire single-flights to ONE handle; the
+      //    credentials callback is NEVER invoked for a plane-known workspace. ──
+      await _leg('leg 4: acquireSession (concurrent, credential-free for a known workspace)',
+          () async {
+        final acquired = await Future.wait([
+          harness.bridge.acquireSession('reader',
+              ifAbsentCredentials: () async =>
+                  fail('reader is on the plane — credentials must not be requested')),
+          harness.bridge.acquireSession('reader',
+              ifAbsentCredentials: () async =>
+                  fail('reader is on the plane — credentials must not be requested')),
+        ]);
+        expect(identical(acquired[0], acquired[1]), isTrue,
+            reason: 'a concurrent double-acquire yields ONE handle');
+        expect(identical(acquired[0], harness.session('reader')), isTrue,
+            reason: 'the acquired handle IS the mounted session');
+      });
+
+      // ── LEG 5: reactive reads on a SESSION — watchById / watch / watchPendingConflicts must
+      //    all deliver a FIRST SNAPSHOT (the 0.48.x dead-delegation class). ──
+      await _leg('leg 5: session reactive reads emit their first snapshot', () async {
+        final raw = await estate.query('estatesByOwner', {'owner': _owner});
+        final aggId = ((raw.single as Map)['id'] ?? '').toString();
+        expect(aggId, isNotEmpty);
+        final byId = await estate
+            .watchById(aggId)
+            .first
+            .timeout(const Duration(seconds: 30),
+                onTimeout: () => throw StateError('watchById never emitted its first snapshot'));
+        expect(byId, hasLength(1));
+        final byQuery = await estate
+            .watch('estatesByOwner', {'owner': _owner})
+            .first
+            .timeout(const Duration(seconds: 30),
+                onTimeout: () => throw StateError('watch(query) never emitted its first snapshot'));
+        expect(byQuery, hasLength(1));
+        // The docs-ws session carries the Surfaced law — its pending-conflicts stream must emit a
+        // first snapshot (empty is correct; EMITTING at all is the regression under test).
+        final conflicts = await harness
+            .session('docs-ws')
+            .watchPendingConflicts()
+            .first
+            .timeout(const Duration(seconds: 30),
+                onTimeout: () => throw StateError(
+                    'watchPendingConflicts never emitted (the session-delegation regression)'));
+        expect(conflicts, isEmpty);
+      });
+
+      // ── LEG 6: the keyed lane end-to-end — an attested read served + SIGNED with the device
+      //    key the 3b re-open installed. ──
+      await _leg('leg 6: attested read from the deviceKeyed workspace', () async {
+        final public = harness.devicePublicKey(_keyed);
+        expect(public, isNotNull);
+        expect(public, isNotEmpty, reason: 'the 3b keygen public half rides the harness');
+        final cat = harness.session(_keyed);
+        final seeded = await cat.offerCreates(
+          domain: 'cat',
+          directiveId: 'listCatalogue',
+          payload: {
+            'listingId': 'L-1',
+            'title': 'Walnut desk',
+            'priceGbp': '900',
+            'listedAt': DateTime.now().toUtc().toIso8601String(),
+          },
+          actor: 'user:seller',
+        );
+        expect(seeded.head, isNotEmpty);
+        final served = await harness.session('reader').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 read is signed by the re-opened session device key');
+      });
+
+      // ── LEG 7: harness diagnostics — assertDomainInstalled, resetWorkspaceCustody, and a
+      //    mid-test seedWorkspaceFromDeployJson round-trip. ──
+      await _leg('leg 7: harness diagnostics (assertDomainInstalled / reset / seed)', () async {
+        await harness.assertDomainInstalled(
+            workspace: estate.workspace, domain: EstateClient.interface.domain);
+        // The negative arm names the active domains.
+        await expectLater(
+            harness.assertDomainInstalled(workspace: 'docs-ws', domain: 'definitely-not-here'),
+            throwsA(isA<NomosTestHarnessException>()));
+        // Reset a workspace's local custody to its seed snapshot, then prove it still serves.
+        await harness.resetWorkspaceCustody('docs-ws');
+        final postReset = await harness
+            .session('docs-ws')
+            .watchPendingConflicts()
+            .first
+            .timeout(const Duration(seconds: 30),
+                onTimeout: () =>
+                    throw StateError('the reset docs-ws session never served a read'));
+        expect(postReset, isEmpty, reason: 'the reset workspace is back at its seed');
+        // Seed a brand-new workspace mid-test from a deploy.json and use it immediately.
+        final late = await harness.seedWorkspaceFromDeployJson(
+            workspace: 'late-ws', deployJsonPaths: [_docsDeploy]);
+        expect(late.workspace, 'late-ws');
+        await harness.assertDomainInstalled(workspace: 'late-ws', domain: 'docs');
+      });
+
+      // Local posture postscript (leg 3's zero-network promise, checked over the WHOLE run): no
+      // session on this plane ever attempted a network fetch.
+      final offending = diagnostics
+          .where((l) => l.contains('intent-offers') || l.contains('refusing network fetch'))
+          .toList();
+      expect(offending, isEmpty,
+          reason: 'local-only sessions must perform NO network work — saw:\n${offending.join('\n')}');
+    } finally {
+      // ── LEG 8: clean disposal within the deadline (a hung teardown is a failure, not a wedge). ──
+      await _leg('leg 8: harness disposal within the deadline', () async {
+        await harness.dispose().timeout(const Duration(seconds: 30),
+            onTimeout: () => throw StateError('harness disposal hung'));
+      });
+    }
+  }, timeout: const Timeout(Duration(minutes: 8)));
+}

package/dart/test/fixtures/wedge/fake-install.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// A FAKE offline-install helper for the hermetic HARNESS PHASE-TIMEOUT tests: honours the real helper's
+// flag + one-line-JSON contract (--deploy/--workspace/--out) but installs nothing — it just writes a tiny
+// dummy snapshot so the harness proceeds to the runner phases.
+import { writeFileSync } from "node:fs";
+const args = process.argv.slice(2);
+const val = (f) => { const i = args.indexOf(f); return i >= 0 ? args[i + 1] : undefined; };
+const out = val("--out");
+const workspace = val("--workspace");
+writeFileSync(out, Buffer.from("fake-snapshot"));
+process.stdout.write(JSON.stringify({ ok: true, snapshot: out, workspace, lawHashes: ["deadbeef"], frameworkHash: "cafebabe" }) + "\n");

package/dart/test/fixtures/wedge/wedge-entry.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// A WEDGING FAKE RUNNER for the hermetic HARNESS PHASE-TIMEOUT tests: speaks the NDJSON bridge protocol,
+// answers everything — EXCEPT the op named in NOMOS_WEDGE_OP (optionally only when the args carry an
+// authorSecret, i.e. the 3b keyed reconnect), which it swallows FOREVER. This forges the exact "silent
+// hang" co2 reported so the harness's typed HarnessPhaseTimeout can be asserted without a real wait.
+import { createInterface } from "node:readline";
+const post = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
+const wedgeOp = process.env.NOMOS_WEDGE_OP || "connect"; // default: wedge the KEYED reconnect (co2's shape)
+const wedgeOnlyKeyed = process.env.NOMOS_WEDGE_ONLY_KEYED !== "0";
+post({ v: 1, event: "ready" });
+const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+rl.on("line", (line) => {
+  const s = line.trim();
+  if (!s) return;
+  let msg; try { msg = JSON.parse(s); } catch { return; }
+  const a = msg.args || {};
+  if (msg.op === wedgeOp && (!wedgeOnlyKeyed || a.authorSecret)) return; // THE WEDGE: never answer
+  if (msg.op === "authorKeygen") return post({ v: 1, id: msg.id, ok: true, result: { secret: "c2VjcmV0", public: "cHVibGlj" } });
+  if (msg.op === "connect") return post({ v: 1, id: msg.id, ok: true, result: { workspace: a.workspace, session: a.session } });
+  post({ v: 1, id: msg.id, ok: true, result: {} });
+});
+rl.on("close", () => process.exit(0));

package/dart/test/harness_phase_timeout_test.dart

@@ -0,0 +1,72 @@
+// NO SILENT HANGS — the harness's per-phase deadline machinery, proven HERMETICALLY (no real waits, no
+// wasm, no network): a fake runner (test/fixtures/wedge/wedge-entry.mjs) speaks the bridge protocol but
+// SWALLOWS the 3b keyed reconnect forever — the exact wedge co2 reported. With a short `phaseTimeout` the
+// harness must throw the TYPED [HarnessPhaseTimeout] naming the phase/workspace/op, never hang; and the
+// failed construction must tear the runner down by itself (no leaked process holding the test runner).
+@TestOn('vm')
+@Timeout(Duration(seconds: 60))
+library;
+
+import 'dart:io';
+
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+String get _fixtures => '${Directory.current.path}/test/fixtures/wedge';
+String get _wedgeEntry => '$_fixtures/wedge-entry.mjs';
+String get _fakeInstall => '$_fixtures/fake-install.mjs';
+
+void main() {
+  test('a wedged keyed reconnect fires HarnessPhaseTimeout naming phase 3b (typed, no hang)', () async {
+    final log = <String>[];
+    Object? err;
+    try {
+      await NomosTestHarness.cluster(
+        workspaces: {
+          'catalogue': ['unused.deploy.json'], // the fake install helper ignores the paths
+        },
+        deviceKeyed: {'catalogue'},
+        nodeEntry: _wedgeEntry,
+        installHelper: _fakeInstall,
+        phaseTimeout: const Duration(seconds: 2), // hermetic: a short deadline, not a real 120s wait
+        onDiagnostic: log.add,
+      );
+    } catch (e) {
+      err = e;
+    }
+    expect(err, isA<HarnessPhaseTimeout>(),
+        reason: 'the wedge must surface as the typed phase timeout, never an eternal await');
+    final t = err as HarnessPhaseTimeout;
+    expect(t.phase, "3b: keyed reconnect of 'catalogue'");
+    expect(t.workspace, 'catalogue');
+    expect(t.awaiting, 'connect');
+    expect(t.elapsed, const Duration(seconds: 2));
+    expect(t.likelyCauses, isNotEmpty, reason: 'known wedges carry their likely causes');
+    expect(t, isA<NomosTestHarnessException>(),
+        reason: 'existing on-NomosTestHarnessException handling keeps working');
+    expect(t.toString(), contains("3b: keyed reconnect of 'catalogue'"));
+    // ask 5 — the phases before the wedge logged enter AND exit; the wedged phase logged its enter.
+    expect(log.any((l) => l.contains('3: connect session') && l.contains('done')), isTrue);
+    expect(log.any((l) => l.contains('3b: device keygen') && l.contains('done')), isTrue);
+    expect(log.any((l) => l.contains("3b: keyed reconnect of 'catalogue'")), isTrue);
+  });
+
+  test('deviceKeyed naming an unknown workspace refuses typed (never a wedge)', () async {
+    Object? err;
+    try {
+      await NomosTestHarness.cluster(
+        workspaces: {
+          'catalogue': ['unused.deploy.json'],
+        },
+        deviceKeyed: {'not-a-workspace'},
+        nodeEntry: _wedgeEntry,
+        installHelper: _fakeInstall,
+        phaseTimeout: const Duration(seconds: 5),
+      );
+    } catch (e) {
+      err = e;
+    }
+    expect(err, isA<NomosTestHarnessException>());
+    expect(err.toString(), contains('not-a-workspace'));
+  });
+}

package/dart/test/sealing_client_test.dart

@@ -0,0 +1,179 @@
+// E2E SEALING FROM DART (task #86 gap 3): the operator-blind encryption handshake driven end-to-end
+// through the Dart sealing-client surface (NomosEncryption — the owner ceremony; WrappedKeyStore —
+// the reader's key custody; the kernel crypto ops over the bridge) against the REAL encrypted-notes
+// law on a local holon. Mirrors bench/scale/e2e_encryption.smoke.mjs leg for leg:
+//   reader device key → grantAndWrap (grant + epoch fan-out in ONE ceremony call) → author-seal →
+//   write the envelope → the reader unwraps its scope key from the on-chain WrappedKey and reads
+//   DECRYPTED → without the key the body stays the opaque envelope → a non-member read is refused.
+@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 _fixture => '$_root/cloud/web-client/test/fixtures/encrypted-notes';
+String get _deploy => '$_fixture/build/encrypted-notes.deploy.json';
+String get _lockfile => '$_fixture/nomos.stable-ids.json';
+String get _runtimeDir =>
+    Platform.environment['NOMOS_DART_RUNTIME'] ??
+    '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+
+const _domain = 'encrypted_notes';
+const _scope = 'readNote';
+const _reader = 'reader-ada';
+const _plaintext = 'the secret body';
+
+String? _missingPrereq() {
+  if (!File(_repoEntry).existsSync()) return 'in-repo runner not found at $_repoEntry';
+  if (!File(_deploy).existsSync() || !File(_lockfile).existsSync()) {
+    return 'missing encrypted-notes fixture — compile it: (cd cloud/web-client/test/fixtures/encrypted-notes && 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('▶ SEAL $name …');
+  try {
+    final r = await body();
+    // ignore: avoid_print
+    print('✔ SEAL $name (${sw.elapsedMilliseconds}ms)');
+    return r;
+  } catch (e, st) {
+    throw TestFailure('SEAL $name FAILED after ${sw.elapsedMilliseconds}ms:\n$e\n$st');
+  }
+}
+
+void main() {
+  test('E2E sealing via the Dart harness: keygen → grantAndWrap → seal → write → decrypted read',
+      () async {
+    final missing = _missingPrereq();
+    if (missing != null) {
+      markTestSkipped(missing);
+      return;
+    }
+    final harness = await NomosTestHarness.ephemeral(
+      deployJsonPaths: [_deploy],
+      workspace: 'sealed-notes',
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      phaseTimeout: const Duration(seconds: 120),
+    );
+    try {
+      final s = harness.bridge;
+      final lawHash = harness.lawHashes('sealed-notes').first;
+
+      // The #58 stable sids for the (Note, body) slot — from the committed lockfile, exactly as the
+      // generated sealing client bakes them.
+      final lock = (jsonDecode(File(_lockfile).readAsStringSync()) as Map);
+      final noteAgg = ((((lock['domains'] as Map)[_domain] as Map)['stableIds'] as Map)['aggregates']
+          as Map)['Note'] as Map;
+      final aggSid = noteAgg['sid'].toString();
+      final fieldSid = ((noteAgg['fields'] as Map)['body'] as Map)['sid'].toString();
+
+      // ── LEG 1: the reader's X25519 device key (secret stays client-side). ──
+      final reader = await _leg('leg 1: reader device keygen (X25519, in-kernel)', () async {
+        final kp = await s.cryptoKeygen();
+        expect((kp['secret'] ?? '').toString(), isNotEmpty);
+        expect((kp['public'] ?? '').toString(), isNotEmpty);
+        return kp;
+      });
+
+      // ── LEG 2: THE OWNER CEREMONY in ONE call — grant the cap + open epoch 0 wrapping the scope
+      //    key to the resolved roster (the Dart NomosEncryption surface, gap 3's real target). ──
+      final scopeKey = base64Encode(
+          base64Decode((await s.cryptoKeygen())['secret'].toString()).sublist(0, 32));
+      final ceremony = NomosEncryption(
+          bridge: s, domain: _domain, domainHash: lawHash, scopes: const [_scope]);
+      final epoch0 = await _leg('leg 2: grantAndWrap (grant + epoch fan-out, one ceremony call)',
+          () async {
+        final r = await ceremony.grantAndWrap(
+          principal: _reader,
+          publicKey: reader['public'].toString(),
+          grantDirective: 'grantReader',
+          grantPayload: {
+            'principal': _reader,
+            'grantedBy': 'owner',
+            'grantedAt': DateTime.now().toUtc().toIso8601String(),
+          },
+          scopeKey: scopeKey,
+        );
+        expect(r.epoch, 0, reason: 'the first ceremony opens epoch 0');
+        expect(r.roster, [_reader], reason: 'the fan-out roster is exactly the granted member');
+        expect(r.head, isNotEmpty);
+        return r;
+      });
+
+      // ── LEG 3: author-seal the body (the wasm seal, sid-bound) and WRITE the envelope. ──
+      final envelope = await _leg('leg 3: seal the body → write the envelope', () async {
+        final env = await s.cryptoSealField(
+          scopeKey: scopeKey,
+          scope: _scope,
+          epoch: epoch0.epoch,
+          aggSid: aggSid,
+          fieldSid: fieldSid,
+          plaintext: _plaintext,
+        );
+        expect(env, contains(fieldSid), reason: 'the envelope binds the stable field sid');
+        expect(env, contains(_scope));
+        await s.offerOutcome(
+          domain: _domain,
+          directiveId: 'writeNote',
+          payload: {'owner': _reader, 'body': env},
+          domainHash: lawHash,
+        );
+        return env;
+      });
+
+      // ── LEG 4: the reader's WrappedKeyStore unwraps its scope key from the on-chain WrappedKey
+      //    with its device secret — the shipped key-custody default. ──
+      final keys = await _leg('leg 4: WrappedKeyStore unwraps the on-chain wrapped key', () async {
+        final store = WrappedKeyStore(
+            bridge: s, principal: _reader, deviceSecret: reader['secret'].toString());
+        final current = await store.scopeKey(_scope);
+        expect(current, isNotNull, reason: 'the reader holds a wrap for its scope');
+        expect(current!.epoch, 0);
+        expect(current.key, scopeKey,
+            reason: 'the unwrapped scope key IS the ceremony key (the real handoff)');
+        return store.readKeys(const [_scope]);
+      });
+
+      // ── LEG 5: read WITH the key → DECRYPTED; read WITHOUT → the opaque envelope. ──
+      await _leg('leg 5: keyed read decrypts; keyless read stays opaque', () async {
+        final withKey = await s.query('notesByOwner', {'owner': _reader}, keys, _reader);
+        expect(withKey, hasLength(1));
+        expect((withKey.single['data'] as Map)['body'], _plaintext,
+            reason: 'the key-holder reads plaintext');
+        final noKey = await s.query('notesByOwner', {'owner': _reader}, null, _reader);
+        final opaque = (noKey.single['data'] as Map)['body'];
+        expect(opaque, isNot(_plaintext), reason: 'the operator view never decrypts');
+        expect(opaque.toString(), contains(_scope),
+            reason: 'the value is the scope-bound ciphertext envelope, sizes/scope visible only');
+        expect(opaque.toString(), envelope, reason: 'byte-for-byte the on-chain envelope');
+      });
+
+      // ── LEG 6: a NON-MEMBER is refused by the read gate itself (before decryption matters). ──
+      await _leg('leg 6: non-member read refused by the read gate', () async {
+        await expectLater(
+            s.query('notesByOwner', {'owner': _reader},
+                [NomosScopeKey(scope: _scope, epoch: 0, key: scopeKey)], 'intruder-mallory'),
+            throwsA(predicate((e) => e.toString().contains('read-forbidden'),
+                'a read-forbidden refusal')));
+      });
+    } finally {
+      await harness.dispose().timeout(const Duration(seconds: 30),
+          onTimeout: () => throw StateError('harness disposal hung'));
+    }
+  }, timeout: const Timeout(Duration(minutes: 5)));
+}

package/dart/test/test_harness_test.dart

@@ -11,7 +11,6 @@ library;
 
 import 'dart:io';
 
-import 'package:nomos_client/nomos_client.dart';
 import 'package:nomos_client/nomos_headless.dart';
 import 'package:test/test.dart';
 
@@ -123,10 +122,12 @@ void main() {
     );
     final joined = lines.join('\n');
     // the four named phases are surfaced so an AppSim can tell install vs runner-wait vs connect-block.
-    expect(joined, contains('phase 1/4 installing'));
-    expect(joined, contains('phase 2/4 spawning the node runner'));
-    expect(joined, contains('phase 3/4 awaiting runner ready'));
-    expect(joined, contains('phase 4/4 connecting session'));
+    expect(joined, contains('phase 1/4: offline law install'));
+    expect(joined, contains('phase 2/4: spawn the node runner'));
+    expect(joined, contains('phase 2/4: spawn the node runner done'));
+    expect(joined, contains('phase 3/4: runner ready'));
+    expect(joined, contains('phase 4/4: connect session'));
+    expect(joined, contains('phase 4/4: connect session "test-ws" done'));
     expect(joined, contains('ready — session "test-ws" connected'));
     expect(harness.bridge, isNotNull);
   }, timeout: const Timeout(Duration(minutes: 2)));