@githolon/dsl 0.66.0 → 0.68.0

package/dart/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 0.45.0
+
+- `offerOutcome(...)` — the one outcome-returning offer lane generated clients now call for EVERY directive:
+  returns `NomosOfferOutcome` with workspace-stamped `created` (`NomosCreated` gains `workspace` + a
+  `NomosRef get ref` view). Activity raw rows carry `created` + `workspace`. Requires `nomos_types >= 0.1.3`.
+
+## 0.44.0
+
+- Activity-feed runtime reads on `NomosBridge`/`NomosSession`: `activityLog({base, limit})` — the committed
+  intent log as raw rows `{intentId, domain, directiveId, actorSubject, occurredAt, payload}` (decoded
+  payload; the verified author; the physical HLC) — and `watchActivity({base})`, a stream re-deriving the
+  feed on every sync tick. Generic (raw Maps); the generated `renderActivity` (from directives' declared
+  `.activity()` metadata) types them into `ActivityEvent`s. Requires `nomos_types >= 0.1.2`.
+
 ## 0.43.0
 
 - `NomosBridge.foreignReader({cloud})` — a `NomosForeignReader` backed by the device's multi-workspace bridge

package/dart/lib/src/webview_bridge.dart

@@ -23,6 +23,7 @@ import 'package:nomos_types/nomos_types.dart'
         nomosErrorFromInfo,
         NomosTraceContext,
         NomosErrorInfo,
+        NomosRef,
         NomosForeignReader,
         NomosForeignWorkspaceReader,
         ForeignAttestation;
