@githolon/dsl 0.66.0 → 0.67.0

package/dart/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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

@@ -1168,6 +1168,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 +1614,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 +1627,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 +1731,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.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.44.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.2
   json_schema: ^5.2.2
   crypto: ^3.0.0
 

package/dart_types/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 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,4 @@ 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';

package/dart_types/lib/src/activity.dart

@@ -0,0 +1,160 @@
+// 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;
+
+/// 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;
+  const ActivityRef({required this.type, required this.id});
+
+  factory ActivityRef.fromJson(Map<String, dynamic> j) =>
+      ActivityRef(type: (j['type'] ?? '') as String, id: (j['id'] ?? '') as String);
+  Map<String, dynamic> toJson() => {'type': type, 'id': id};
+
+  @override
+  bool operator ==(Object other) => other is ActivityRef && other.type == type && other.id == id;
+  @override
+  int get hashCode => Object.hash(type, id);
+}
+
+/// 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/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.2
 
 environment:
   sdk: ^3.5.0

package/package.json

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

package/src/activity.ts

@@ -0,0 +1,179 @@
+// NOMOS — DIRECTIVE ACTIVITY DESCRIPTORS (architecture/activity_descriptors.md). A directive OPT-IN declares
+// its own user-facing activity metadata, so a client can fold typed activity rows straight from the intent
+// log — no string-enricher guessing meaning beside the truth. The kernel/ledger stays the audit truth; this
+// is a pure CLIENT-SIDE human projection, declared where the event semantics live.
+//
+//   directive("createSite").creates(EstateSite).payload(SitePayload)
+//     .activity({
+//       kind: "site.created",                       // STABLE event id (seeds the i18n keys)
+//       title: "Created site",
+//       message: "{actor} created {siteName}",       // {actor} + declared params
+//       category: "estate", icon: "add_location", severity: "info",
+//       refs: { site: { type: EstateSite, from: "siteId" } },   // navigation target (type + payload path)
+//       params: { siteName: "name" },                // display value ← payload field path
+//     })
+//
+// NON-LAW, additive metadata (same class as `.doc()`): a directive that never calls `.activity()` is
+// byte-identical in the canonical manifest.
+import { z } from "zod";
+import type { AggregateHandle } from "./aggregate.js";
+import { isContractHandle, type ContractHandle } from "./contract.js";
+
+/** How prominent an activity row is — a declared default the app may style/threshold on. */
+export type ActivitySeverity = "info" | "success" | "warning" | "critical";
+
+/** A declared navigation target: the referenced aggregate/contract TYPE + the payload field path holding its
+ *  id. Replaces the enricher's blind id-probing — the reference is declared, not guessed. */
+export interface ActivityRefInput {
+  /** The target type — an aggregate handle or a `contract(...)` (reuse contracts for the nav target). */
+  readonly type: AggregateHandle | ContractHandle;
+  /** The payload field path holding the target's id (dotted for nested, e.g. `"location.siteId"`). */
+  readonly from: string;
+}
+
+/** The `.activity({...})` input (declarative — field PATHS, never functions, so it generates to Dart too). */
+export interface ActivityInput {
+  /** STABLE event id (e.g. `"site.created"`) — the wire kind + the seed for the i18n keys. */
+  readonly kind: string;
+  /** Default (English) title; falls back to `kind` if omitted. */
+  readonly title?: string;
+  /** Message template — `{actor}` + any declared `params` name in braces (e.g. `"{actor} created {siteName}"`). */
+  readonly message: string;
+  /** Optional grouping category (e.g. `"estate"`). */
+  readonly category?: string;
+  /** Optional default icon token (app-interpreted). */
+  readonly icon?: string;
+  /** Row prominence (default `"info"`). */
+  readonly severity?: ActivitySeverity;
+  /** Navigation targets: name → { target type, payload path to its id }. */
+  readonly refs?: Record<string, ActivityRefInput>;
+  /** Display values: template-param name → payload field path (dotted ok). */
+  readonly params?: Record<string, string>;
+}
+
+/** The NORMALIZED, serializable descriptor stored on the directive + emitted to codegen/IR. */
+export interface ActivityDescriptor {
+  readonly kind: string;
+  readonly title: string;
+  readonly message: string;
+  readonly category?: string;
+  readonly icon?: string;
+  readonly severity: ActivitySeverity;
+  /** Refs sorted by name; `type` is the target's wire id (a string). */
+  readonly refs: readonly { readonly name: string; readonly type: string; readonly from: string }[];
+  /** Params sorted by name. */
+  readonly params: readonly { readonly name: string; readonly from: string }[];
+  /** Stable i18n keys derived from `kind` (`activity.<kind>.title` / `.message`). */
+  readonly titleKey: string;
+  readonly messageKey: string;
+}
+
+const SEVERITIES: ReadonlySet<string> = new Set(["info", "success", "warning", "critical"]);
+
+/** The i18n key for a `kind` + slot — stable, derived (never hand-authored). */
+export function activityKey(kind: string, slot: "title" | "message"): string {
+  return `activity.${kind}.${slot}`;
+}
+
+/** Interpolate `{name}` placeholders in a template from `vars` (a missing var renders as the empty string —
+ *  the compile-time validator already guarantees every placeholder is declared, so this is defensive only).
+ *  The ONE render helper shared by the TS + Dart renderers (each reimplements the same trivial substitution). */
+export function renderActivityTemplate(template: string, vars: Record<string, string>): string {
+  return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (_m, name: string) => vars[name] ?? "");
+}
+
+/** The `{placeholder}` names referenced by a template. */
+function templateVars(template: string): string[] {
+  const out: string[] = [];
+  for (const m of template.matchAll(/\{([a-zA-Z0-9_]+)\}/g)) out.push(m[1]!);
+  return out;
+}
+
+/** Top-level payload field names (best-effort — a plain `z.object`); `undefined` when the schema isn't a
+ *  destructurable object (validation of `from` roots is then skipped, staying permissive). */
+function payloadFieldNames(schema: unknown): Set<string> | undefined {
+  const def = (schema as { _def?: { shape?: unknown }; def?: { shape?: unknown } })?._def
+    ?? (schema as { def?: { shape?: unknown } })?.def;
+  const shape = (def as { shape?: unknown })?.shape;
+  const resolved = typeof shape === "function" ? (shape as () => Record<string, unknown>)() : shape;
+  if (resolved === undefined || resolved === null || typeof resolved !== "object") return undefined;
+  return new Set(Object.keys(resolved as Record<string, unknown>));
+}
+
+/**
+ * Validate + normalize an `.activity({...})` input at author time (throws a typed error naming the problem).
+ * Checks: `kind`/`message` non-empty; `severity` valid; every message/title `{placeholder}` is `actor` or a
+ * declared param; every ref/param `from` ROOT names a real payload field (when the payload shape is
+ * introspectable). Returns the serializable {@link ActivityDescriptor}. Pure.
+ */
+export function normalizeActivity(directiveId: string, input: ActivityInput, payloadSchema?: unknown): ActivityDescriptor {
+  const where = `directive '${directiveId}' .activity(...)`;
+  if (typeof input.kind !== "string" || input.kind.trim().length === 0) {
+    throw new Error(`${where}: 'kind' must be a non-empty stable string (e.g. "site.created").`);
+  }
+  if (typeof input.message !== "string" || input.message.trim().length === 0) {
+    throw new Error(`${where}: 'message' must be a non-empty template string.`);
+  }
+  const severity = input.severity ?? "info";
+  if (!SEVERITIES.has(severity)) {
+    throw new Error(`${where}: 'severity' must be one of info|success|warning|critical (got '${severity}').`);
+  }
+  const params = Object.entries(input.params ?? {}).map(([name, from]) => {
+    if (typeof from !== "string" || from.length === 0) {
+      throw new Error(`${where}: param '${name}' must map to a payload field path string.`);
+    }
+    return { name, from };
+  });
+  const paramNames = new Set(params.map((p) => p.name));
+  // Every {placeholder} must be `actor` or a declared param — an undeclared var is a typo, refuse it.
+  for (const tmpl of [input.title ?? "", input.message]) {
+    for (const v of templateVars(tmpl)) {
+      if (v !== "actor" && !paramNames.has(v)) {
+        throw new Error(
+          `${where}: template references '{${v}}' but no such param is declared (known: actor${
+            paramNames.size > 0 ? ", " + [...paramNames].join(", ") : ""
+          }). Declare it in params or fix the template.`,
+        );
+      }
+    }
+  }
+  const refs = Object.entries(input.refs ?? {}).map(([name, r]) => {
+    const targetId = (r?.type as { id?: unknown })?.id;
+    const isTarget = typeof targetId === "string" && ((r.type as { __isAggregateHandle?: unknown }).__isAggregateHandle === true || isContractHandle(r.type));
+    if (!isTarget) {
+      throw new Error(`${where}: ref '${name}'.type must be an aggregate handle or a contract(...) (got ${typeof r?.type}).`);
+    }
+    if (typeof r.from !== "string" || r.from.length === 0) {
+      throw new Error(`${where}: ref '${name}'.from must be a payload field path string.`);
+    }
+    return { name, type: targetId as string, from: r.from };
+  });
+  // Best-effort payload-field existence check (root of a dotted path).
+  const fields = payloadFieldNames(payloadSchema);
+  if (fields !== undefined) {
+    for (const { name, from } of [...params, ...refs.map((r) => ({ name: `ref ${r.name}`, from: r.from }))]) {
+      const root = from.split(".")[0]!;
+      if (!fields.has(root)) {
+        throw new Error(
+          `${where}: ${name} reads payload field '${root}' which the payload does not declare ` +
+            `(known: ${[...fields].sort().join(", ")}). Fix the path or add the field.`,
+        );
+      }
+    }
+  }
+  return {
+    kind: input.kind,
+    title: input.title ?? input.kind,
+    message: input.message,
+    ...(input.category !== undefined ? { category: input.category } : {}),
+    ...(input.icon !== undefined ? { icon: input.icon } : {}),
+    severity,
+    refs: refs.sort((a, b) => a.name.localeCompare(b.name)),
+    params: params.sort((a, b) => a.name.localeCompare(b.name)),
+    titleKey: activityKey(input.kind, "title"),
+    messageKey: activityKey(input.kind, "message"),
+  };
+}
+
+/** Re-exported so directive.ts can accept the zod payload type in the `.activity` overload without a cycle. */
+export type { z };

