@githolon/dsl 0.75.0 → 0.76.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/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.0",
+  "version": "0.76.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/codegen_dart_client.ts

@@ -627,7 +627,11 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       const targetInThisDomain = aggById.has(targetType) || owner?.name === thisDomainName;
       if (!targetInThisDomain) {
         if (owner === undefined) continue; // target not in this package — unreachable, skip the resolver
-        addImport(`${owner.name}.dart`, concreteClassName(targetType));
+        // LAYERED-packages mode: the sibling domain's TYPES file lives in the TYPES package, not
+        // beside this client file — a relative `<name>.dart` import points at a nonexistent path in
+        // the client package (the co2 0.75.0 regression). The types-barrel import above already
+        // re-exports every generated concrete class, so the extra import is only needed FLAT.
+        if (opts.typesImportUri === undefined) addImport(`${owner.name}.dart`, concreteClassName(targetType));
       }
       const targetConcrete = concreteClassName(targetType);
       const member = dartMemberName(fieldName);
@@ -735,10 +739,11 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     // them (the by-id accessors reference them) and re-export them (once per package, Dart de-dups).
     ...(opts.typesImportUri === undefined && opts.frameworkImportUri !== undefined ? [`import '${opts.frameworkImportUri}';`] : []),
     // CROSS-DOMAIN REF TRAVERSAL (§2a follow-on): a cross-domain resolver references a SIBLING domain's
-    // generated client class + read model (from `<name>.client.dart`) or a foreignRef target's concrete
-    // class (from the sibling TYPES `<name>.dart`) — all co-located in the same generated dir (flat OR
-    // layered), so a same-dir relative import `show`-limited to exactly the referenced names. Empty for a
-    // domain with no cross-domain ref (byte-identical to before this existed).
+    // generated client class + read model (from `<name>.client.dart`, co-located with this file in BOTH
+    // modes) or — FLAT MODE ONLY — a foreignRef target's concrete class from the sibling TYPES
+    // `<name>.dart` (in layered mode that file lives in the TYPES package and the types-barrel import
+    // above already re-exports it; emitting the relative import there was the co2 0.75.0 regression).
+    // Empty for a domain with no cross-domain ref (byte-identical to before this existed).
     ...[...crossDomainImports.entries()]
       .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
       .map(([uri, names]) => `import '${uri}' show ${[...names].sort().join(", ")};`),

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).