@@ -104,7 +105,15 @@ class SyncStatus {
 class NomosCreated {
   final String type;
   final String id;
-  const NomosCreated({required this.type, required this.id});
+
+  /// The workspace the offer ran on (NomosRef). Additive — defaults to '' on older runners that
+  /// don't stamp it; then [ref] is workspace-blank (still a valid locator on the local plane).
+  final String workspace;
+  const NomosCreated({required this.type, required this.id, this.workspace = ''});
+
+  /// The canonical [NomosRef] view — the `{workspace,type,id}` triple, followable/serializable
+  /// (`nomos://<workspace>/<type>/<id>`). One reference, everywhere.
+  NomosRef get ref => NomosRef(workspace: workspace, type: type, id: id);
   @override
   String toString() => id;
 }
@@ -604,6 +613,10 @@ class NomosOfferOutcome {
   final String head;
   final List<NomosCreated> created;
 
+  /// The workspace the offer ran on (NomosRef). Additive; '' on older runners. Each [created] ref already
+  /// carries this, so `outcome.created.first.ref` is the full followable `{workspace,type,id}` locator.
+  final String workspace;
+
   /// The born child workspace name(s), when the offer ran a `.births()` directive (else empty). Each is a
   /// LOCAL workspace on this device's plane, resident in the shared engine plane the moment it is born:
   /// `bridge.session(name)` returns its handle, and `bridge.connect(session: name)` (no `restoreFrom`) mounts
@@ -616,6 +629,7 @@ class NomosOfferOutcome {
   const NomosOfferOutcome({
     required this.head,
     required this.created,
+    this.workspace = '',
     this.born = const [],
     this.birthOutcomes = const [],
   });
@@ -965,6 +979,32 @@ class NomosBridge {
     List<Map<String, Object?>>? attestations,
     bool? force,
     String? session,
+  }) =>
+      offerOutcome(
+        domain: domain,
+        directiveId: directiveId,
+        payload: payload,
+        actor: actor,
+        domainHash: domainHash,
+        attestations: attestations,
+        force: force,
+        session: session,
+      );
+
+  /// THE ONE OUTCOME-RETURNING OFFER LANE — [offerDirective] answering the full typed [NomosOfferOutcome]
+  /// (head + law-minted `created` NomosRefs + births), for EVERY generated method (create or mutate). A pure
+  /// mutation returns `created: []`; a `.creates(...)` plan returns the minted aggregate id(s), each already
+  /// carrying the session [workspace] so `outcome.created.first.ref` is a complete followable NomosRef with no
+  /// query-after round-trip. [offerCreates] is the historical alias (identical behavior).
+  Future<NomosOfferOutcome> offerOutcome({
+    required String domain,
+    required String directiveId,
+    required Object? payload,
+    String? actor,
+    String? domainHash,
+    List<Map<String, Object?>>? attestations,
+    bool? force,
+    String? session,
   }) async {
     final r = _asMap(await _call('offerDirective', {
       'domain': domain,
@@ -992,13 +1032,17 @@ class NomosBridge {
             .map((m) => (m['workspace'] ?? '').toString())
             .where((s) => s.isNotEmpty),
     ]..removeWhere((s) => s.isEmpty);
+    // The offer ran on this workspace (NomosRef) — stamp every minted ref with it so it is a complete locator.
+    final ws = (r['workspace'] ?? '').toString();
     return NomosOfferOutcome(
       head: r['head'].toString(),
+      workspace: ws,
       created: ((r['created'] as List?) ?? const [])
           .whereType<Map>()
           .map((m) => NomosCreated(
               type: (m['type'] ?? '').toString(),
-              id: (m['id'] ?? '').toString()))
+              id: (m['id'] ?? '').toString(),
+              workspace: ws))
           .toList(),
       born: bornNames,
       birthOutcomes: births,
@@ -1168,6 +1212,26 @@ class NomosBridge {
         .toList();
   }
 
+  /// RUNTIME activity feed — per-committed-intent rows (newest-first) from the local ledger, each carrying
+  /// `{intentId, domain, directiveId, actorSubject, occurredAt, payload}` (payload = the DECODED directive
+  /// payload). `base` = a commit-oid cursor (only intents newer than it); omitted = from the tip bounded by
+  /// `limit` (default 200). Generic raw rows — the typed shaping is the codegen `renderActivity`.
+  Future<List<Map<String, dynamic>>> activityLog(
+      {String? base, int? limit}) async {
+    final r = _asMap(await _call('activityLog', {
+      if (base != null) 'base': base,
+      if (limit != null) 'limit': limit,
+    }));
+    return ((r['rows'] as List?) ?? const [])
+        .map((e) => (e as Map).cast<String, dynamic>())
+        .toList();
+  }
+
+  /// Watch the RUNTIME activity feed: a stream that re-emits the newest-first activity rows on every local
+  /// change (doorbell/sync tick). `base` = a commit-oid cursor. Cancelling drops the watch on the runner.
+  Stream<List<dynamic>> watchActivity({String? base, String? session}) =>
+      _watchStream(kind: 'activity', base: base, session: session);
+
   /// Mint an ed25519 DEVICE KEY in-kernel → `{secret, public}` (base64). The SECRET stays on this device
   /// (persist it in secure storage); pass it to [connect] as `authorSecret` (or per-offer `signWith`) so the
   /// holon SIGNS each intent. The PUBLIC half is what gets enrolled so the gate re-verifies the signature on
@@ -1594,6 +1658,7 @@ class NomosBridge {
       String? id,
       String? spatialId,
       NomosBbox? bbox,
+      String? base,
       String? session}) {
     final subId = 'w${++_seq}';
     late final StreamController<List<dynamic>> ctrl;
@@ -1606,6 +1671,7 @@ class NomosBridge {
         if (id != null) 'id': id,
         if (spatialId != null) 'spatialId': spatialId,
         if (bbox != null) 'bbox': bbox.toJson(),
+        if (base != null) 'base': base,
         if (session != null) 'session': session,
       }),
       onCancel: () async {
@@ -1709,6 +1775,9 @@ class NomosSession extends NomosBridge {
           [String? session]) =>
       parent.watchSpatial(spatialId, bbox, session ?? workspace);
   @override
+  Stream<List<dynamic>> watchActivity({String? base, String? session}) =>
+      parent.watchActivity(base: base, session: session ?? workspace);
+  @override
   Stream<Map<String, Object?>> watchCompatibility(
           Map<String, Object?> requirement,
           [String? session]) =>

package/dart/pubspec.lock

@@ -191,7 +191,7 @@ packages:
       path: "../dart_types"
       relative: true
     source: path
-    version: "0.1.0"
+    version: "0.1.2"
   package_config:
     dependency: transitive
     description:

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.43.0
+version: 0.45.0
 
 environment:
   sdk: ^3.5.0
@@ -20,7 +20,7 @@ dependencies:
   # The pure-data core (wire types, offer codec, NomosReads, schema validation, error
   # info). nomos_client depends on and re-exports it, so existing imports are unchanged.
   # For local monorepo dev, pubspec_overrides.yaml points this at ../dart_types.
-  nomos_types: ^0.1.1
+  nomos_types: ^0.1.3
   json_schema: ^5.2.2
   crypto: ^3.0.0
 

package/dart_types/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 0.1.3
+
+- `NomosRef` — THE one typed reference `{workspace, type, id}`: value semantics, the canonical
+  `nomos://<workspace>/<type>/<id>` uri (`uri`/`parse`, encode round-trip), `fromJson` (object or uri),
+  `resolve()` over the multi-workspace reader. `ActivityRef` gains `workspace` + a `.ref` view; `ForeignRef`
+  gains `.ref`. Every reference shape now converges on the one triple. Purely additive.
+
+## 0.1.2
+
+- Activity-feed runtime types: `ActivityEvent` (the shared activity row — kind/actor/occurredAt, rendered
+  title+message, stable `titleKey`/`messageKey` + params for localization, typed `refs`, category/icon/
+  severity, domain/directiveId provenance), `ActivityRef`, `ActivitySeverity`, `renderActivityTemplate`.
+  Consumed by the generated `renderActivity`/`describe`/`describeHistory`. Purely additive.
+
 ## 0.1.1
 
 - Add `t.foreignRef` runtime types: `ForeignRef<T>` (a typed cross-workspace locator), `NomosForeignReader` /

package/dart_types/lib/nomos_types.dart

@@ -31,3 +31,5 @@ export 'src/errors.dart';
 // `NomosForeignReader`/`NomosForeignWorkspaceReader` read surfaces + the named resolve outcomes. Pure data +
 // abstract interfaces (no bridge) — so both the layered TYPES package and nomos_client resolve them.
 export 'src/foreign_ref.dart';
+export 'src/activity.dart';
+export 'src/nomos_ref.dart';

package/dart_types/lib/src/activity.dart

@@ -0,0 +1,173 @@
+// NOMOS — the ACTIVITY-FEED runtime types (directive `.activity(...)` descriptors). The shared, tenant-
+// agnostic shape a client renders from the intent log: a directive DECLARES its activity metadata (kind,
+// message template, refs, params) and the generated `renderActivity` turns each committed intent into an
+// [ActivityEvent] — no string-enricher guessing meaning beside the truth. The kernel/ledger stays the audit
+// truth; this is a pure client-side human projection.
+//
+// These live in the pure `nomos_types` core (no bridge/lifecycle) so BOTH the layered TYPES package (where
+// the generated pure `renderActivity` lives) AND the runtime `nomos_client` package resolve them.
+library;
+
+import 'nomos_ref.dart';
+
+/// A declared navigation target on an activity row: the referenced aggregate/contract TYPE + the resolved id
+/// (read from a payload field the directive named). Replaces the old enricher's blind id-probing — the app
+/// knows exactly what `id` points at and can deep-link/resolve it.
+class ActivityRef {
+  final String type;
+  final String id;
+
+  /// The source workspace (additive — empty on rows rendered before refs carried it).
+  final String workspace;
+
+  const ActivityRef({required this.type, required this.id, this.workspace = ''});
+
+  /// The canonical reference view (`nomos://<workspace>/<type>/<id>`).
+  NomosRef get ref => NomosRef(workspace: workspace, type: type, id: id);
+
+  factory ActivityRef.fromJson(Map<String, dynamic> j) => ActivityRef(
+      type: (j['type'] ?? '') as String,
+      id: (j['id'] ?? '') as String,
+      workspace: (j['workspace'] ?? '') as String);
+  Map<String, dynamic> toJson() =>
+      {'type': type, 'id': id, if (workspace.isNotEmpty) 'workspace': workspace};
+
+  @override
+  bool operator ==(Object other) =>
+      other is ActivityRef && other.type == type && other.id == id && other.workspace == workspace;
+  @override
+  int get hashCode => Object.hash(type, id, workspace);
+}
+
+/// Row prominence — a declared default the app may style or threshold on.
+enum ActivitySeverity {
+  info,
+  success,
+  warning,
+  critical;
+
+  static ActivitySeverity fromWire(String? s) {
+    switch (s) {
+      case 'success':
+        return ActivitySeverity.success;
+      case 'warning':
+        return ActivitySeverity.warning;
+      case 'critical':
+        return ActivitySeverity.critical;
+      default:
+        return ActivitySeverity.info;
+    }
+  }
+
+  String get wire => name;
+}
+
+/// A rendered activity row — the tenant-agnostic "tiny shared activity contract". Produced by the generated
+/// `renderActivity(intentMeta, payload)` from a directive's declared `.activity(...)` descriptor. The UI
+/// consumes this directly (title/message already interpolated; `refs` for navigation; `titleKey`/`messageKey`
+/// + `params` for later localization).
+class ActivityEvent {
+  /// The intent id — a stable per-event identity (dedupe/order key).
+  final String eventId;
+
+  /// The declared STABLE event kind (e.g. `"site.created"`).
+  final String kind;
+
+  /// The intent's author (principal) — the "who".
+  final String actorSubject;
+
+  /// When it happened (the intent's physical HLC timestamp, ISO-8601 when available).
+  final String occurredAt;
+
+  /// The rendered title (template interpolated); [titleKey] + [params] localize it later.
+  final String title;
+
+  /// The rendered message (template interpolated); [messageKey] + [params] localize it later.
+  final String message;
+
+  /// Stable i18n key for the title (`activity.<kind>.title`).
+  final String titleKey;
+
+  /// Stable i18n key for the message (`activity.<kind>.message`).
+  final String messageKey;
+
+  /// The interpolation params (name → display value, read from the payload) — for localized re-rendering.
+  final Map<String, String> params;
+
+  /// Declared navigation targets (name → typed ref).
+  final Map<String, ActivityRef> refs;
+
+  /// Optional grouping category (e.g. `"estate"`).
+  final String? category;
+
+  /// Optional default icon token (app-interpreted).
+  final String? icon;
+
+  /// Row prominence (default [ActivitySeverity.info]).
+  final ActivitySeverity severity;
+
+  /// Provenance — the domain + directive that produced this event.
+  final String domain;
+  final String directiveId;
+
+  const ActivityEvent({
+    required this.eventId,
+    required this.kind,
+    required this.actorSubject,
+    required this.occurredAt,
+    required this.title,
+    required this.message,
+    required this.titleKey,
+    required this.messageKey,
+    required this.params,
+    required this.refs,
+    required this.severity,
+    required this.domain,
+    required this.directiveId,
+    this.category,
+    this.icon,
+  });
+
+  factory ActivityEvent.fromJson(Map<String, dynamic> j) => ActivityEvent(
+        eventId: (j['eventId'] ?? '') as String,
+        kind: (j['kind'] ?? '') as String,
+        actorSubject: (j['actorSubject'] ?? '') as String,
+        occurredAt: (j['occurredAt'] ?? '') as String,
+        title: (j['title'] ?? '') as String,
+        message: (j['message'] ?? '') as String,
+        titleKey: (j['titleKey'] ?? '') as String,
+        messageKey: (j['messageKey'] ?? '') as String,
+        params: ((j['params'] as Map?)?.cast<String, dynamic>() ?? const {})
+            .map((k, v) => MapEntry(k, '$v')),
+        refs: ((j['refs'] as Map?)?.cast<String, dynamic>() ?? const {})
+            .map((k, v) => MapEntry(k, ActivityRef.fromJson((v as Map).cast<String, dynamic>()))),
+        category: j['category'] as String?,
+        icon: j['icon'] as String?,
+        severity: ActivitySeverity.fromWire(j['severity'] as String?),
+        domain: (j['domain'] ?? '') as String,
+        directiveId: (j['directiveId'] ?? '') as String,
+      );
+
+  Map<String, dynamic> toJson() => {
+        'eventId': eventId,
+        'kind': kind,
+        'actorSubject': actorSubject,
+        'occurredAt': occurredAt,
+        'title': title,
+        'message': message,
+        'titleKey': titleKey,
+        'messageKey': messageKey,
+        'params': params,
+        'refs': refs.map((k, v) => MapEntry(k, v.toJson())),
+        if (category != null) 'category': category,
+        if (icon != null) 'icon': icon,
+        'severity': severity.wire,
+        'domain': domain,
+        'directiveId': directiveId,
+      };
+}
+
+/// Interpolate `{name}` placeholders in [template] from [vars] — the render helper the generated
+/// `renderActivity` uses. A missing var renders empty (the compiler already validated every placeholder).
+String renderActivityTemplate(String template, Map<String, String> vars) =>
+    template.replaceAllMapped(RegExp(r'\{([a-zA-Z0-9_]+)\}'), (m) => vars[m.group(1)] ?? '');

package/dart_types/lib/src/foreign_ref.dart

@@ -14,6 +14,8 @@
 // this barrel, and its `NomosBridge` implements [NomosForeignReader] over the device's multi-workspace plane.
 library;
 
+import 'nomos_ref.dart';
+
 /// Reads a FOREIGN workspace on demand — the surface a [ForeignRef] resolves against. It is STRUCTURAL: any
 /// object with this shape works. `nomos_client`'s `NomosBridge` implements it over the device's local
 /// multi-workspace plane (`bridge.session(ws).queryById(id)`, mounting the workspace lazily); the TS twin is
@@ -111,6 +113,10 @@ class ForeignRef<T> {
   /// The foreign aggregate type this locator points at.
   final String type;
 
+  /// The canonical reference view (`nomos://<workspace>/<type>/<id>`) — a [ForeignRef] IS a typed view over
+  /// the one reference triple.
+  NomosRef get ref => NomosRef(workspace: workspace, type: type, id: id);
+
   /// The target's decoder (the aggregate `fromJson` factory), applied to a resolved row's flat `data` map.
   final T Function(Map<String, dynamic> data, [String id]) _decode;
 

package/dart_types/lib/src/nomos_ref.dart

@@ -0,0 +1,75 @@
+// 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.
+//
+// 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.
+library;
+
+import 'foreign_ref.dart';
+
+/// 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;
+
+  /// The aggregate TYPE (the read-projection type tag, e.g. `estate.EstateSite` or `EstateSite`).
+  final String type;
+
+  /// The instance id (law-minted or law-defined).
+  final String id;
+
+  const NomosRef({required this.workspace, required this.type, required this.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)}';
+
+  /// 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]);
+  }
+
+  /// 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,
+    );
+  }
+
+  Map<String, dynamic> toJson() => {'workspace': workspace, 'type': type, 'id': 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);
+
+  @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;
+}

package/dart_types/pubspec.yaml

@@ -11,7 +11,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.1.1
+version: 0.1.3
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.66.0",
+  "version": "0.68.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",