package/src/codegen_dart.ts

@@ -2002,6 +2002,133 @@ export function generateDartContracts(contracts: readonly import("./contract.js"
   ].join("\n");
 }
 
+// ── ACTIVITY DESCRIPTORS (architecture/activity_descriptors.md) — shared registry codegen ──
+
+/** One directive's declared activity, tagged with its provenance (domain + directive id). */
+export interface PackageActivityEntry {
+  readonly domain: string;
+  readonly directiveId: string;
+  readonly desc: import("./activity.js").ActivityDescriptor;
+}
+
+/** Collect every directive's `.activity(...)` descriptor across the package's modules, tagged with its
+ *  domain + directive id, sorted by directive id (byte-deterministic switch/registry order). Empty when
+ *  no directive opts in — an activity-free package then emits NO registry (byte-identical). Shared by the
+ *  flat + layered Dart emit AND the TS client (one source of truth). */
+export function collectActivityDescriptors(modules: readonly DomainModule[]): PackageActivityEntry[] {
+  const out: PackageActivityEntry[] = [];
+  for (const mod of modules) {
+    const domain = mod.domain ?? mod.name;
+    for (const d of mod.directives as AnyDirective[]) {
+      const desc = (d as { activityDescriptor?: import("./activity.js").ActivityDescriptor }).activityDescriptor;
+      if (desc !== undefined) out.push({ domain, directiveId: d.id, desc });
+    }
+  }
+  return out.sort((a, b) => (a.directiveId < b.directiveId ? -1 : a.directiveId > b.directiveId ? 1 : 0));
+}
+
+/** Dart string literal (single-quoted, backslash/quote/`$` escaped). */
+const dartLit = (s: string): string => `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\$/g, "\\$")}'`;
+
+/** Emit ONE `case '<directiveId>':` arm folding a raw row into a typed [ActivityEvent]. */
+function emitDartActivityArm(e: PackageActivityEntry): string[] {
+  const { directiveId, desc } = e;
+  const paramEntries = desc.params.map((p) => `        ${dartLit(p.name)}: _activityPayloadPath(payload, ${dartLit(p.from)}),`);
+  const refEntries = desc.refs.map(
+    (r) => `          ${dartLit(r.name)}: ActivityRef(type: ${dartLit(r.type)}, id: _activityPayloadPath(payload, ${dartLit(r.from)})),`,
+  );
+  return [
+    `    case ${dartLit(directiveId)}:`,
+    `      {`,
+    `        final params = <String, String>{`,
+    ...paramEntries,
+    `        };`,
+    `        final vars = <String, String>{'actor': actorSubject, ...params};`,
+    `        return ActivityEvent(`,
+    `          eventId: (rawRow['intentId'] ?? '') as String,`,
+    `          kind: ${dartLit(desc.kind)},`,
+    `          actorSubject: actorSubject,`,
+    `          occurredAt: (rawRow['occurredAt'] ?? '') as String,`,
+    `          title: renderActivityTemplate(${dartLit(desc.title)}, vars),`,
+    `          message: renderActivityTemplate(${dartLit(desc.message)}, vars),`,
+    `          titleKey: ${dartLit(desc.titleKey)},`,
+    `          messageKey: ${dartLit(desc.messageKey)},`,
+    `          params: params,`,
+    `          refs: <String, ActivityRef>{`,
+    ...refEntries,
+    `          },`,
+    ...(desc.category !== undefined ? [`          category: ${dartLit(desc.category)},`] : []),
+    ...(desc.icon !== undefined ? [`          icon: ${dartLit(desc.icon)},`] : []),
+    `          severity: ActivitySeverity.${desc.severity},`,
+    `          domain: (rawRow['domain'] ?? '') as String,`,
+    `          directiveId: ${dartLit(directiveId)},`,
+    `        );`,
+    `      }`,
+  ];
+}
+
+/**
+ * The full source of the shared `activity_registry.dart` file — the PURE per-directive activity registry
+ * + `renderActivity(rawRow) => ActivityEvent?`, emitted ONCE per package into the TYPES package (both the
+ * flat + layered emit). References only nomos_types (`ActivityEvent`/`ActivityRef`/`ActivitySeverity`/
+ * `renderActivityTemplate`), so the file is PURE (frontend-safe, no bridge). A raw row is
+ * `{ intentId, domain, directiveId, actorSubject, occurredAt, payload }` (the runtime's per-committed-intent
+ * shape); `renderActivity` returns null for a directive with no declared `.activity(...)`.
+ */
+export function generateDartActivityRegistry(entries: readonly PackageActivityEntry[]): string {
+  const sorted = [...entries].sort((a, b) => (a.directiveId < b.directiveId ? -1 : a.directiveId > b.directiveId ? 1 : 0));
+  return [
+    `// GENERATED by nomos-compile — the package's shared ACTIVITY REGISTRY (architecture/activity_descriptors.md). DO NOT EDIT.`,
+    `// A directive OPT-IN declares its user-facing activity metadata; \`renderActivity\` folds each committed-intent`,
+    `// raw row into a typed ActivityEvent. Pure (nomos_types only) — the kernel/ledger stays the audit truth.`,
+    `//`,
+    `// ignore_for_file: unused_import`,
+    `library;`,
+    ``,
+    `import 'package:nomos_client/nomos_client.dart';`,
+    ``,
+    `/// A NARRATIVE over the activity log (for an in-app LLM): the filtered [events] + a plain-English`,
+    `/// [transcript] (ONE LINE PER EVENT, oldest-first, \`"<occurredAt> — <title>: <message>"\`) grounded in`,
+    `/// the VERIFIED log, never raw payloads. Produced by the client's \`describe\` / \`describeHistory\`.`,
+    `class ActivityNarrative {`,
+    `  final List<ActivityEvent> events;`,
+    `  final String transcript;`,
+    `  const ActivityNarrative({required this.events, required this.transcript});`,
+    `}`,
+    ``,
+    `/// Wrap events into an [ActivityNarrative], building the LLM-ready transcript: one line per event,`,
+    `/// OLDEST-FIRST (the log yields newest-first).`,
+    `ActivityNarrative activityNarrative(List<ActivityEvent> events) => ActivityNarrative(`,
+    `      events: events,`,
+    `      transcript: events.reversed.map((e) => '\${e.occurredAt} — \${e.title}: \${e.message}').join('\\n'),`,
+    `    );`,
+    ``,
+    `/// Read a dotted path off a decoded intent payload, coerced to String ('' when absent/null).`,
+    `String _activityPayloadPath(Map<String, dynamic> payload, String path) {`,
+    `  dynamic cur = payload;`,
+    `  for (final seg in path.split('.')) {`,
+    `    if (cur is! Map) return '';`,
+    `    cur = cur[seg];`,
+    `  }`,
+    `  return cur == null ? '' : '\$cur';`,
+    `}`,
+    ``,
+    `/// Fold ONE committed-intent raw row into a typed [ActivityEvent], or null when the directive declares`,
+    `/// no \`.activity(...)\`. rawRow = { intentId, domain, directiveId, actorSubject, occurredAt, payload }.`,
+    `ActivityEvent? renderActivity(Map<String, dynamic> rawRow) {`,
+    `  final directiveId = (rawRow['directiveId'] ?? '') as String;`,
+    `  final actorSubject = (rawRow['actorSubject'] ?? '') as String;`,
+    `  final payload = ((rawRow['payload'] as Map?)?.cast<String, dynamic>()) ?? const <String, dynamic>{};`,
+    `  switch (directiveId) {`,
+    ...sorted.flatMap(emitDartActivityArm),
+    `    default:`,
+    `      return null;`,
+    `  }`,
+    `}`,
+    ``,
+  ].join("\n");
+}
+
 /** True when ANY aggregate field in the module is `t.evidence()` — gates emitting the
  * shared [emitEvidenceRefClass] once. */
 function moduleUsesEvidence(aggregates: readonly AggregateHandle[]): boolean {

package/src/codegen_dart_client.ts

@@ -121,6 +121,19 @@ export interface DartBridgeClientOptions {
    * client re-exports that barrel so one import of the client still gives the whole typed surface.
    */
   readonly typesImportUri?: string;
+  /**
+   * ACTIVITY FEED (architecture/activity_descriptors.md): true iff the PACKAGE declares ≥1 directive
+   * `.activity(...)`. When set the client emits `watchActivity()` / `activityLog()` (folding the bridge's
+   * raw committed-intent rows through the shared pure `renderActivity`). Off ⇒ byte-identical to before.
+   */
+  readonly emitActivity?: boolean;
+  /**
+   * FLAT (vendored) mode only: the relative import of the shared `activity_registry.dart` (where the pure
+   * `renderActivity` lives), needed because a flat client imports only its sibling `<name>.dart`. In layered
+   * mode the registry resolves through {@link typesImportUri} (the types barrel re-exports it), so this is
+   * omitted. Only meaningful when {@link emitActivity} is set.
+   */
+  readonly activityImportUri?: string;
 }
 
 /** Generate the `<name>.client.dart` async bridge client for one domain module. */
@@ -345,6 +358,55 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     );
   }
 
