@githolon/dsl 0.113.4 → 0.115.0

package/compile_package.mjs

@@ -19,9 +19,11 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import {
+  authoredImport,
   compileInputs,
   compileProofPath,
   readCompileProof,
+  recordedImportedSources,
 } from "./compile_proof.mjs";
 
 const DSL_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -49,12 +51,21 @@ if (cacheable) {
     dslDir: DSL_DIR,
     configPath,
     argumentIdentity,
+    importedSources: recordedImportedSources(proofPath),
   });
   const proof = readCompileProof({ proofPath, inputs });
   if (proof !== undefined) {
     console.log(`nomos-compile: ${proof.name} unchanged`);
-    console.log(`  law        ${path.relative(process.cwd(), proof.law)}`);
-    console.log(`  domainHash ${proof.domainHash}`);
+    // The law identity is the unit set (CAP-773): the compile wrote it beside the package it proves.
+    const unitSet = (() => {
+      try {
+        return readFileSync(proof.law.replace(/\.law\.usdz$/u, ".units.sha256"), "utf8").trim();
+      } catch {
+        return "(unreadable — recompile)";
+      }
+    })();
+    console.log(`  law        unit set ${unitSet}`);
+    console.log(`  package    ${proof.domainHash} — package — not what targets serve (${path.relative(process.cwd(), proof.law)})`);
     console.log(`  verify     ✓ typed USDA content proof covers compiler, authored inputs and ${proof.outputCount} generated artifacts`);
     process.exit(0);
   }
