@githolon/dsl 0.101.6 → 0.102.0

package/dart/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 0.64.0
+
+- Generate one self-documenting application object: intent-shaped business actions at the root, typed
+  aggregate collections for reads and navigation, aggregate-specific conflict decisions, and verified
+  activity. The generated application is the application state; raw runtime clients are private.
+- Let one intent atomically create and ensure any number of aggregate consequences. Every created record and
+  reference-bearing query uses `NomosRef<T>`; secondary ensures keep their aggregate identity through
+  compilation and admission.
+- Generate restart-safe offline scenarios and ownership-aware proofs while keeping keys, certificates,
+  signers, warrants, topology and retry machinery outside the tenant API.
+- Mark the generator-only runtime library internal, so tenant imports receive an analyzer refusal while
+  compiler-generated application code retains the sole intentional implementation bridge.
+
 ## 0.63.1
 
 - Make automatic sync a truthful client-owned lifecycle: local acceptance is durable, offline/restored

package/dart/lib/nomos_client.dart

@@ -1,54 +1,5 @@
-// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
-// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
-// wasm32-wasip1 artifact {kernel · projection · embedded
-// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
-// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
-// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
-
-/// Nomos 2 Dart frontend types.
+/// Nomos runtime implementation package.
 ///
-///  - The hand-written kernel WIRE types (`Value`, `Field`/`WireField`, `Hlc`,
-///    `Op`, `FieldOp`, `Event`, `Schema`/`WireDriver`) — byte-compatible with
-///    serde_json. See `src/wire.dart`, `src/driver.dart`.
-///  - The ONE effectful write verb `offer(intent)` (`src/offer.dart`) + the typed
-///    reactive read engine `NomosReads` (`src/subscriptions.dart`).
-///  - The framework PRIMITIVES ONLY. The CODE-GENERATED per-domain types
-///    (aggregates + public intent payloads + enums + `watch…` read accessors) NO LONGER
-///    live here — they were extracted into the co-located TENANT package
-///    `co2_nomos_domains` (`ts_packages/co2-nomos-domains/dart/`), emitted there by
-///    `ts_packages/co2-nomos-domains/src/emit_dart.ts`. Tenant domains squatting in
-///    the framework package was the wrong topology; this barrel now exports ONLY the
-///    hand-written framework wire/offer/read/provider primitives. App code that
-///    wants the typed domain surface imports `package:co2_nomos_domains/co2_nomos_domains.dart`,
-///    which re-exports this framework barrel PLUS every generated domain.
+/// Tenant applications import their generated `<Domain>Application` package. No generic runtime surface is
+/// exported here; generated code uses a private implementation import under `src/`.
 library;
-
-// THE PURE-DATA CORE — the hand-written kernel wire types, the `offer(intent)` codec,
-// the tri-state `NomosSlot<T>`, `NomosReads`, schema validation, runtime aggregate
-// metadata, the data-only error/trace types, and the typed diagnostics moved to the
-// standalone `nomos_types` package (so generated per-domain TYPES files resolve against
-// it alone). Re-exported here so this barrel's public API is unchanged for consumers.
-export 'package:nomos_types/nomos_types.dart';
-// homeNameOf(subject) — the canonical home-workspace name (parity with @githolon/client + the law side).
-export 'src/home.dart';
-export 'src/workspace_name.dart';
-// THE WEBVIEW BRIDGE (app-binding boundary) — the async Dart runtime that drives the REAL githolon running
-// in a WebView, so the generated typed client never needs a `MemoryPersistence` fake.
-export 'src/webview_bridge.dart';
-// SESSION-BOUND CLIENTS (architecture/session_bound_clients.md) — the typed session/client
-// contract: NomosClientInterface (`XClient.interface`), session.assertCompatible(...), and the two
-// typed mismatch errors (DomainClientSessionMismatch / DomainNotInstalledForSession).
-export 'src/session_bound.dart';
-// The PROVIDER boundary (server-side capability-provider SDK runtime: TaskOutcome /
-// TaskSuccess / TaskFailure / TaskResult / TaskProvider / HostClock). The symmetric twin
-// of `offer.dart`; the generated per-task provider classes build on it.
-export 'src/provider.dart';
-
-// ── NO generated domains here ──────────────────────────────────────────────
-// The per-domain generated types moved to the tenant `co2_nomos_domains` package
-// (`ts_packages/co2-nomos-domains/dart/lib/src/generated/`). The tenant barrel
-// (`package:co2_nomos_domains/co2_nomos_domains.dart`) re-exports THIS framework
-// barrel plus every generated domain — so importing it gives the whole typed
-// surface (framework primitives + tenant domains) through one import. The colliding
-// positional enums (`StatusEnum`/`KindEnum`/…) and their `hide` clauses now live on
-// the tenant barrel's exports, not here.

