@githolon/dsl 0.101.5 → 0.102.0

package/dart_types/lib/src/invitation.dart

@@ -0,0 +1,96 @@
+library;
+
+/// A framework-owned authority coordinate established from verified custody and representation.
+final class Identity<TSubject> {
+  final String id;
+  final String address;
+
+  const Identity._(this.id, this.address);
+}
+
+/// The durable, independently attributable participant using an application.
+///
+/// This is not a tenant Person row, login token, device, or application state.
+final class User {
+  final Identity<User> identity;
+
+  const User._(this.identity);
+}
+
+abstract final class NmsInternalUsers {
+  static User create(
+          {required String identityId, required String identityAddress}) =>
+      User._(Identity<User>._(identityId, identityAddress));
+}
+
+/// A framework-created delivery address for one User.
+///
+/// It is deliberately not a string: an email address, identity-provider uid,
+/// principal, record id, or arbitrary application value cannot be passed to a
+/// generated invitation action by mistake. A recipient carries no authority.
+final class Recipient<TSubject> {
+  final String _address;
+
+  const Recipient._(this._address);
+
+  @override
+  bool operator ==(Object other) =>
+      other is Recipient<TSubject> && other._address == _address;
+
+  @override
+  int get hashCode => _address.hashCode;
+
+  @override
+  String toString() => 'Recipient<$TSubject>';
+}
+
+/// A single-use invitation to become a recipient of a business grant.
+///
+/// Nomos owns creation, proof, redemption, replay rejection and delivery. Your
+/// product owns transport: put [link] in an email, message, QR code or any other
+/// channel. The transport address is never treated as the invited identity.
+final class Invitation<TSubject> {
+  final Recipient<TSubject> recipient;
+  final String _token;
+
+  const Invitation._(this.recipient, this._token);
+
+  /// Attach this invitation to your application's join URL.
+  ///
+  /// The capability is kept in the URL fragment so ordinary HTTP servers and
+  /// access logs do not receive it. The generated application redeems the link.
+  String link(String baseUrl) {
+    final base = Uri.parse(baseUrl);
+    if (!base.hasScheme || base.host.isEmpty) {
+      throw ArgumentError.value(baseUrl, 'baseUrl', 'must be an absolute URL');
+    }
+    return base.replace(fragment: 'nomos-invitation=$_token').toString();
+  }
+}
+
+/// Framework-only construction and wire lowering for generated clients.
+abstract final class NmsInternalInvitations {
+  static Recipient<TSubject> recipient<TSubject>(String address) {
+    if (address.trim().isEmpty)
+      throw StateError('Nomos produced an empty recipient address.');
+    return Recipient<TSubject>._(address);
+  }
+
+  static Invitation<TSubject> invitation<TSubject>({
+    required String address,
+    required String token,
+  }) =>
+      Invitation<TSubject>._(recipient<TSubject>(address), token);
+
+  static String address<TSubject>(Recipient<TSubject> recipient) =>
+      recipient._address;
+
+  static String token<TSubject>(Invitation<TSubject> invitation) =>
+      invitation._token;
+}
+
+/// Framework-only payload serializer used by generated directive classes.
+abstract final class NmsInternalRecipients {
+  static String address<TSubject>(Recipient<TSubject> recipient) =>
+      NmsInternalInvitations.address(recipient);
+}

package/dart_types/lib/src/nomos_ref.dart

@@ -1,75 +1,113 @@
-// NOMOS — THE ONE REFERENCE (architecture/nomos_ref.md). A [NomosRef] is the canonical, globally-unique,
-// workspace-qualified identity of an aggregate instance: `{ workspace, type, id }`, with the stable string
-// form `nomos://<workspace>/<type>/<id>`. It travels WITH the data by default — every generated read row,
-// write outcome, and activity ref carries (or views as) one — so a dev holding a thing can always point at
-// it: no client-side UUID pre-minting, no loose {workspaceId, id} string pairs, no re-query-and-diff.
+// NOMOS — THE ONE REFERENCE (architecture/nomos_ref.md).
 //
-// A NomosRef is a LOCATOR (like ForeignRef, which remains the TYPED per-field view): `resolve` is an
-// informational read over the device's multi-workspace plane; law-grade attestation stays on the declared
-// attested-read lane. Pure nomos_types — no bridge/lifecycle imports.
+// Tenant code gets a typed, inspectable identity value that it can retain, serialize and hand back to a
+// generated business action/read. It cannot construct one or use it to reach runtime machinery.
 library;
 