@@ -85,6 +96,15 @@ const tsxApiEntry = path.join(
 
 // Global hooks (not a namespaced `tsImport`): the compiler's `import.meta.url` and every
 // `createRequire` must stay plain file URLs, exactly as under the tsx CLI.
+// The compile's authored import closure (including modules outside the project directory) is
+// collected here and recorded in the compile proof, so editing any of them invalidates it.
+const importedSources = new Set();
+globalThis[Symbol.for("nomos.compile.importedSources")] = importedSources;
 const { register } = await import(pathToFileURL(tsxApiEntry).href);
-register();
+register({
+  onImport(url) {
+    const file = authoredImport(url, DSL_DIR);
+    if (file !== undefined) importedSources.add(file);
+  },
+});
 await import(pathToFileURL(MAIN).href);

package/compile_proof.d.mts

@@ -1,6 +1,8 @@
 export interface CompileProofInputs {
   readonly authoring: readonly { readonly path: string; readonly sha256: string }[];
   readonly compiler: readonly { readonly path: string; readonly sha256: string }[];
+  /** The authored modules the compile imported, including any outside the project directory. */
+  readonly importedSources: readonly string[];
   readonly authoringIdentity: string;
   readonly compilerIdentity: string;
   readonly argumentIdentity: string;
@@ -11,7 +13,12 @@ export function compileInputs(options: {
   dslDir: string;
   configPath: string;
   argumentIdentity: string;
+  importedSources?: readonly string[];
 }): CompileProofInputs;
+/** The authored file a compile imported from `url`, or undefined for compiler and dependency code. */
+export function authoredImport(url: string, dslDir: string): string | undefined;
+/** The authored import closure a previous compile recorded in its proof. */
+export function recordedImportedSources(proofPath: string): string[];
 export function compileProofPath(cwd: string, configPath: string): string;
 export function generatedOutputFiles(
   outDir: string,

package/compile_proof.mjs

@@ -13,7 +13,7 @@ import {
 } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const INPUT_EXTENSIONS = new Set([
   ".ts", ".mts", ".cts", ".js", ".mjs", ".cjs", ".json", ".yaml", ".yml",
@@ -94,8 +94,38 @@ function dependencyPackageFiles(dslDir, cwd) {
   return files;
 }
 
-export function compileInputs({ cwd, dslDir, configPath, argumentIdentity }) {
+/**
+ * The authored module a running compile imported, or undefined for compiler and dependency code.
+ * A project may name modules outside its own directory (`../../domains/x.ts`); walking the project
+ * root never sees those, so the proof records the closure the compile actually loaded.
+ */
+export function authoredImport(url, dslDir) {
+  if (!url.startsWith("file:")) return undefined;
+  const file = path.resolve(fileURLToPath(url));
+  if (!INPUT_EXTENSIONS.has(path.extname(file))) return undefined;
+  if (file.split(path.sep).includes("node_modules")) return undefined;
+  const fromCompiler = path.relative(path.resolve(dslDir), file);
+  if (!fromCompiler.startsWith("..") && !path.isAbsolute(fromCompiler)) return undefined;
+  return file;
+}
+
+/** The authored import closure a previous compile recorded, so an unchanged check re-hashes it. */
+export function recordedImportedSources(proofPath) {
+  let text;
+  try {
+    text = readFileSync(proofPath, "utf8");
+  } catch {
+    return [];
+  }
+  const list = /custom uniform asset\[\] nomos:importedSources = \[([^\]]*)\]/u.exec(text)?.[1];
+  if (list === undefined) return [];
+  return [...list.matchAll(/@([^@]+)@/gu)].map((match) => path.resolve(path.dirname(proofPath), match[1]));
+}
+
+export function compileInputs({ cwd, dslDir, configPath, argumentIdentity, importedSources = [] }) {
+  const imported = [...new Set(importedSources.map((file) => path.resolve(file)))].sort(compareText);
   const authoring = inventory([
+    ...imported,
     configPath,
     // An operator may compile an absolute project path from a different repo.
     // Its sibling sources are inputs too; cwd alone can falsely certify stale law.
@@ -115,7 +145,9 @@ export function compileInputs({ cwd, dslDir, configPath, argumentIdentity }) {
   return {
     authoring,
     compiler,
-    authoringIdentity: inventoryIdentity("authoring", authoring),
+    importedSources: imported,
+    // v2 of the authoring identity covers the imported closure; a v1 proof never certifies it.
+    authoringIdentity: inventoryIdentity("authoring-closure", authoring),
     compilerIdentity: inventoryIdentity("implementation", compiler),
     argumentIdentity: sha256(`nomos-compile-arguments-v1\0${argumentIdentity}`),
   };
@@ -163,6 +195,9 @@ function emitCompileProof({ proofPath, inputs, outputs, name, domainHash, law })
     `    custom uniform string nomos:authoringIdentity = "${inputs.authoringIdentity}"`,
     `    custom uniform string nomos:compilerIdentity = "${inputs.compilerIdentity}"`,
     `    custom uniform string nomos:argumentIdentity = "${inputs.argumentIdentity}"`,
+    `    custom uniform asset[] nomos:importedSources = [${(inputs.importedSources ?? [])
+      .map((file) => `@${path.relative(proofDir, file).replaceAll(path.sep, "/")}@`)
+      .join(", ")}]`,
     "    custom rel nomos:inputs = [",
     ...relationships("Inputs", inputPrims).map((line, index) => `${line}${index + 1 === inputPrims.length ? "" : ","}`),
     "    ]",

package/dart/CHANGELOG.md

@@ -1,3 +1,63 @@
+## 0.69.0
+
+- The test cloud's partition proxy (`NomosTestCloud`) carries live sockets: each workspace's catch-up
+  stream and live offers pass through it while ONLINE, and going OFFLINE severs them too (CAP-826).
+
+Uses nomos_types 0.14.0; regenerate generated clients with this compiler.
+
+- Generated framework calls expose `domainRequirements` (CAP-666): for each application domain, the law unit and
+  the generated requirement identity this client was compiled against. `NomosApprovedModel` carries them to the
+  model-adoption desk, and the client inventory records them as the build's contract, so an application pinned
+  to one domain no longer goes stale when a rollout moves a domain it never touches.
+- One parent per node (CAP-788): the kernel refuses, with `[birth-child-already-parented]`, a business birth whose
+  child already records a different parent. Names are fixed at birth (CAP-803): `keyedBirthWorkspace` and the
+  generated `open` / `fetch` / `watchOpenProgress(key)` address a business child by
+  `workspaceNameForKey(namespace, key)`, exactly as 0.68.0 did, and send no parent. The parent-scoped naming
+  proposed with CAP-788 is withdrawn before release.
+- Birth keys are minted by default (CAP-804). A business birth with no `key` names its child by an id Nomos
+  mints inside the birth; generated applications open it with `openReference` / `fetchReference` / `mine()`
+  instead of `open(key)`. An encrypted `.owned()` birth reserves its minted key first (`session.mintId`). An
+  explicit key, `key: "<field>"`, must name a typed-id field and names children exactly as before. When a duplicate birth is refused on the losing peer
+  (`[birth-child-already-parented]`), the child's creation receipt completes with a `NomosOperationRefused`
+  error (new export; `NomosOperationStatus.refusal` / `isRefused`).
+- Birth keys are typed ids (CAP-804 follow-up): a generated client's branded-id fields are extension types in read
+  models and query keys, and `open(key)` / `fetch(key)` / `watchOpenProgress(key)` take the key's branded type. A
+  write that changes a birth key is refused (`birth-key-write-once`).
+- One console enrolment exchange is bounded at 20 s (`nomosConsoleEnrolmentTimeout`); a timeout is a retryable
+  transport failure, so a slow console no longer holds a person's write (CAP-807).
+- Nested record members, map values, list elements and union variants carry their protobuf wire allocation in the
+  generated compatibility requirement, and the kernel judges them recursively (CAP-681). A client whose nested
+  allocation differs from the installed law is refused with the member named, never decoded wrongly.
+- A reloaded app no longer sees an empty child list (CAP-824): `nomosFrameworkChildWorkspaces` (behind the
+  generated `mine()` / `available()`) waits out a retryable not-ready answer while the device is still preparing
+  its copy, as every other one-shot read does, so the caller gets the children or a real error. A write that meets
+  unfinished preparation is held and reported as `NomosWritePhase.preparing`, then completes; no client change.
+- Bundles the 0.115.0 runtime: the kernel-side release qualification (CAP-789), the per-domain adoption record
+  (CAP-666), one parent per node with names fixed at birth (CAP-788, CAP-803), minted birth keys and the losing
+  peer's typed birth refusal (CAP-804), the pack indexed in place (CAP-802), pack imports in bounded steps
+  that never hold up a person's work (CAP-806), one law version per identity named by its unit set (CAP-809), the
+  v2 command frontier (CAP-810) and claimed law versions (CAP-811).
+
+## 0.68.0
+
+Breaking: regenerate generated Dart clients with this compiler.
+
+- Generated clients name the law by its unit set (CAP-773). Generated framework calls expose `lawUnitSet` and
+  `lawPackageSha256` in place of `applicationBirthContract`, and no generated offer carries a law expectation;
+  the kernel selects current law from the workspace's own state. `OpenReceivingGroupRequest.contract` is retired:
+  a Home is born under the law its platform serves. Pass `unitSet` to `NomosApprovedModel` (nomos_types 0.13.0).
+- A local offer's call returns after the watches it changed have delivered the post-offer state, and it re-reads
+  only the watches it can change (CAP-755, CAP-760). Rows watches merge the rows that changed instead of
+  re-reading the whole result (`NmsRowsMerge`, `NomosRows`), and `NomosRowProjection` redoes only those rows
+  (CAP-731, CAP-751).
+- The sync status reports a custodian warming up as `CustodianWarmingPosture`, not as an error (CAP-769).
+- `--dart-define=NOMOS_TRACE=true` writes an opt-in `[nomos-trace]` timeline across the save path (CAP-741).
+- Testing: `NmsTestPeer` stands on an explicit `NmsTestPeerHost`; `NOMOS_TEST_PEER_HOST=native` runs AppSim on the
+  real Apple native host (CAP-717). `NOMOS_PEER_CLASSES` selects the Node peer's classes, e.g.
+  `personal-device` (CAP-722).
+- Bundles the runtime with instant local writes, the live link changes and the fixes listed in
+  nomos_flutter 0.67.0.
+
 ## 0.67.2
 
 - Bundles the 0.113.4 runtime: owed watch re-reads never starve the Peer Office's maintenance.

package/dart/lib/src/application_framework_calls.dart

@@ -3,8 +3,8 @@
 import 'dart:convert' show utf8;
 import 'dart:typed_data' show Uint8List;
 import 'package:meta/meta.dart' show internal;
-import 'package:nomos_types/nomos_types.dart' show Sha256Digest;
-import 'package:nomos_types/nomos_kernel_protocol.dart' show ApplicationBirthContract, BirthCertificate;
+import 'package:nomos_types/nomos_types.dart' show NomosDomainRequirement, Sha256Digest;
+import 'package:nomos_types/nomos_kernel_protocol.dart' show BirthCertificate;
 
 import 'generated_call.dart';
 import 'result_usda.dart' show NmsUsdaLayer, NmsUsdaPrim;
@@ -235,10 +235,20 @@ abstract interface class NmsApplicationFrameworkCalls {
   String get parentModelAuthoritySeatAggregate;
   String get parentModelAuthoritySeatId;
 
-  /// The application's birth contract for the receiving-group desk: the compiled law package identity
-  /// (the closure serving the injected application-home domain). The parent platform's controller is
-  /// per-platform installed state the desk observes at birth, never a value the descriptor carries.
-  ApplicationBirthContract get applicationBirthContract;
+  /// THE LAW this application was compiled as (CAP-773): the unit set identity of its `build/<name>.units`.
+  /// An application approves law by it; each workspace serves a closure its own kernel composes from those
+  /// units, so no compiled value names what a workspace serves.
+  String get lawUnitSet;
+
+  /// The compiled package closure (`build/<name>.law.usdz`): the bytes a device stages through the
+  /// model-adoption desk on a package-lane workspace. Package — not what a unit-lane workspace serves.
+  String get lawPackageSha256;
+
+  /// THE PER-DOMAIN REQUIREMENTS (CAP-666), by application domain key: the exact law unit
+  /// (`domain:<key>` of the unit set) and the generated consumer requirement identity this
+  /// client was compiled against. An application pins its release by these beside [lawUnitSet];
+  /// the model-adoption desk and the client inventory carry them as this build's contract.
+  Map<String, NomosDomainRequirement> get domainRequirements;
 
   NmsGeneratedCall enrollFirstDevice({
     required String domain,

package/dart/lib/src/console_enrolment.dart

@@ -192,6 +192,13 @@ final class NomosConsoleEnrolmentRefused implements Exception {
   String toString() => 'console enrolment refused (HTTP $status): $message';
 }
 
+/// How long one console enrolment exchange may take before the shell reports
+/// it as a retryable transport failure. The console answers once the
+/// workspaces the device asked for admitted it (its fan-out follows in the
+/// background), so a healthy answer takes a few seconds; Peer Office asks
+/// again with a fresh token rather than holding a person's write.
+const Duration nomosConsoleEnrolmentTimeout = Duration(seconds: 20);
+
 /// One console exchange: status and raw body.
 final class NomosConsoleResponse {
   const NomosConsoleResponse({required this.status, required this.body});

package/dart/lib/src/console_http_io.dart

@@ -1,25 +1,32 @@
+import 'dart:async';
 import 'dart:convert';
 import 'dart:io';
 
-import 'console_enrolment.dart' show NomosConsoleResponse;
+import 'console_enrolment.dart'
+    show NomosConsoleResponse, nomosConsoleEnrolmentTimeout;
 
 /// The native shells' console transport: one JSON POST, the answer's status
 /// and body. No retry and no interpretation: Peer Office owns both.
-Future<NomosConsoleResponse> nomosDefaultConsolePost(
-    Uri url, String body) async {
-  final client = HttpClient()..connectionTimeout = const Duration(seconds: 30);
+///
+/// The whole exchange is bounded by [timeout] ([nomosConsoleEnrolmentTimeout]) (CAP-807:
+/// a slow console held a person's write for 53 s before this failed). A
+/// [TimeoutException] is a retryable transport failure: the console may still
+/// finish the enrolment, and the next attempt (a fresh token) finds it done.
+Future<NomosConsoleResponse> nomosDefaultConsolePost(Uri url, String body,
+    {Duration timeout = nomosConsoleEnrolmentTimeout}) async {
+  final client = HttpClient()..connectionTimeout = timeout;
   try {
-    final request = await client.postUrl(url);
-    request.headers
-      ..contentType = ContentType.json
-      ..set(HttpHeaders.acceptHeader, 'application/json');
-    request.add(utf8.encode(body));
-    final response = await request.close().timeout(const Duration(seconds: 60));
-    final text = await response
-        .transform(utf8.decoder)
-        .join()
-        .timeout(const Duration(seconds: 60));
-    return NomosConsoleResponse(status: response.statusCode, body: text);
+    return await () async {
+      final request = await client.postUrl(url);
+      request.headers
+        ..contentType = ContentType.json
+        ..set(HttpHeaders.acceptHeader, 'application/json');
+      request.add(utf8.encode(body));
+      final response = await request.close();
+      final text = await response.transform(utf8.decoder).join();
+      return NomosConsoleResponse(status: response.statusCode, body: text);
+    }()
+        .timeout(timeout);
   } finally {
     client.close(force: true);
   }

package/dart/lib/src/dev_cloud.dart

@@ -79,6 +79,10 @@ class NomosTestCloud {
   bool _online = true;
   bool _stopped = false;
 
+  /// Live sockets the proxy carries (each workspace's catch-up stream and live offers,
+  /// architecture/peer_catchup.md). Going OFFLINE severs them too, as a real link loss would.
+  final Set<WebSocket> _liveSockets = {};
+
   NomosTestCloud._(
     this._server,
     this._proxy,
@@ -98,6 +102,12 @@ class NomosTestCloud {
   /// cloud and peers converge. Deterministic: no timing races, the test decides exactly when the link exists.
   void setOnline(bool online) {
     _online = online;
+    if (!online) {
+      for (final socket in _liveSockets.toList()) {
+        socket.close(WebSocketStatus.goingAway, 'partitioned');
+      }
+      _liveSockets.clear();
+    }
     _log(
       'partition: ${online ? "ONLINE (link up)" : "OFFLINE (link severed)"}',
     );
@@ -350,6 +360,10 @@ class NomosTestCloud {
       } catch (_) {}
       return;
     }
+    if (WebSocketTransformer.isUpgradeRequest(req)) {
+      await _proxyLiveSocket(req);
+      return;
+    }
     try {
       final target = _upstream.replace(
         path: req.uri.path,
@@ -375,6 +389,50 @@ class NomosTestCloud {
     }
   }
 
+  /// A WebSocket through the partition: both ends piped frame for frame, both closed together.
+  Future<void> _proxyLiveSocket(HttpRequest req) async {
+    final WebSocket upstream;
+    try {
+      upstream = await WebSocket.connect(_upstream
+          .replace(
+            scheme: _upstream.scheme == 'https' ? 'wss' : 'ws',
+            path: req.uri.path,
+            query: req.uri.query.isEmpty ? null : req.uri.query,
+          )
+          .toString());
+    } catch (_) {
+      try {
+        req.response.statusCode = 502;
+        await req.response.close();
+      } catch (_) {}
+      return;
+    }
+    final WebSocket client;
+    try {
+      client = await WebSocketTransformer.upgrade(req);
+    } catch (_) {
+      await upstream.close();
+      return;
+    }
+    _liveSockets
+      ..add(client)
+      ..add(upstream);
+    void closeBoth() {
+      _liveSockets
+        ..remove(client)
+        ..remove(upstream);
+      client.close();
+      upstream.close();
+    }
+
+    upstream.listen((frame) {
+      if (_online) client.add(frame);
+    }, onDone: closeBoth, onError: (_) => closeBoth());
+    client.listen((frame) {
+      if (_online) upstream.add(frame);
+    }, onDone: closeBoth, onError: (_) => closeBoth());
+  }
+
   Future<Map<String, Object?>> _getJson(Uri url) async {
     final req = await _client.getUrl(url);
     final resp = await req.close();
@@ -394,6 +452,10 @@ class NomosTestCloud {
     if (_stopped) return;
     _stopped = true;
     _log('stopping');
+    for (final socket in _liveSockets.toList()) {
+      socket.close();
+    }
+    _liveSockets.clear();
     try {
       await _proxy.close(force: true);
     } catch (_) {}

package/dart/lib/src/generated_call.dart

@@ -2,6 +2,8 @@ import 'dart:typed_data';
 
 import 'package:meta/meta.dart' show internal;
 
+import 'nomos_trace.dart' show NomosTrace;
+
 /// One compiler-authored, nominal domain call.
 ///
 /// Generated applications construct this directly from their typed input. The
@@ -63,10 +65,17 @@ abstract final class NmsInternalGeneratedCalls {
       throw ArgumentError(
           'A generated Nomos call needs one exact typed Protobuf payload.');
     }
-    return _GeneratedCall(domain, directive, protobufType, protobufPayload);
+    return _GeneratedCall(domain, directive, protobufType, protobufPayload,
+        NomosTrace.enabled ? NomosTrace.now() : 0);
   }
 }
 
+/// When generated code finished encoding [call] (Timeline microseconds), for the opt-in
+/// timeline trace; 0 when tracing was off or the call was not compiler-authored.
+@internal
+int nmsGeneratedCallCreatedAt(NmsGeneratedCall call) =>
+    call is _GeneratedCall ? call.createdAtMicros : 0;
+
 /// Constructor namespace reserved for generated query code.
 @internal
 abstract final class NmsInternalGeneratedQueries {
@@ -112,8 +121,10 @@ abstract final class NmsInternalGeneratedResults {
 }
 
 final class _GeneratedCall implements NmsGeneratedCall {
-  const _GeneratedCall(
-      this.domain, this.directive, this.protobufType, this.protobufPayload);
+  const _GeneratedCall(this.domain, this.directive, this.protobufType,
+      this.protobufPayload, this.createdAtMicros);
+
+  final int createdAtMicros;
 
   @override
   final String domain;

package/dart/lib/src/nms_generated_runtime.dart

@@ -39,6 +39,12 @@ export 'package:nomos_types/src/foreign_ref.dart'
         ForeignDenied,
         ForeignUnreachable;
 export 'reception/dart_reception.dart';
+export 'rows_watch.dart'
+    show
+        NomosRowProjection,
+        NomosRows,
+        NomosRowsProjectionStream,
+        NomosWatchPositionMismatch;
 export 'session_bound.dart';
 export 'application_model_adoption.dart'
     show
@@ -49,6 +55,7 @@ export 'application_model_adoption.dart'
         NomosModelAdoptionPhase,
         NomosModelAdoptionProgress;
 export 'provider.dart';
+export 'nomos_trace.dart' show NomosTrace;
 export 'record_origin.dart';
 export 'generated_call.dart'
     show

package/dart/lib/src/node_runner_transport.dart

@@ -20,6 +20,8 @@ import 'package:package_config/package_config.dart' show loadPackageConfigUri;
 
 import 'package:nomos_types/nomos_kernel_protocol.dart' as nomos_protocol;
 
+import 'nomos_trace.dart' show NomosTrace;
+
 import 'runtime_v2_transport.dart'
     show
         NmsBufferedRuntimeEvents,
@@ -40,8 +42,15 @@ class NodeRunnerTransport
   final void Function(String line)? _onDiagnostic;
   final Map<int, Completer<nomos_protocol.RuntimeResponse>> _runtimeReplies =
       {};
+
+  /// Opt-in timeline only: when each request was written, and when its answer was decoded.
+  final Map<int, int> _traceSentAt = {};
+  final Map<int, int> _traceArrivedAt = {};
   bool _disposed = false;
 
+  /// A watch change was delivered in this event-loop turn and its listeners have not run yet.
+  bool _eventsAhead = false;
+
   NodeRunnerTransport._(this._proc, this._onDiagnostic) {
     _proc.stdout.transform(utf8.decoder).transform(const LineSplitter()).listen(
         (line) {
@@ -49,12 +58,34 @@ class NodeRunnerTransport
       if (s.isEmpty) return;
       if (s.startsWith('runtime-v2:')) {
         try {
+          final traceArrived = NomosTrace.enabled ? NomosTrace.now() : 0;
           final response = nomos_protocol.RuntimeResponse.fromBuffer(
             base64Decode(s.substring('runtime-v2:'.length)),
           );
-          _runtimeReplies
-              .remove(response.requestId.toInt())
-              ?.complete(response);
+          if (NomosTrace.enabled) {
+            final id = response.requestId.toInt();
+            final now = NomosTrace.now();
+            _traceArrivedAt[id] = now;
+            final sent = _traceSentAt[id];
+            NomosTrace.emit(
+                'main',
+                'rt.recv',
+                'rr=$id outcome=${response.whichOutcome().name} '
+                    'decUs=${now - traceArrived} '
+                    'us=${sent == null ? -1 : now - sent} bytes=${s.length}');
+          }
+          final reply = _runtimeReplies.remove(response.requestId.toInt());
+          if (reply != null) {
+            if (_eventsAhead) {
+              // Watch changes the peer queued while serving this request were written ahead of
+              // its reply and may share this stdout chunk. Their listeners run as microtasks;
+              // complete the reply in the next event-loop turn so they all run first (CAP-755: a
+              // local offer's watches have delivered before its call returns).
+              Timer.run(() => reply.complete(response));
+            } else {
+              reply.complete(response);
+            }
+          }
         } catch (error, stackTrace) {
           _diag('[nomos-node-runner runtime-v2] $error');
           for (final reply in _runtimeReplies.values) {
@@ -72,6 +103,11 @@ class NodeRunnerTransport
           if (!consumeCredentialRefreshEvent(
               event, this, _runtimeEvents.addError)) {
             _runtimeEvents.add(event);
+            if (event.hasWatchChanged() && !_eventsAhead) {
+              _eventsAhead = true;
+              // Cleared once this chunk's microtasks (the events' listeners) have all run.
+              Timer.run(() => _eventsAhead = false);
+            }
           }
         } catch (error, stackTrace) {
           _runtimeEvents.addError(error, stackTrace);
@@ -89,7 +125,15 @@ class NodeRunnerTransport
     _proc.stderr
         .transform(utf8.decoder)
         .transform(const LineSplitter())
-        .listen((line) => _diag('[nomos-node-runner] $line'));
+        .listen((line) {
+      // The peer's own timeline lines join this process's log as they are (nomos_trace.dart).
+      if (line.startsWith('[nomos-trace] ')) {
+        // ignore: avoid_print
+        print(line);
+        return;
+      }
+      _diag('[nomos-node-runner] $line');
+    });
   }
 
   void _diag(String line) {
@@ -199,15 +243,40 @@ class NodeRunnerTransport
     }
     final reply = Completer<nomos_protocol.RuntimeResponse>();
     _runtimeReplies[id] = reply;
+    final traceStarted = NomosTrace.enabled ? NomosTrace.now() : 0;
+    if (NomosTrace.enabled && !request.hasTrace()) {
+      // Sampled: the peer writes its own timeline lines for this frame.
+      request.trace = NomosTrace.sampledContext();
+    }
     try {
-      _proc.stdin.writeln(
-        'runtime-v2:${base64Encode(request.writeToBuffer())}',
-      );
+      final line = 'runtime-v2:${base64Encode(request.writeToBuffer())}';
+      _proc.stdin.writeln(line);
+      if (NomosTrace.enabled) {
+        _traceSentAt[id] = NomosTrace.now();
+        NomosTrace.emit(
+            'main',
+            'rt.send',
+            'rr=$id op=${NomosTrace.describeRequest(request)} '
+                'lr=${request.hasKernelCall() ? request.kernelCall.request.requestId : '-'} '
+                'encUs=${NomosTrace.now() - traceStarted} bytes=${line.length}');
+      }
     } catch (error, stackTrace) {
       _runtimeReplies.remove(id);
       reply.completeError(error, stackTrace);
     }
-    return reply.future;
+    if (!NomosTrace.enabled) return reply.future;
+    return reply.future.then((response) {
+      // From the decoded answer to the awaiting code running again.
+      final arrived = _traceArrivedAt.remove(id);
+      final sent = _traceSentAt.remove(id);
+      final now = NomosTrace.now();
+      NomosTrace.emit(
+          'main',
+          'rt.resume',
+          'rr=$id resumeUs=${arrived == null ? -1 : now - arrived} '
+              'us=${sent == null ? -1 : now - sent}');
+      return response;
+    });
   }
 
   /// Tear down: stop the runner process and close the message stream.