@githolon/dsl 0.75.1 → 0.77.0

package/dart/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 0.52.0
+
+- **Offer ack decoupled from watch fan-out** (co2's 2.08s 3×3-grid report): the durable acknowledgement
+  (plan + gate + fold + git write) resolves before any watch fan-out runs; the post-write nudge —
+  including the O(law-size) compat recompute that was the bulk of the unaccounted ~1.1s — is a
+  coalesced macrotask after the ack. Ack latency is now watcher-count-independent (fixture: 346ms with
+  12 watchers → 71ms flat). Read-your-writes holds (projection updates at fold time, tested); ticks are
+  never lost (coalescing + flush-on-dispose, tested).
+- **Full offer span taxonomy** on `recentSpans`/`spanEvents` with no new API: `payload-encode`,
+  `compat-preflight`, `bridge-ipc`, `gate-fold`, `watch-nudge`, `response-delivery` (`git-write` is not
+  separable client-side — plan+gate+fold+write is ONE wasm call). Older runner bundles degrade cleanly
+  (no bridge-leg spans).
+- Regression test for local-only sync observational inertness (offer → query → sync{localOnly} → head
+  unchanged → same row).
+
 ## 0.51.0
 
 - **The burn-down wave.** Dead-letter queue surface on the session plane: `deadLetters()`,

package/dart/lib/src/webview_bridge.dart

@@ -1193,6 +1193,13 @@ class NomosBridge {
     String? session,
   }) async {
     final Map<String, Object?> r;
+    // OFFER SPAN TAXONOMY (bridge legs): stamp the Dart-side send/receive around the op; the runner
+    // echoes { timing: { recv, done } } (its op-pickup and durable-ack instants, ms-epoch, same wall
+    // clock — one machine). bridge-ipc = t0..recv (up-leg transport + queueing); response-delivery =
+    // done..t1 (post-ack down-leg). The runner's own spans (payload-encode / compat-preflight /
+    // gate-fold / watch-nudge) stream over the span event lane, so `recentSpans` carries the full
+    // attributable breakdown of one offer with no new API.
+    final t0 = DateTime.now().millisecondsSinceEpoch;
     try {
       r = _asMap(await _call('offerDirective', {
         'domain': domain,
@@ -1208,6 +1215,23 @@ class NomosBridge {
       throw await _wrapDomainNotInstalled(e,
           domain: domain, domainHash: domainHash, requestedWorkspace: session);
     }
+    final t1 = DateTime.now().millisecondsSinceEpoch;
+    final timing = r['timing'];
+    if (timing is Map) {
+      final recv = timing['recv'], done = timing['done'];
+      if (recv is num && done is num) {
+        int within(num v) {
+          final x = v.toInt();
+          return x < t0 ? t0 : (x > t1 ? t1 : x);
+        }
+        noteLocalSpan(
+            track: 'submit', name: 'offer: bridge ipc (up-leg)', kind: 'bridge-ipc',
+            t0: t0, t1: within(recv));
+        noteLocalSpan(
+            track: 'submit', name: 'offer: response delivery (down-leg)', kind: 'response-delivery',
+            t0: within(done), t1: t1);
+      }
+    }
     final births = ((r['birthOutcomes'] as List?) ?? const [])
         .whereType<Map>()
         .map((m) => m.cast<String, Object?>())

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

package/dart/test/local_sync_inert_test.dart

@@ -0,0 +1,97 @@
+// LOCAL-ONLY SYNC MUST BE OBSERVATIONALLY INERT (co2's 0.75.1 blocker). Their repro, verbatim shape:
+// open a local:// session from a snapshot → offer → query returns the row → sync(admit: true) returns
+// {localOnly: true} → the SAME query must return the SAME row, and the head must be unchanged.
+// No branch/fold mutation, no network, identical results before and after.
+@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';
+
+String get _root => '${Directory.current.path}/../..';
+String get _repoEntry => '$_root/cloud/web-client/runner/node-entry.mjs';
+String get _deployJson =>
+    '$_root/bench/scale/fixtures/estate-birth/build/estate-birth.deploy.json';
+String get _runtimeDir =>
+    Platform.environment['NOMOS_DART_RUNTIME'] ??
+    '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+
+const _workspace = 'estate-birth';
+const _owner = 'user:local-sync-inert';
+
+String? _missingPrereq() {
+  if (!File(_repoEntry).existsSync())
+    return 'in-repo runner not found at $_repoEntry';
+  if (!File(_deployJson).existsSync()) {
+    return 'compile the fixture: (cd bench/scale/fixtures/estate-birth && node ../../../../dsl/compile_package.mjs)';
+  }
+  if (!File('$_runtimeDir/holon.wasm').existsSync())
+    return 'warm ~/.holon/runtime first';
+  return null;
+}
+
+void main() {
+  test(
+      'local-only sync is OBSERVATIONALLY INERT: offer -> query -> sync -> head unchanged -> same row',
+      () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final harness = await NomosTestHarness.cluster(
+      workspaces: {
+        _workspace: [_deployJson],
+      },
+      deviceKeyed: {_workspace},
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+    );
+    try {
+      final session = harness.session(_workspace);
+      final client = await HomeClient.bind(session, actor: _owner);
+
+      // 1-2. offer a write on the snapshot-opened local session.
+      final birth = await client.birthEstateWorkspace(
+        payload: BirthEstateWorkspacePayload(
+          owner: _owner,
+          frameworkHash: harness.frameworkHash!,
+          lawHash: harness.lawHashes(_workspace).first,
+          bornAt: DateTime.now().toUtc().toIso8601String(),
+        ),
+      );
+      expect(birth.born, hasLength(1));
+
+      // 3. query confirms the row (the home law's birth-record read).
+      final before = await client.birthRecordsByPrincipal(principal: _owner);
+      expect(before, hasLength(1),
+          reason: 'the offer must be readable BEFORE sync');
+      final statusBefore = await session.custodyStatus();
+      expect(statusBefore.pendingLocalIntents, greaterThan(0),
+          reason: 'the local write is pending (nothing upstream to land on)');
+
+      // 4. local-only sync — must be a no-op in EVERY observable respect.
+      final summary = await session.sync(admit: true);
+      expect(summary['localOnly'], true,
+          reason: 'a local:// session syncs as the documented no-op');
+
+      // 5. THE REGRESSION (co2): custody unchanged, same query returns the SAME row.
+      final statusAfter = await session.custodyStatus();
+      expect(statusAfter.pendingLocalIntents, statusBefore.pendingLocalIntents,
+          reason:
+              'local-only sync must not consume/move pending local intents');
+      final after = await client.birthRecordsByPrincipal(principal: _owner);
+      expect(after, hasLength(1),
+          reason:
+              'local-only sync must be observationally inert — the row must still read');
+      expect(after.single.principal, before.single.principal,
+          reason: 'the SAME row, byte-for-byte semantics');
+    } finally {
+      await harness.dispose();
+    }
+  }, timeout: const Timeout(Duration(minutes: 4)));
+}

package/dart/test/watch_after_offer_stall_test.dart

@@ -0,0 +1,98 @@
+// REGRESSION (co2, 0.76 offer-ack decoupling): the generated watch must emit the locally
+// committed projection promptly after an offer's acknowledgement — with NO subsequent bridge op.
+// co2's Flutter AppSim (NodeRunnerTransport → node-entry → realm sessions → watchById → Riverpod)
+// saw the post-offer tick NEVER arrive after upgrading to @githolon/client 0.76 / nomos_client 0.52.
+@TestOn('vm')
+library;
+
+import 'dart:async';
+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 _gbDeploy => '$_root/examples/guestbook/build/guestbook.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';
+  if (!File(_gbDeploy).existsSync()) {
+    return 'missing $_gbDeploy — compile it (cd examples/guestbook && npx nomos-compile)';
+  }
+  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('watch emits the post-offer projection under COMPLETE SILENCE (no follow-up ops)',
+      timeout: const Timeout(Duration(minutes: 4)), () async {
+    final missing = _missingPrereq();
+    if (missing != null) {
+      // ignore: avoid_print
+      print('SKIP: $missing');
+      return;
+    }
+    final harness = await NomosTestHarness.ephemeral(
+      deployJsonPaths: [_gbDeploy],
+      workspace: 'stall-ws',
+      nodeEntry: _repoEntry,
+      resolveFrom: '$_root/cloud/web-client',
+      runtimeDir: _runtimeDir,
+      onDiagnostic: (l) {}, // keep output small
+    );
+    addTearDown(harness.dispose);
+    final s = harness.bridge;
+
+    // 1. create one entry, find its id.
+    await s.offerDirective(
+        domain: 'guestbook',
+        directiveId: 'signGuestbook',
+        payload: {
+          'author': 'ada',
+          'message': 'hi',
+          'mood': 'delighted',
+          'signedAt': DateTime.now().toUtc().toIso8601String(),
+        });
+    final rows = await s.query('entriesByAuthor', {'author': 'ada'});
+    expect(rows.length, 1);
+    final id = (rows.first as Map)['id'] as String;
+
+    // 2. subscribe (the app's watchById lane) and wait for the initial tick.
+    final ticks = <List<dynamic>>[];
+    final gotInitial = Completer<void>();
+    final gotMutated = Completer<void>();
+    final sub = s.watchById(id).listen((r) {
+      ticks.add(r);
+      if (!gotInitial.isCompleted) {
+        gotInitial.complete();
+        return;
+      }
+      final tags = ((r.first as Map)['data'] as Map)['tags'];
+      if (tags is List && tags.contains('t-after') && !gotMutated.isCompleted) {
+        gotMutated.complete();
+      }
+    });
+    addTearDown(sub.cancel);
+    await gotInitial.future.timeout(const Duration(seconds: 20),
+        onTimeout: () => throw StateError('initial watch tick never arrived'));
+
+    // 3. THE TEST — mutate the watched row, then COMPLETE SILENCE: no further bridge ops.
+    //    The post-ack deferred nudge (0.76) must still deliver the tick.
+    await s.offerDirective(
+        domain: 'guestbook',
+        directiveId: 'tagEntry',
+        payload: {'entryId': id, 'tags': ['t-after']});
+    await gotMutated.future.timeout(const Duration(seconds: 8), onTimeout: () {
+      throw StateError(
+          'REGRESSION: the post-offer watch tick never arrived under silence '
+          '(ticks seen: ${ticks.length})');
+    });
+  });
+}

package/dart/test/webview_bridge_test.dart

@@ -307,6 +307,48 @@ void main() {
     }
   });
 
+  group('offer span taxonomy (bridge legs)', () {
+    test(
+        'offerOutcome turns the runner timing stamps into bridge-ipc + response-delivery spans on recentSpans',
+        () async {
+      final now = DateTime.now().millisecondsSinceEpoch;
+      final transport = ReplayTransport({
+        'head': 'H1',
+        'created': <Object?>[],
+        'workspace': 'ws',
+        // the runner's op-pickup + durable-ack instants (additive `timing` field)
+        'timing': {'recv': now, 'done': now},
+      });
+      final bridge = NomosBridge(transport);
+      await bridge.ready;
+      await bridge.offerOutcome(
+          domain: 'guestbook', directiveId: 'signGuestbook', payload: {'author': 'ada'});
+      final kinds = bridge.recentSpans
+          .map((m) => ((m['span'] as Map?)?['kind'] ?? '').toString())
+          .toSet();
+      expect(kinds, contains('bridge-ipc'),
+          reason: 'up-leg transport attributed as a span');
+      expect(kinds, contains('response-delivery'),
+          reason: 'post-ack down-leg attributed as a span');
+      await bridge.dispose();
+    });
+
+    test('a runner without timing (older bundle) emits no bridge-leg spans and still answers', () async {
+      final transport =
+          ReplayTransport({'head': 'H1', 'created': <Object?>[], 'workspace': 'ws'});
+      final bridge = NomosBridge(transport);
+      await bridge.ready;
+      final out = await bridge.offerOutcome(
+          domain: 'guestbook', directiveId: 'signGuestbook', payload: {'author': 'ada'});
+      expect(out.head, 'H1');
+      final kinds = bridge.recentSpans
+          .map((m) => ((m['span'] as Map?)?['kind'] ?? '').toString())
+          .toSet();
+      expect(kinds, isNot(contains('bridge-ipc')));
+      await bridge.dispose();
+    });
+  });
+
   late FakeRunner runner;
   late NomosBridge bridge;
   setUp(() {

package/package.json

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

package/src/compile_package_main.ts

@@ -928,7 +928,7 @@ const NOMOS_TYPES_DEP = "^0.3.0";
 // 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
-const NOMOS_CLIENT_DEP = "^0.51.0";
+const NOMOS_CLIENT_DEP = "^0.52.0";
 // DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in dsl/dart/pubspec.yaml
 // and dsl/dart_types/pubspec.yaml — a Dart release without this bump fails the suite, so tenants never
 // land back in dependency_overrides (the exact co2 report this closes, third occurrence).