+  // ── activity feed → typed reactive + one-shot (declared `.activity(...)`) ──
+  if (opts.emitActivity === true) {
+    methods.push(
+      `  /// THE ACTIVITY FEED (architecture/activity_descriptors.md): fold the committed intent log into typed`,
+      `  /// [ActivityEvent]s (declared \`.activity(...)\`). Re-emits on every new committed intent; a directive`,
+      `  /// with no declared activity is dropped. Cancel the subscription to stop.`,
+      `  Stream<List<ActivityEvent>> watchActivity() =>`,
+      `      bridge.watchActivity().map((rows) => rows`,
+      `          .map((r) => renderActivity((r as Map).cast<String, dynamic>()))`,
+      `          .whereType<ActivityEvent>()`,
+      `          .toList());`,
+      ``,
+      `  /// One-shot: the current committed activity log, folded to typed [ActivityEvent]s (declared \`.activity(...)\`).`,
+      `  Future<List<ActivityEvent>> activityLog({String? base, int? limit}) async =>`,
+      `      (await bridge.activityLog(base: base, limit: limit))`,
+      `          .map((r) => renderActivity(r.cast<String, dynamic>()))`,
+      `          .whereType<ActivityEvent>()`,
+      `          .toList();`,
+      ``,
+      `  /// NARRATIVE (for an in-app LLM): the workspace story — the activity log folded to typed events + a`,
+      `  /// plain-English [ActivityNarrative.transcript] grounded in the VERIFIED log. Filter by [actor] /`,
+      `  /// [category] / [since] (ISO occurredAt lower bound); [limit] caps the rows pulled. Newest-first.`,
+      `  Future<ActivityNarrative> describe({String? since, String? actor, String? category, int? limit}) async {`,
+      `    final raw = await bridge.activityLog(limit: limit);`,
+      `    var events = raw`,
+      `        .map((r) => renderActivity(r.cast<String, dynamic>()))`,
+      `        .whereType<ActivityEvent>()`,
+      `        .toList();`,
+      `    if (actor != null) events = events.where((e) => e.actorSubject == actor).toList();`,
+      `    if (category != null) events = events.where((e) => e.category == category).toList();`,
+      `    if (since != null) events = events.where((e) => e.occurredAt.compareTo(since) >= 0).toList();`,
+      `    return activityNarrative(events);`,
+      `  }`,
+      ``,
+      `  /// NARRATIVE for ONE thing: the story of the aggregate [aggregateId] — events whose declared refs`,
+      `  /// point at it (only directives declaring a ref to the aggregate appear in its story) + a transcript.`,
+      `  Future<ActivityNarrative> describeHistory(String aggregateId, {int? limit}) async {`,
+      `    final raw = await bridge.activityLog(limit: limit);`,
+      `    final events = raw`,
+      `        .map((r) => renderActivity(r.cast<String, dynamic>()))`,
+      `        .whereType<ActivityEvent>()`,
+      `        .where((e) => e.refs.values.any((ref) => ref.id == aggregateId))`,
+      `        .toList();`,
+      `    return activityNarrative(events);`,
+      `  }`,
+      ``,
+    );
+  }
+
   return [
     `// AUTO-GENERATED by nomos-compile — typed ASYNC Dart client for domain "${domain}".`,
     `// Drives the REAL githolon over a NomosBridge (the WebView runner). Regenerated every compile; do`,
@@ -368,6 +430,9 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     // Layered-packages mode: the sibling types live in their OWN package — one barrel import
     // replaces both the relative types import and the relative framework import.
     ...(opts.typesImportUri !== undefined ? [`import '${opts.typesImportUri}';`] : [`import '${mod.name}.dart';`]),
+    // ACTIVITY FEED (flat mode): the shared pure `renderActivity` lives in the sibling `activity_registry.dart`
+    // (in layered mode it resolves through the types-package barrel above). Only when the package opts in.
+    ...(opts.emitActivity === true && opts.activityImportUri !== undefined ? [`import '${opts.activityImportUri}';`] : []),
     // Framework-shared aggregate types (RelationTupleReadModel, …) live in the ONE shared file — import
     // them (the by-id accessors reference them) and re-export them (once per package, Dart de-dups).
     ...(opts.typesImportUri === undefined && opts.frameworkImportUri !== undefined ? [`import '${opts.frameworkImportUri}';`] : []),

package/src/codegen_ts.ts

@@ -40,6 +40,7 @@ import type { AggregateHandle } from "./aggregate.js";
 import type { Field, ValueObjectDescriptor, ValueObjectFieldDescriptor } from "./fields.js";
 import type { Directive } from "./directive.js";
 import type { DomainModule } from "./codegen_dart.js";
+import { collectActivityDescriptors, type PackageActivityEntry } from "./codegen_dart.js";
 import type { NomosCompat } from "./compat_manifest.js";
 import type { QueryDecl } from "./query.js";
 import { voMetaOf, collectPayloadValueObjectDescriptors } from "./value_object.js";
@@ -665,6 +666,86 @@ export interface TsClientOptions {
   readonly compat?: NomosCompat;
 }
 
+/** TS string literal (JSON.stringify covers escaping). */
+const _actLit = (s: string): string => JSON.stringify(s);
+
+/** Emit the ACTIVITY-FEED block (architecture/activity_descriptors.md): the `ActivityEvent`/`ActivityRef`/
+ *  `ActivityRawRow` runtime types, a dotted payload-path getter, the per-directive `renderActivity` registry,
+ *  and the shared template renderer — inline in the generated `.client.ts` (mirrors the ForeignRef placement).
+ *  Empty when no directive declares `.activity(...)` — an activity-free package stays BYTE-IDENTICAL. */
+function emitTsActivityBlock(entries: readonly PackageActivityEntry[]): string[] {
+  if (entries.length === 0) return [];
+  const arm = (e: PackageActivityEntry): string[] => {
+    const { directiveId, desc } = e;
+    const params = desc.params.map((p) => `${_actLit(p.name)}: _activityPayloadPath(row.payload, ${_actLit(p.from)})`).join(", ");
+    const refs = desc.refs
+      .map((r) => `${_actLit(r.name)}: { type: ${_actLit(r.type)}, id: _activityPayloadPath(row.payload, ${_actLit(r.from)}) }`)
+      .join(", ");
+    return [
+      `  ${_actLit(directiveId)}: (row: ActivityRawRow): ActivityEvent => {`,
+      `    const params: Record<string, string> = { ${params} };`,
+      `    const vars = { actor: row.actorSubject, ...params };`,
+      `    return {`,
+      `      eventId: row.intentId, kind: ${_actLit(desc.kind)}, actorSubject: row.actorSubject, occurredAt: row.occurredAt,`,
+      `      title: _renderActivityTemplate(${_actLit(desc.title)}, vars), message: _renderActivityTemplate(${_actLit(desc.message)}, vars),`,
+      `      titleKey: ${_actLit(desc.titleKey)}, messageKey: ${_actLit(desc.messageKey)},`,
+      `      params, refs: { ${refs} },`,
+      ...(desc.category !== undefined ? [`      category: ${_actLit(desc.category)},`] : []),
+      ...(desc.icon !== undefined ? [`      icon: ${_actLit(desc.icon)},`] : []),
+      `      severity: ${_actLit(desc.severity)}, domain: row.domain, directiveId: ${_actLit(directiveId)},`,
+      `    };`,
+      `  },`,
+    ];
+  };
+  return [
+    `// ── activity feed (architecture/activity_descriptors.md) — typed rows folded from the intent log ──`,
+    `/** A declared navigation target on an activity row (the referenced type + the resolved id). */`,
+    `export interface ActivityRef { type: string; id: string }`,
+    `/** A rendered activity row — produced by \`renderActivity\` from a directive's declared \`.activity(...)\`. */`,
+    `export interface ActivityEvent {`,
+    `  eventId: string; kind: string; actorSubject: string; occurredAt: string;`,
+    `  title: string; message: string; titleKey: string; messageKey: string;`,
+    `  params: Record<string, string>; refs: Record<string, ActivityRef>;`,
+    `  category?: string; icon?: string;`,
+    `  severity: "info" | "success" | "warning" | "critical";`,
+    `  domain: string; directiveId: string;`,
+    `}`,
+    `/** The runtime's per-committed-intent RAW ROW (the shape \`holon.watchActivity\`/\`activityLog\` yield). */`,
+    `export interface ActivityRawRow { intentId: string; domain: string; directiveId: string; actorSubject: string; occurredAt: string; payload: Record<string, unknown> }`,
+    `/** A NARRATIVE over the activity log (for an in-app LLM): the filtered events + a plain-English \`transcript\``,
+    ` *  (ONE LINE PER EVENT, oldest-first, \`"<occurredAt> — <title>: <message>"\`) — grounding text over the`,
+    ` *  VERIFIED log, never raw payloads. Produced by the client's \`describe\` / \`describeHistory\`. */`,
+    `export interface ActivityNarrative { events: ActivityEvent[]; transcript: string }`,
+    `/** Build the LLM-ready transcript: one line per event, OLDEST-FIRST (the log yields newest-first). */`,
+    `function _activityTranscript(events: readonly ActivityEvent[]): string {`,
+    "  return [...events].reverse().map((e) => `${e.occurredAt} — ${e.title}: ${e.message}`).join(\"\\n\");",
+    `}`,
+    `/** Read a dotted path off a decoded intent payload, coerced to string ("" when absent/null). */`,
+    `function _activityPayloadPath(obj: unknown, path: string): string {`,
+    `  let cur: unknown = obj;`,
+    `  for (const seg of path.split(".")) {`,
+    `    if (cur === null || typeof cur !== "object") return "";`,
+    `    cur = (cur as Record<string, unknown>)[seg];`,
+    `  }`,
+    `  return cur === null || cur === undefined ? "" : String(cur);`,
+    `}`,
+    `/** Interpolate \`{name}\` placeholders in a template from vars (a missing var renders empty). */`,
+    `function _renderActivityTemplate(template: string, vars: Record<string, string>): string {`,
+    `  return template.replace(/\\{([a-zA-Z0-9_]+)\\}/g, (_m, name: string) => vars[name] ?? "");`,
+    `}`,
+    `const _ACTIVITY_REGISTRY: Record<string, (row: ActivityRawRow) => ActivityEvent> = {`,
+    ...entries.flatMap(arm),
+    `};`,
+    `/** Fold ONE committed-intent raw row into a typed [ActivityEvent], or null when the directive declares`,
+    ` *  no \`.activity(...)\`. Pure — the kernel/ledger stays the audit truth; this is a client-side projection. */`,
+    `export function renderActivity(row: ActivityRawRow): ActivityEvent | null {`,
+    `  const f = _ACTIVITY_REGISTRY[row.directiveId];`,
+    `  return f === undefined ? null : f(row);`,
+    `}`,
+    ``,
+  ];
+}
+
 /** TRUE when any module declares a PACKED workspace taxonomy (the routed-holon shape).
  *  Gates every slice-4 paged-surface emission: taxonomy-free clients stay BYTE-IDENTICAL. */
 function anyPackedTaxonomy(modules: readonly DomainModule[]): boolean {
@@ -690,6 +771,10 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   );
   const encPresent = encMap !== null;
   const encConst = encryptionConstName(opts.packageName);
+  // ACTIVITY FEED (architecture/activity_descriptors.md): the package's declared `.activity(...)` descriptors.
+  // Empty ⇒ NOTHING activity-related emits (byte-identical to a pre-activity compile).
+  const activityEntries = collectActivityDescriptors(modules);
+  const activityPresent = activityEntries.length > 0;
   const out: string[] = [];
   // The PACKAGE-LEVEL recursive-type registry: every directive payload's `z.lazy` knots mint
   // named recursive type aliases into it (deduped by lazy identity across directives); the decls
@@ -853,6 +938,16 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  deadLetters(): Promise<{ id?: string; oid: string; source: string; error: string; domain?: string | null; directiveId?: string | null; at: string }[]>;`,
     `  retryDeadLetter(id: string): Promise<{ ok: boolean; head?: string; alreadyOnMain?: boolean; error?: string }>;`,
     `  discardDeadLetter(id: string): Promise<{ ok: boolean; removed: number }>;`,
+    ...(activityPresent
+      ? [
+          `  /** THE ACTIVITY FEED (declared \`.activity(...)\`): subscribe to per-committed-intent RAW ROWS`,
+          `   *  (the runtime folds the intent log). \`cb\` fires with the current rows + on every new intent;`,
+          `   *  returns an unsubscribe fn. The generated client maps these through \`renderActivity\`. */`,
+          `  watchActivity(cb: (rows: ActivityRawRow[]) => void, opts?: { base?: string }): () => void;`,
+          `  /** One-shot: the current committed activity log as RAW ROWS (folded to typed rows by the client). */`,
+          `  activityLog(opts?: { base?: string; limit?: number }): Promise<ActivityRawRow[]>;`,
+        ]
+      : []),
     `  /** THE COMPAT SUPERPOWER (#72b) — OPTIONAL: a holon from @githolon/client's connect() attaches it.`,
     `   *  The factory hands over this client's baked compat manifest + structural interface (the requirement),`,
     `   *  and the holon computes the LIVE per-member verdict on \`holon.compat\`. A KNOWN-incompatible directive`,
@@ -1489,6 +1584,9 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     }
   }
 
+  // ── activity feed (declared `.activity(...)`) — types + `renderActivity` registry (empty ⇒ nothing) ──
+  out.push(...emitTsActivityBlock(activityEntries));
+
   // ── payload types + per-domain client factories ──
   const usedPayloadNames = new Set<string>();
   for (const mod of modules) {
@@ -1714,6 +1812,38 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       );
     }
 
+    if (activityPresent) {
+      methods.push(
+        `    /** THE ACTIVITY FEED (declared \`.activity(...)\`): typed activity rows folded from the intent log.`,
+        `     *  \`cb\` fires with the current rows + on every new committed intent; returns stop(). Directives with`,
+        `     *  no declared activity are dropped. */`,
+        `    watchActivity: (cb: (events: ActivityEvent[]) => void, opts?: { base?: string }) =>`,
+        `      holon.watchActivity((rows) => cb(rows.map(renderActivity).filter((e): e is ActivityEvent => e !== null)), opts),`,
+        `    /** One-shot: the current committed activity log, folded to typed [ActivityEvent]s. */`,
+        `    activityLog: async (opts?: { base?: string; limit?: number }): Promise<ActivityEvent[]> =>`,
+        `      (await holon.activityLog(opts)).map(renderActivity).filter((e): e is ActivityEvent => e !== null),`,
+        `    /** NARRATIVE (for an in-app LLM): the workspace story — the activity log folded to typed events +`,
+        `     *  a plain-English \`transcript\` grounded in the VERIFIED log. Filter by \`actor\` / \`category\` /`,
+        `     *  \`since\` (ISO occurredAt lower bound); \`limit\` caps the rows pulled. Events are newest-first. */`,
+        `    describe: async (opts: { since?: string; actor?: string; category?: string; limit?: number } = {}): Promise<ActivityNarrative> => {`,
+        `      const raw = await holon.activityLog(opts.limit !== undefined ? { limit: opts.limit } : {});`,
+        `      let events = raw.map(renderActivity).filter((e): e is ActivityEvent => e !== null);`,
+        `      if (opts.actor !== undefined) events = events.filter((e) => e.actorSubject === opts.actor);`,
+        `      if (opts.category !== undefined) events = events.filter((e) => e.category === opts.category);`,
+        `      if (opts.since !== undefined) events = events.filter((e) => e.occurredAt >= opts.since!);`,
+        `      return { events, transcript: _activityTranscript(events) };`,
+        `    },`,
+        `    /** NARRATIVE for ONE thing: the story of the aggregate \`aggregateId\` — events whose declared refs`,
+        `     *  point at it (only directives declaring a ref to the aggregate appear in its story) + a transcript. */`,
+        `    describeHistory: async (aggregateId: string, opts: { limit?: number } = {}): Promise<ActivityNarrative> => {`,
+        `      const raw = await holon.activityLog(opts.limit !== undefined ? { limit: opts.limit } : {});`,
+        `      const events = raw.map(renderActivity).filter((e): e is ActivityEvent => e !== null)`,
+        `        .filter((e) => Object.values(e.refs).some((r) => r.id === aggregateId));`,
+        `      return { events, transcript: _activityTranscript(events) };`,
+        `    },`,
+      );
+    }
+
     out.push(
       `/** Typed client for the \`${domain}\` domain, bound to a connected holon.`,
       ` *  Pass \`{ actor }\` (the verified principal uid) to author AS that user — every write seals it as`,

package/src/compile_package_main.ts

@@ -56,6 +56,8 @@ import type { AggregateHandle } from "./aggregate.js";
 import {
   generateDartDomain,
   generateDartContracts,
+  generateDartActivityRegistry,
+  collectActivityDescriptors,
   type DartImport,
   type DartRefImport,
   type DomainModule,
@@ -428,6 +430,7 @@ const DART_SUPPORT_CORE_SRC = [
   // The foreign-ref locator runtime (ForeignRef<T>/NomosForeignReader/…, t.foreignRef) — a generated read
   // model with a `t.foreignRef` field references `ForeignRef<Target>` through the barrel, so it must vendor.
   "foreign_ref.dart",
+  "activity.dart",
 ] as const;
 // The RUNTIME support files, vendored from `nomos_client` (dsl/dart/lib/src): the async WebView
 // bridge the generated `<name>.client.dart` drives, and the provider surface. Their
@@ -450,6 +453,10 @@ const FRAMEWORK_FILE = "nomos_framework";
 /** The shared basename of the domain-contracts DTO file emitted once per package (domain_contracts.md). */
 const CONTRACTS_FILE = "contracts";
 
+/** The shared basename of the ACTIVITY REGISTRY file emitted once per package (activity_descriptors.md).
+ *  Absent when no directive declares `.activity(...)` — an activity-free package emits no `activity_registry.dart`. */
+const ACTIVITY_FILE = "activity_registry";
+
 /** Collect every domain contract across the package's modules, deduped by id (later-wins). Sorted by id.
  *  Empty when no domain declares a contract (contract-free packages emit no `contracts.dart`). */
 function collectPackageContracts(modules: readonly DomainModule[]): ContractHandle[] {
@@ -731,6 +738,14 @@ function emitDart(
   if (packageContracts.length > 0) {
     writeGenerated(CONTRACTS_FILE, generateDartContracts(packageContracts));
   }
+  // 2a-ter. the shared ACTIVITY REGISTRY (`activity_registry.dart`) — the pure `renderActivity`, ONCE. Emitted
+  //         iff a directive opts in via `.activity(...)` (activity-free packages stay byte-identical). Pure
+  //         (nomos_types), so the client folds typed activity rows from the intent log with no runtime import.
+  const packageActivity = collectActivityDescriptors(modules);
+  const activityImportUri = packageActivity.length > 0 ? `${ACTIVITY_FILE}.dart` : undefined;
+  if (packageActivity.length > 0) {
+    writeGenerated(ACTIVITY_FILE, generateDartActivityRegistry(packageActivity));
+  }
   // CROSS-DOMAIN `t.foreignRef` (auto import). A foreignRef field typed `ForeignRef<CatalogueListing>` +
   // `CatalogueListing.fromJson` needs the TARGET aggregate's Dart class — which lives in the target DOMAIN's
   // generated file. Within ONE package the compiler knows which domain owns each aggregate, so we auto-emit
@@ -794,6 +809,7 @@ function emitDart(
       ...(compat !== undefined ? { compat } : {}),
       supportImport,
       ...(domainFrameworkImport !== undefined ? { frameworkImportUri: domainFrameworkImport } : {}),
+      ...(packageActivity.length > 0 ? { emitActivity: true, ...(activityImportUri !== undefined ? { activityImportUri } : {}) } : {}),
     });
     const cp = path.join(genDir, `${mod.name}.client.dart`);
     writeFileSync(cp, clientSrc, "utf8");
@@ -820,6 +836,7 @@ function emitDart(
       : `export 'package:nomos_client/nomos_client.dart';`,
     ...(hasFrameworkSymbols ? [`export '${genRel}/${FRAMEWORK_FILE}.dart';`] : []),
     ...(contractsImportUri !== undefined ? [`export '${genRel}/${CONTRACTS_FILE}.dart';`] : []),
+    ...(activityImportUri !== undefined ? [`export '${genRel}/${ACTIVITY_FILE}.dart';`] : []),
     ...modules.flatMap((m) => [
       `export '${genRel}/${m.name}.dart';`,
       `export '${genRel}/${m.name}.client.dart';`,
@@ -844,8 +861,10 @@ function emitDart(
 /** The pure-core support import generated TYPES files carry in layered-packages mode. */
 const DART_TYPES_IMPORT = `import 'package:nomos_types/nomos_types.dart';`;
 /** Version constraints the scaffolded pubspecs pin — move together with the Dart packages' releases. */
-const NOMOS_TYPES_DEP = "^0.1.0";
-const NOMOS_CLIENT_DEP = "^0.38.0";
+// FLOOR = the release carrying every symbol generated code may reference (0.1.2: ActivityEvent).
+const NOMOS_TYPES_DEP = "^0.1.2";
+// FLOOR = the release carrying the bridge methods generated clients call (0.44.0: activityLog/watchActivity).
+const NOMOS_CLIENT_DEP = "^0.44.0";
 
 const isPubPackageName = (s: string): boolean => /^[a-z][a-z0-9_]*$/.test(s);
 
@@ -960,7 +979,7 @@ function emitDartPackages(
   // field as the target aggregate's class, which lives in the target domain's file). A sibling types file is
   // still PURE (no runtime/bridge surface — the purity gate exists to keep nomos_client out, not to isolate
   // domain files from each other; Dart allows type-import cycles for mutual refs).
-  const siblingTypeFiles = new Set<string>([...modules.map((m) => `${m.name}.dart`), `${FRAMEWORK_FILE}.dart`, `${CONTRACTS_FILE}.dart`]);
+  const siblingTypeFiles = new Set<string>([...modules.map((m) => `${m.name}.dart`), `${FRAMEWORK_FILE}.dart`, `${CONTRACTS_FILE}.dart`, `${ACTIVITY_FILE}.dart`]);
   const writeTypes = (fileBase: string, src: string): void => {
     if (!src.includes(DART_PACKAGE_IMPORT)) {
       fail(`generated Dart for '${fileBase}' does not carry the expected support import — codegen_dart header drifted`);
@@ -994,6 +1013,10 @@ function emitDartPackages(
   const packageContracts = collectPackageContracts(modules);
   const contractsImportUri = packageContracts.length > 0 ? `${CONTRACTS_FILE}.dart` : undefined;
   if (packageContracts.length > 0) writeTypes(CONTRACTS_FILE, generateDartContracts(packageContracts));
+  // ACTIVITY REGISTRY (layered): the pure `renderActivity` in the TYPES package (nomos_types only). The
+  // client resolves it through the types-package barrel (which re-exports every types file). Opt-in only.
+  const packageActivity = collectActivityDescriptors(modules);
+  if (packageActivity.length > 0) writeTypes(ACTIVITY_FILE, generateDartActivityRegistry(packageActivity));
   // CROSS-DOMAIN foreignRef (layered): map aggregate id → its domain's type file, so a foreignRef field's
   // target class resolves via a sibling import (the purity gate now permits sibling type files).
   const aggIdToTypeFile = new Map<string, string>();
@@ -1085,6 +1108,7 @@ function emitDartPackages(
       ...(compat !== undefined ? { compat } : {}),
       supportImport: "package",
       typesImportUri,
+      ...(packageActivity.length > 0 ? { emitActivity: true } : {}),
     });
     const cp = path.join(clientGen, `${mod.name}.client.dart`);
     writeFileSync(cp, clientSrc, "utf8");

package/src/directive.ts

@@ -23,6 +23,7 @@ import type { Ports } from "./ctx.js";
 import type { CertifiedReadDecl } from "./certified_read.js";
 import type { RelationDecl } from "./relation.js";
 import type { QueryDecl } from "./query.js";
+import { normalizeActivity, type ActivityInput, type ActivityDescriptor } from "./activity.js";
 import { BIRTH_METER_QUERIES } from "./birth_meter.js";
 import {
   isFromPayloadRef,
@@ -115,6 +116,15 @@ export interface Directive<P = unknown> {
    * byte-identical in the canonical manifest to before `description` existed).
    */
   readonly description?: string;
+  /**
+   * OPT-IN user-facing ACTIVITY metadata (`architecture/activity_descriptors.md`) — the kind/title/message
+   * template, refs, params, category/icon/severity a client uses to render a typed activity row from this
+   * directive's intents (no string-enricher). Set by `.activity({...})`; NON-LAW, additive (same class as
+   * `description` — a directive that never declares activity is byte-identical). Normalized + validated at
+   * author time. `undefined` ⇒ this directive contributes no activity row. (The setter is `.activity({...})`;
+   * this stored field is `activityDescriptor` to avoid a method/field name clash on `RequirableDirective`.)
+   */
+  readonly activityDescriptor?: ActivityDescriptor;
   /**
    * NATIVE ZANZIBAR write-authz (P4): the RELATION the captured author must HOLD to author this
    * directive, and the OBJECT it is checked on. The ONE gate runs `engine.check(schema, object,
@@ -414,6 +424,14 @@ export interface RequirableDirective<P> extends Directive<P> {
    * calls this declares no prose (codegen falls back to a default derived from the id).
    */
   doc(description: string): RequirableDirective<P>;
+  /**
+   * Declare OPT-IN user-facing ACTIVITY metadata (`architecture/activity_descriptors.md`) — a stable `kind`,
+   * a `{actor}`+params message template, navigation `refs`, display `params` (payload field paths), and
+   * category/icon/severity. Codegen emits a typed activity descriptor + `renderActivity` so a client folds
+   * typed activity rows from the intent log (no string-enricher). Validated at author time (unknown template
+   * var / missing payload field refuse). Non-law, additive; a directive that never calls it is byte-identical.
+   */
+  activity(input: ActivityInput): RequirableDirective<P>;
   /**
    * Declare the directive's CertifiedReads (survival Constraint 5; `certified_read.md`
    * §"Tenant authoring") — the profiled, named write-path reads its `decide()` consults, the
@@ -810,6 +828,11 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
     doc(description: string): RequirableDirective<P> {
       return makeRequirable({ ...base, description });
     },
+    activity(input: ActivityInput): RequirableDirective<P> {
+      // Normalize + validate against this directive's payload (unknown template var / missing payload field
+      // refuse here). Non-law, additive — stored like `description`.
+      return makeRequirable({ ...base, activityDescriptor: normalizeActivity(base.id, input, base.payloadSchema) });
+    },
     readsCertified(reads: Record<string, CertifiedReadDecl>): RequirableDirective<P> {
       // Accumulate onto any prior declared CertifiedReads (a repeated local name's later decl
       // wins) — additive, non-destructive. The local binding NAME (the key) is what `decide`

package/src/index.ts

@@ -136,6 +136,7 @@ export {
 // surface). The dev never sees a "prim" — that is the GitHolon's internal OpenUSD IR.
 export { create, existing, ensure, type AggregateRef } from "./authoring.js";
 export { contract, isContractHandle, satisfiesContract, type ContractHandle, type ContractField, type ContractSatisfaction } from "./contract.js";
+export { normalizeActivity, renderActivityTemplate, activityKey, type ActivityInput, type ActivityDescriptor, type ActivityRefInput, type ActivitySeverity } from "./activity.js";
 // THE CAPTURED READ — a plan reads O(1) DSL queries via `read(query, args)`; the result is committed as
 // the intent's read footprint (deterministic replay + stale-premise detection). The dev calls typed DSL
 // queries; the library routes them here. The host capability is `nomos.read` (twin of `nomos.rng`).