-import 'foreign_ref.dart';
+/// A framework-created, workspace-qualified reference to one generated aggregate type.
+///
+/// Nomos creates these from committed business outcomes and projected records. Keep the value and pass it
+/// to generated actions, `find` and `watchOne`; do not copy an id into application state. [TAggregate]
+/// prevents a reference to one business kind being passed where another is required.
+final class NomosRef<TAggregate> {
+  final String _workspace;
+  final String _type;
+  final String _id;
 
-/// The canonical typed reference to an aggregate instance: workspace + aggregate type + instance id.
-/// Value semantics; `uri` is the stable interop string (`nomos://<workspace>/<type>/<id>`).
-class NomosRef {
-  /// The workspace holding the instance.
-  final String workspace;
+  const NomosRef._(this._workspace, this._type, this._id);
 
-  /// The aggregate TYPE (the read-projection type tag, e.g. `estate.EstateSite` or `EstateSite`).
-  final String type;
+  /// The application/workspace that owns the record.
+  String get workspace => _workspace;
 
-  /// The instance id (law-minted or law-defined).
-  final String id;
+  /// The stable aggregate kind carried by this reference.
+  String get type => _type;
 
-  const NomosRef({required this.workspace, required this.type, required this.id});
+  /// The stable identity of the record within its workspace.
+  String get id => _id;
 
-  /// The stable string form — survives URLs, nav params, JSON, logs. Segments are URI-encoded so a
-  /// workspace/type/id containing `/` or spaces round-trips.
-  String get uri =>
-      'nomos://${Uri.encodeComponent(workspace)}/${Uri.encodeComponent(type)}/${Uri.encodeComponent(id)}';
+  /// The stable, portable address of this business record.
+  ///
+  /// Keep this in navigation state, URLs or messages when another part of the
+  /// application needs to recover the typed reference through its generated
+  /// aggregate collection. An address never grants access: generated reads and
+  /// actions still verify the signed-in person's authority when it is used.
+  String get address => 'nomos://${Uri.encodeComponent(_workspace)}/'
+      '${Uri.encodeComponent(_type)}/${Uri.encodeComponent(_id)}';
 
-  /// Parse a `nomos://<workspace>/<type>/<id>` string (the inverse of [uri]). Throws [FormatException]
-  /// on anything else.
-  factory NomosRef.parse(String uri) {
-    final u = Uri.tryParse(uri);
-    if (u == null || u.scheme != 'nomos') {
-      throw FormatException('NomosRef.parse: not a nomos:// uri', uri);
-    }
-    // nomos://<ws>/<type>/<id> — the workspace lands as the authority (host), type/id as path segments.
-    final ws = Uri.decodeComponent(u.host);
-    final segs = u.pathSegments.map(Uri.decodeComponent).toList();
-    if (ws.isEmpty || segs.length != 2 || segs[0].isEmpty || segs[1].isEmpty) {
-      throw FormatException('NomosRef.parse: expected nomos://<workspace>/<type>/<id>', uri);
-    }
-    return NomosRef(workspace: ws, type: segs[0], id: segs[1]);
-  }
+  @override
+  bool operator ==(Object other) =>
+      other is NomosRef<Object?> &&
+      other._workspace == _workspace &&
+      other._type == _type &&
+      other._id == _id;
+
+  @override
+  int get hashCode => Object.hash(_workspace, _type, _id);
+
+  @override
+  String toString() => 'NomosRef<$TAggregate>';
+}
+
+/// Framework-only codec and locator access for generated implementation code.
+///
+/// This is intentionally withheld from `package:nomos_types/nomos_types.dart` and from generated tenant
+/// package barrels. It exists because Dart privacy is library-scoped: generated implementation libraries
+/// need one explicit, auditable construction and wire-codec door while tenant code receives [NomosRef].
+abstract final class NmsInternalNomosRefs {
+  static NomosRef<TAggregate> create<TAggregate>({
+    required String workspace,
+    required String type,
+    required String id,
+  }) =>
+      NomosRef<TAggregate>._(workspace, type, id);
 
-  /// Accepts the `{workspace,type,id}` object OR the `nomos://` uri string.
-  factory NomosRef.fromJson(Object? j) {
-    if (j is String) return NomosRef.parse(j);
-    final m = (j as Map).cast<String, dynamic>();
-    return NomosRef(
-      workspace: (m['workspace'] ?? '') as String,
-      type: (m['type'] ?? '') as String,
-      id: (m['id'] ?? '') as String,
+  static String workspace<TAggregate>(NomosRef<TAggregate> reference) =>
+      reference._workspace;
+
+  static String type<TAggregate>(NomosRef<TAggregate> reference) =>
+      reference._type;
+
+  static String id<TAggregate>(NomosRef<TAggregate> reference) => reference._id;
+
+  static NomosRef<TAggregate> fromJson<TAggregate>(Object? value) {
+    if (value is String) return fromUri<TAggregate>(value);
+    final map = (value as Map).cast<String, dynamic>();
+    return create<TAggregate>(
+      workspace: (map['workspace'] ?? '') as String,
+      type: (map['type'] ?? '') as String,
+      id: (map['id'] ?? '') as String,
     );
   }
 
-  Map<String, dynamic> toJson() => {'workspace': workspace, 'type': type, 'id': id};
+  static Map<String, dynamic> toJson<TAggregate>(
+    NomosRef<TAggregate> reference,
+  ) =>
+      {
+        'workspace': reference._workspace,
+        'type': reference._type,
+        'id': reference._id,
+      };
 
-  /// Informational lookup of the referenced instance over the device's multi-workspace plane (the same
-  /// reader `ForeignRef.resolve` uses — `bridge.foreignReader()` in nomos_client). Returns the raw
-  /// `{type,id,data}` rows for the id in the ref's workspace (empty ⇒ not found / not visible).
-  Future<List<Map<String, dynamic>>> resolve(NomosForeignReader nomos) =>
-      nomos.foreignWorkspace(workspace).queryById(id);
+  static NomosRef<TAggregate> fromUri<TAggregate>(String value) {
+    final uri = Uri.tryParse(value);
+    if (uri == null || uri.scheme != 'nomos') {
+      throw FormatException('Expected a Nomos reference', value);
+    }
+    final workspace = Uri.decodeComponent(uri.host);
+    final segments = uri.pathSegments.map(Uri.decodeComponent).toList();
+    if (workspace.isEmpty ||
+        segments.length != 2 ||
+        segments[0].isEmpty ||
+        segments[1].isEmpty) {
+      throw FormatException('Expected a complete Nomos reference', value);
+    }
+    return create<TAggregate>(
+      workspace: workspace,
+      type: segments[0],
+      id: segments[1],
+    );
+  }
 
-  @override
-  bool operator ==(Object other) =>
-      other is NomosRef && other.workspace == workspace && other.type == type && other.id == id;
-  @override
-  int get hashCode => Object.hash(workspace, type, id);
-  @override
-  String toString() => uri;
+  static String toUri<TAggregate>(NomosRef<TAggregate> reference) =>
+      reference.address;
 }

package/dart_types/pubspec.yaml

@@ -9,7 +9,7 @@ description: >-
   Pure kernel wire/data types for Nomos Dart frontends — no transport, no bridge,
   no runtime. The hand-written serde-JSON-compatible types plus the offer codec,
   reactive read engine, schema validation, and data-only error/trace types.
-version: 0.7.1
+version: 0.8.0
 
 environment:
   sdk: ^3.5.0

package/dart_types/test/surfaced_test.dart

@@ -1,7 +1,92 @@
 import 'package:nomos_types/nomos_types.dart';
+import 'package:nomos_types/src/invitation.dart' show NmsInternalInvitations;
+import 'package:nomos_types/src/nomos_ref.dart' show NmsInternalNomosRefs;
 import 'package:test/test.dart';
 
+final class _Asset {}
+
 void main() {
+  test(
+      'Invitation is transport-neutral and keeps its capability in the URL fragment',
+      () {
+    final invitation = NmsInternalInvitations.invitation<User>(
+      address: 'nomos-invitation:v1:public-key',
+      token: 'bearer-capability',
+    );
+
+    final link = invitation.link('https://tenant.example/join?campaign=summer');
+    final uri = Uri.parse(link);
+    expect(uri.origin, 'https://tenant.example');
+    expect(uri.path, '/join');
+    expect(uri.queryParameters, {'campaign': 'summer'});
+    expect(uri.fragment, 'nomos-invitation=bearer-capability');
+    expect(invitation.toString(), isNot(contains('bearer-capability')));
+  });
+
+  test('NomosRef compares by its public address', () {
+    final first = NmsInternalNomosRefs.create<_Asset>(
+      workspace: 'estate-one',
+      type: 'EstateAsset',
+      id: 'asset-one',
+    );
+    final same = NmsInternalNomosRefs.create<_Asset>(
+      workspace: 'estate-one',
+      type: 'EstateAsset',
+      id: 'asset-one',
+    );
+    final differentWorkspace = NmsInternalNomosRefs.create<_Asset>(
+      workspace: 'estate-two',
+      type: 'EstateAsset',
+      id: 'asset-one',
+    );
+
+    expect(first, same);
+    expect(first.hashCode, same.hashCode);
+    expect(first, isNot(differentWorkspace));
+    expect(first.workspace, 'estate-one');
+    expect(first.type, 'EstateAsset');
+    expect(first.id, 'asset-one');
+    expect(first.address, 'nomos://estate-one/EstateAsset/asset-one');
+    expect(NmsInternalNomosRefs.fromUri<_Asset>(first.address), first);
+  });
+
+  test('NomosRef address round-trips escaped public identity', () {
+    final reference = NmsInternalNomosRefs.create<_Asset>(
+      workspace: 'estate/one',
+      type: 'Estate Asset',
+      id: 'asset/one',
+    );
+
+    expect(
+      reference.address,
+      'nomos://estate%2Fone/Estate%20Asset/asset%2Fone',
+    );
+    expect(NmsInternalNomosRefs.fromUri<_Asset>(reference.address), reference);
+  });
+
+  test(
+      'business activity names who performed it without exposing an actor lane',
+      () {
+    const event = ActivityEvent(
+      eventId: 'event-1',
+      kind: 'estate.created',
+      performedBy: 'user:ada',
+      occurredAt: '2026-07-20T00:00:00Z',
+      title: 'Estate created',
+      message: 'Ada created the estate',
+      titleKey: 'activity.estate.created.title',
+      messageKey: 'activity.estate.created.message',
+      params: {},
+      refs: {},
+      severity: ActivitySeverity.success,
+      domain: 'estate',
+      directiveId: 'createEstate',
+    );
+    expect(event.performedBy, 'user:ada');
+    expect(event.toJson(), containsPair('performedBy', 'user:ada'));
+    expect(event.toJson(), isNot(contains('actorSubject')));
+  });
+
   group('SurfacedValue', () {
     test('a plain scalar decodes RESOLVED', () {
       final v = SurfacedValue<String>.fromJson('hello', (x) => x as String);
@@ -11,7 +96,9 @@ void main() {
       expect(v.pending, isEmpty);
     });
 
-    test('the __surfaced envelope decodes PENDING (value + occurredAt + nullable author)', () {
+    test(
+        'the __surfaced envelope decodes PENDING (value + occurredAt + nullable author)',
+        () {
       final v = SurfacedValue<String>.fromJson({
         '__surfaced': {
           'pending': [
@@ -34,29 +121,41 @@ void main() {
       expect(v.pending, hasLength(2));
       expect(v.pending[0].value, 'a');
       expect(v.pending[0].author, 'user:ada');
-      expect(v.pending[0].occurredAt, const Hlc(physical: 10, logical: 1, replica: 7));
+      expect(v.pending[0].occurredAt,
+          const Hlc(physical: 10, logical: 1, replica: 7));
       expect(v.pending[1].value, 'b');
       expect(v.pending[1].author, isNull);
     });
 
-    test('decode() off a flat data map: absent/null => null (partial-fold doctrine)', () {
-      expect(SurfacedValue.decode<String>({}, 'title', (x) => x as String), isNull);
-      expect(SurfacedValue.decode<String>({'title': null}, 'title', (x) => x as String), isNull);
-      final v = SurfacedValue.decode<String>({'title': 't'}, 'title', (x) => x as String);
+    test(
+        'decode() off a flat data map: absent/null => null (partial-fold doctrine)',
+        () {
+      expect(SurfacedValue.decode<String>({}, 'title', (x) => x as String),
+          isNull);
+      expect(
+          SurfacedValue.decode<String>(
+              {'title': null}, 'title', (x) => x as String),
+          isNull);
+      final v = SurfacedValue.decode<String>(
+          {'title': 't'}, 'title', (x) => x as String);
       expect(v, const SurfacedResolved<String>('t'));
     });
 
-    test('mixed-schema values stay withheld until field evolution is available', () {
-      final v = SurfacedValue<String>.fromJson({
-        '__surfaced': {
-          'status': 'evolutionRequired',
-          'targetSchema': 'title-v2',
-          'evolution': {
-            'sourceSchemas': ['title-v1'],
-            'authoredUnder': ['law-v1'],
+    test('mixed-schema values stay withheld until field evolution is available',
+        () {
+      final v = SurfacedValue<String>.fromJson(
+          {
+            '__surfaced': {
+              'status': 'evolutionRequired',
+              'targetSchema': 'title-v2',
+              'evolution': {
+                'sourceSchemas': ['title-v1'],
+                'authoredUnder': ['law-v1'],
+              },
+            },
           },
-        },
-      }, (_) => throw StateError('must not cast an old value to the current type'));
+          (_) => throw StateError(
+              'must not cast an old value to the current type'));
       expect(v, isA<SurfacedEvolutionRequired<String>>());
       final blocked = v as SurfacedEvolutionRequired<String>;
       expect(blocked.targetSchema, 'title-v2');
@@ -66,18 +165,25 @@ void main() {
     });
 
     test('value equality holds on both arms', () {
-      expect(const SurfacedResolved<String>('x'), const SurfacedResolved<String>('x'));
+      expect(const SurfacedResolved<String>('x'),
+          const SurfacedResolved<String>('x'));
       final p1 = SurfacedValue<String>.fromJson({
         '__surfaced': {
           'pending': [
-            {'value': 'a', 'occurredAt': {'physical': 1, 'logical': 0, 'replica': 1}},
+            {
+              'value': 'a',
+              'occurredAt': {'physical': 1, 'logical': 0, 'replica': 1}
+            },
           ],
         },
       }, (x) => x as String);
       final p2 = SurfacedValue<String>.fromJson({
         '__surfaced': {
           'pending': [
-            {'value': 'a', 'occurredAt': {'physical': 1, 'logical': 0, 'replica': 1}},
+            {
+              'value': 'a',
+              'occurredAt': {'physical': 1, 'logical': 0, 'replica': 1}
+            },
           ],
         },
       }, (x) => x as String);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.101.5",
+  "version": "0.102.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",
@@ -21,6 +21,7 @@
     "./compose": "./src/compose.ts",
     "./usd": "./src/usd.ts",
     "./usd-layers": "./src/usd_layers.ts",
+    "./application-composition": "./src/application_composition.ts",
     "./usd-state": "./src/usd_state.ts",
     "./engine-entry": "./src/engine_entry.ts",
     "./workspace-type": "./src/workspace_type.ts",
@@ -31,7 +32,6 @@
     "./codegen-dart": "./src/codegen_dart.ts",
     "./codegen-dot": "./src/codegen_dot.ts",
     "./codegen-provider": "./src/codegen_provider_dart.ts",
-    "./framework/identity": "./src/framework/identity.ts",
     "./framework/disclosure": "./src/framework/disclosure.ts",
     "./framework/bootstrap": "./src/framework/bootstrap.ts",
     "./framework/domain_lifecycle": "./src/framework/domain_lifecycle.ts",
@@ -43,12 +43,14 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/framework/identity.ts",
     "dart",
     "!dart/.dart_tool",
     "!dart/build",
     "dart_types",
     "!dart_types/.dart_tool",
     "!dart_types/build",
+    "runtime",
     "compile_package.mjs",
     "check_package.mjs",
     "compat_package.mjs",
@@ -58,19 +60,21 @@
     "access": "public"
   },
   "scripts": {
+    "build:application-runtime": "node scripts/build_application_runtime.mjs",
+    "prepack": "npm run build:application-runtime",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
   "dependencies": {
     "esbuild": "0.24.2",
     "tsx": "^4.19.2",
+    "typescript": "^5.6.3",
     "vscode-languageserver": "^9.0.1",
     "vscode-languageserver-textdocument": "^1.0.12",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^25.9.2",
-    "typescript": "^5.6.3",
     "vitest": "^2.1.8"
   }
 }