package/dart/lib/src/dev_cloud.dart

@@ -14,6 +14,11 @@
 // final remote = await cloud.remoteHead('estate');      // inspect remote head + commit count
 // await cloud.stop();
 // ```
+@internal
+library;
+
+import 'package:meta/meta.dart' show internal;
+
 import 'dart:async';
 import 'dart:convert';
 import 'dart:io';

package/dart/lib/src/home.dart

@@ -1,20 +1,15 @@
+@internal
+library;
+
+import 'package:meta/meta.dart' show internal;
+
 import 'dart:convert';
 
 import 'package:crypto/crypto.dart';
 
-/// The canonical home-workspace name for an identity SUBJECT (e.g. `user:<firebaseUid>`).
-///
-/// BYTE-IDENTICAL to `@githolon/client`'s `homeNameOf` and the law side
-/// (`dsl/src/framework/home.ts` `HOME_NAME_PREFIX`). A home holon is named by its SUBJECT — never the raw
-/// uid and never an app-chosen workspace name — so the same principal always resolves the same home, on
-/// every peer and on the cloud. Use it directly as the `workspace`:
-///
-/// ```dart
-/// NomosScope.home(application: 'my-app', authToken: idToken, ...)
-/// ```
-///
-/// Formula: `home-` + the first 40 hex chars of `sha256(utf8(subject))`.
-String homeNameOf(String subject) {
-  final hex = sha256.convert(utf8.encode(subject)).toString(); // lowercase hex
-  return 'home-${hex.substring(0, 40)}';
+/// Compiler/runtime-only receiving-group address. Generated application hosts call this; tenant code does
+/// not choose or persist framework workspace names.
+String nmsInternalReceivingGroupNameOf(String principal) {
+  final hex = sha256.convert(utf8.encode(principal)).toString();
+  return 'nomos-rg-${hex.substring(0, 40)}';
 }

package/dart/lib/src/nms_conformance_runtime.dart

@@ -0,0 +1,12 @@
+// Framework conformance surface. Nomos' own tests use this to exercise transport and lifecycle machinery.
+// Generated tenant tests use nms_test_environment.dart instead.
+@internal
+library;
+
+import 'package:meta/meta.dart' show internal;
+
+export 'dev_cloud.dart';
+export 'node_runner_transport.dart';
+export 'session_bound.dart';
+export 'test_harness.dart';
+export 'webview_bridge.dart';

package/dart/lib/src/nms_generated_runtime.dart

@@ -0,0 +1,29 @@
+/// Generator and framework-host implementation surface.
+///
+/// Deliberately lives under `src/`: tenant code imports its generated application package instead.
+@internal
+library;
+
+import 'package:meta/meta.dart' show internal;
+
+export 'package:nomos_types/nomos_types.dart';
+export 'package:nomos_types/src/nomos_ref.dart' show NmsInternalNomosRefs;
+export 'package:nomos_types/src/invitation.dart'
+    show NmsInternalInvitations, NmsInternalRecipients, NmsInternalUsers;
+export 'package:nomos_types/src/foreign_ref.dart'
+    show
+        NmsInternalForeignRefs,
+        NomosForeignReader,
+        NomosForeignWorkspaceReader,
+        ForeignResolveResult,
+        ForeignFound,
+        ForeignNotFound,
+        ForeignDenied,
+        ForeignUnreachable;
+export 'home.dart';
+export 'workspace_name.dart';
+export 'webview_bridge.dart';
+export 'session_bound.dart';
+export 'provider.dart';
+export 'record_origin.dart';
+export 'source_trust.dart';

package/dart/lib/src/nms_test_environment.dart

@@ -0,0 +1,8 @@
+// Framework implementation for generated business scenarios. Not a tenant entrypoint.
+@internal
+library;
+
+import 'package:meta/meta.dart' show internal;
+
+export 'dev_cloud.dart' show NomosTestCloud;
+export 'test_harness.dart' show NomosTestHarness;

package/dart/lib/src/node_runner_transport.dart

@@ -7,10 +7,17 @@
 //
 // This file is a PURE RELAY: no orchestration, no op knowledge — the protocol implementation lives in
 // createWebviewRunner (shared with the WebView path) and the orchestration in index.mjs, same as every peer.
+@internal
+library;
+
+import 'package:meta/meta.dart' show internal;
+
 import 'dart:async';
 import 'dart:convert';
 import 'dart:io';
 
+import 'package:package_config/package_config.dart' show loadPackageConfigUri;
+
 import 'webview_bridge.dart' show BridgeTransport;
 
 class NodeRunnerTransport implements BridgeTransport {
@@ -21,10 +28,8 @@ class NodeRunnerTransport implements BridgeTransport {
   bool _disposed = false;
 
   NodeRunnerTransport._(this._proc, this._onDiagnostic) {
-    _proc.stdout
-        .transform(utf8.decoder)
-        .transform(const LineSplitter())
-        .listen((line) {
+    _proc.stdout.transform(utf8.decoder).transform(const LineSplitter()).listen(
+        (line) {
       final s = line.trim();
       if (s.isEmpty) return;
       Object? decoded;
@@ -39,8 +44,8 @@ class NodeRunnerTransport implements BridgeTransport {
       }
     }, onDone: () {
       if (!_disposed && !_incoming.isClosed) {
-        _incoming.addError(
-            StateError('the nomos node runner exited unexpectedly'));
+        _incoming
+            .addError(StateError('the nomos node runner exited unexpectedly'));
       }
     });
     _proc.stderr
@@ -79,24 +84,57 @@ class NodeRunnerTransport implements BridgeTransport {
       node,
       [entryPath],
       environment: environment,
-      workingDirectory: resolveFrom,
+      // [resolveFrom] locates a packaged runner when [entry] is omitted; it is not a runtime dependency of
+      // an explicit, self-contained entry. Reusing it as cwd made copied release tests fail with ENOENT even
+      // though the selected runner existed and was executable.
+      workingDirectory: entry == null ? resolveFrom : null,
     );
     return NodeRunnerTransport._(proc, onDiagnostic);
   }
 
   static Future<String> _resolveEntry(String node, String from) async {
-    final r = await Process.run(
-      node,
-      ['-p', "require.resolve('@githolon/client/runner/node-entry.ts')"],
-      workingDirectory: from,
-    );
-    final out = (r.stdout as String).trim();
-    if (r.exitCode != 0 || out.isEmpty) {
-      throw StateError(
-          'cannot resolve @githolon/client/runner/node-entry.ts from $from — '
-          'is @githolon/client installed (npm install)? stderr: ${r.stderr}');
+    String? packageConfigPath = Platform.packageConfig;
+    if (packageConfigPath == null) {
+      var directory = Directory(from).absolute;
+      while (true) {
+        final candidate = File(
+          '${directory.path}${Platform.pathSeparator}.dart_tool${Platform.pathSeparator}package_config.json',
+        );
+        if (candidate.existsSync()) {
+          packageConfigPath = candidate.uri.toString();
+          break;
+        }
+        final parent = directory.parent;
+        if (parent.path == directory.path) break;
+        directory = parent;
+      }
+    }
+    if (packageConfigPath != null) {
+      final packages = await loadPackageConfigUri(
+        Uri.base.resolve(packageConfigPath),
+      );
+      final bundled = packages.resolve(
+        Uri.parse('package:nomos_client/src/runner/node-entry.mjs'),
+      );
+      if (bundled != null && bundled.scheme == 'file') {
+        final path = bundled.toFilePath();
+        if (File(path).existsSync()) return path;
+      }
+    }
+    for (final entry in const [
+      '@githolon/client/runner/node-entry.mjs',
+      '@githolon/client/runner/node-entry.ts',
+    ]) {
+      final r = await Process.run(
+        node,
+        ['-p', "require.resolve('$entry')"],
+        workingDirectory: from,
+      );
+      final out = (r.stdout as String).trim();
+      if (r.exitCode == 0 && out.isNotEmpty) return out;
     }
-    return out;
+    throw StateError('the Nomos release contains no bundled node runner and no '
+        '@githolon/client runner is installed; reinstall nomos_client');
   }
 
   @override

package/dart/lib/src/provider.dart

@@ -27,8 +27,11 @@
 /// This file is HAND-WRITTEN and domain-AGNOSTIC (declared ONCE, here): the generated
 /// per-task provider classes build on these interfaces, so the round-trip mechanism is
 /// proven once and reused for every capability.
+@internal
 library;
 
+import 'package:meta/meta.dart' show internal;
+
 import 'dart:convert';
 
 import 'package:nomos_types/nomos_types.dart' show NomosIntent;
@@ -122,7 +125,8 @@ abstract interface class TaskProvider<O, R> {
   /// [NomosIntent] ready for the ONE write path (`offer`). `now` stamps the
   /// terminal time. Decoding raw JSON happens HERE and only here; the handler the dev
   /// writes sees ONLY the typed [O] and returns ONLY a typed [TaskOutcome].
-  NomosIntent handleObligation(String obligationPayloadJson, {required HostClock now});
+  NomosIntent handleObligation(String obligationPayloadJson,
+      {required HostClock now});
 
   /// Convenience: decode an Obligation payload from an already-parsed map (the host may have
   /// the row's `data` map in hand from a read). Same path as [handleObligation].

package/dart/lib/src/record_origin.dart

@@ -0,0 +1,55 @@
+/// Private generated-client state tying a decoded business object to the
+/// workspace record it came from.
+///
+/// This deliberately lives under `src/` and is never exported by a tenant
+/// application package. Generated navigation and write facades use it so a
+/// business record can be passed to another business action without exposing
+/// workspace coordinates to tenant code.
+@internal
+library;
+
+import 'package:meta/meta.dart' show internal;
+
+final class NmsInternalRecordOrigin {
+  const NmsInternalRecordOrigin({
+    required this.workspace,
+    required this.type,
+    required this.id,
+  });
+
+  final String workspace;
+  final String type;
+  final String id;
+}
+
+final class NmsInternalRecordOrigins {
+  NmsInternalRecordOrigins._();
+
+  static final Expando<NmsInternalRecordOrigin> _origins =
+      Expando<NmsInternalRecordOrigin>('nms-record-origin');
+
+  static T remember<T>(
+    T record, {
+    required String workspace,
+    required String type,
+    required String id,
+  }) {
+    _origins[record as Object] = NmsInternalRecordOrigin(
+      workspace: workspace,
+      type: type,
+      id: id,
+    );
+    return record;
+  }
+
+  static NmsInternalRecordOrigin require(Object record) {
+    final origin = _origins[record];
+    if (origin == null) {
+      throw StateError(
+        'This business record was not read through its generated application. '
+        'Read or follow the record first, then pass that returned record to the action.',
+      );
+    }
+    return origin;
+  }
+}