@githolon/dsl 0.113.3 → 0.114.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,27 @@
+## 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.
+
 ## 0.67.1
 
 - Git custody upkeep backing off after a failure is reported as `upkeepRetrying`, not `retrying`: the workspace is

package/dart/lib/src/application_framework_calls.dart

@@ -4,7 +4,7 @@ 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_kernel_protocol.dart' show BirthCertificate;
 
 import 'generated_call.dart';
 import 'result_usda.dart' show NmsUsdaLayer, NmsUsdaPrim;
@@ -235,10 +235,14 @@ 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;
 
   NmsGeneratedCall enrollFirstDevice({
     required String domain,

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.

package/dart/lib/src/nomos_trace.dart

@@ -0,0 +1,107 @@
+/// THE OPT-IN TIMELINE TRACE: `[nomos-trace]` lines across the whole call path.
+///
+/// One generated call (a save, a read) crosses the reception, the transport, an isolate, the
+/// native host, the Peer Office and the kernel. Every layer writes `[nomos-trace]` lines so one
+/// call can be followed end to end and each millisecond given to a layer:
+///
+///   * `c=` — this Dart call (one generated offer or query), joined to
+///   * `lr=` — the kernel request id the reception gave it, joined to
+///   * `rr=` — the Runtime v2 request id every lower layer (worker, host, office) logs.
+///
+/// `t=` is microseconds on Dart's Timeline clock; on Apple the native host and the Peer Office
+/// stamp the same clock (CLOCK_MONOTONIC_RAW), so cross-layer gaps are plain subtraction.
+/// `scripts/nomos_trace_waterfall.ts` turns a log of these lines into a per-call waterfall.
+///
+/// Off by default, including in debug. Build with `--dart-define=NOMOS_TRACE=true` (a release
+/// phone build, `flutter test`, AppSim) or set [NomosTrace.enabled] before the first call. Every
+/// Runtime v2 request is then sent with a `sampled` trace context, which is what turns the native
+/// host's and the Peer Office's lines on: one switch for the whole path. Disabled, each call site
+/// is one static bool read. Lines name operation kinds, ids, sizes and durations only: never
+/// payloads, credentials or workspace contents.
+library;
+
+import 'dart:async';
+import 'dart:developer' as developer;
+
+import 'package:meta/meta.dart' show internal;
+import 'package:nomos_types/nomos_kernel_protocol.dart' as nomos_protocol;
+
+/// See the library comment.
+abstract final class NomosTrace {
+  /// Whether `[nomos-trace]` lines are written. Per isolate: hosts that run a worker isolate pass
+  /// it on explicitly.
+  static bool enabled = const bool.fromEnvironment('NOMOS_TRACE');
+
+  static int _calls = 0;
+
+  /// Microseconds on the Timeline clock (the clock every `t=` uses).
+  static int now() => developer.Timeline.now;
+
+  /// A fresh Dart call id (`c=`).
+  static int nextCall() => ++_calls;
+
+  /// Write one line: `[nomos-trace] t=<now> L=<layer> e=<event> <fields>`. Build [fields] only
+  /// behind an `if (NomosTrace.enabled)` so a disabled build pays nothing for them.
+  static void emit(String layer, String event, String fields) {
+    // A release build's print reaches the device log (idevicesyslog -m nomos); debugPrint
+    // would throttle and batch it, which skews the very timings being read.
+    // ignore: avoid_print
+    print('[nomos-trace] t=${now()} L=$layer e=$event $fields');
+  }
+
+  /// The trace context every Runtime v2 request carries while tracing: `sampled` asks the native
+  /// host and the Peer Office to write their lines too. No ids are set, so the office keeps
+  /// deriving span ids from the request id exactly as when tracing is off.
+  @internal
+  static nomos_protocol.TraceContext sampledContext() =>
+      nomos_protocol.TraceContext(sampled: true);
+
+  /// What a Runtime v2 request asks for, as an operation kind (never argument values):
+  /// `kernelCall/offer:estate/placeAssetOnDrawing`, `kernelCall/query:rows:assetsByAssetId`, `watch`…
+  static String describeRequest(nomos_protocol.RuntimeRequest request) {
+    final command = request.whichCommand().name;
+    if (request.hasKernelCall()) {
+      return '$command/${describeCall(request.kernelCall.request)}';
+    }
+    if (request.hasWatch() && request.watch.hasQuery()) {
+      return '$command/${_describeQuery(request.watch.query)}';
+    }
+    return command;
+  }
+
+  /// A kernel request's operation kind.
+  static String describeCall(nomos_protocol.CallRequest call) {
+    if (call.hasOffer()) {
+      final offer = call.offer;
+      return offer.hasCall()
+          ? 'offer:${offer.call.domain}/${offer.call.directive}'
+          : 'offer:${offer.whichIntent().name}';
+    }
+    if (call.hasQuery()) return _describeQuery(call.query);
+    return call.whichOperation().name;
+  }
+
+  /// [source] with each data event's synchronous listener time traced as `e=watch.handler`
+  /// ([fields] identify the watch). The listener runs inside the transform's data handler, so
+  /// this is the time the application spent on one emission before yielding. Unchanged when off.
+  @internal
+  static Stream<T> timedListener<T>(Stream<T> source, String fields) {
+    if (!enabled) return source;
+    return source.transform(StreamTransformer<T, T>.fromHandlers(
+      handleData: (value, sink) {
+        final started = now();
+        sink.add(value);
+        emit('dart', 'watch.handler', '$fields us=${now() - started}');
+      },
+    ));
+  }
+
+  static String _describeQuery(nomos_protocol.QueryRequest query) {
+    if (query.hasRows()) return 'query:rows:${query.rows.id}';
+    if (query.hasPage()) return 'query:page:${query.page.id}';
+    if (query.hasById()) return 'query:byId:${query.byId.aggregateType}';
+    if (query.hasByType()) return 'query:byType:${query.byType.aggregateType}';
+    if (query.hasNamed()) return 'query:named:${query.named.operation}';
+    return 'query:${query.whichQuery().name}';
+  }
+}