@githolon/dsl 0.65.1 → 0.67.0

package/src/codegen_dart.ts

@@ -744,7 +744,11 @@ function aggFieldSpec(
       // workspace field give the app `resolve`/`watch`/`attest` on demand, without cloning the other holon.
       // This takes precedence over the same-workspace typed-id path below.
       if (field.foreignRef !== undefined) {
-        const target = field.foreignRef.targetAggregateId;
+        // A contract target names the shared DTO class `<ContractId>Contract` (emitted into the shared
+        // `contracts.dart`); the aggregate class is `<ContractId>` and must not collide, hence the suffix.
+        const target = field.foreignRef.targetIsContract === true
+          ? `${field.foreignRef.targetAggregateId}Contract`
+          : field.foreignRef.targetAggregateId;
         return {
           name,
           wireName,
@@ -1904,6 +1908,227 @@ function emitValueObjectClass(d: ValueObjectDescriptor): string {
   ].join("\n");
 }
 
+/** The Dart type a CONTRACT field decodes to (domain_contracts.md) — a public DTO leaf. Contracts are
+ *  plain shapes (no merge state), so map by kind: scalars to their Dart primitive, a named VO to its class,
+ *  a ref/foreignRef to the raw id String. Everything is nullable (a projected DTO is a partial fold). */
+function dartTypeOfContractField(field: Field): string {
+  switch (field.kind) {
+    case "int":
+    case "counter":
+      return "int";
+    case "bool":
+      return "bool";
+    case "json":
+      return field.valueObject !== undefined ? field.valueObject.name : "Map<String, dynamic>";
+    default:
+      // string / enum / position / ref / foreignRef — all carried as a String on the wire.
+      return "String";
+  }
+}
+
+/** The fromJson decode expression for a CONTRACT field, reading `data['<wire>']`. */
+function contractFromExpr(field: Field, wire: string): string {
+  const acc = `data['${wire}']`;
+  switch (field.kind) {
+    case "int":
+    case "counter":
+      return `(${acc} as num?)?.toInt()`;
+    case "bool":
+      return `${acc} as bool?`;
+    case "json":
+      if (field.valueObject !== undefined) {
+        return `${acc} == null ? null : ${field.valueObject.name}.fromProjected((${acc} as Map).cast<String, Object?>())`;
+      }
+      return `${acc} == null ? null : (${acc} as Map).cast<String, dynamic>()`;
+    default:
+      return `${acc} as String?`;
+  }
+}
+
+/**
+ * Emit an immutable Dart class for ONE domain contract (a public DTO — architecture/domain_contracts.md).
+ * The class is `<ContractId>Contract` (the suffix keeps it distinct from an identically-named aggregate's
+ * `<ContractId>` read-model class). `final` fields + a `const` ctor + a `fromJson(Map, [id])` factory. Pure —
+ * references only nomos_types primitives (+ any VO class, which is shared). Emitted into `contracts.dart`.
+ */
+function emitDartContractClass(c: import("./contract.js").ContractHandle): string {
+  const cls = `${c.id}Contract`;
+  const fields = Object.entries(c.fields).map(([wireName, f]) => ({
+    wireName,
+    member: dartMemberName(wireName),
+    dartType: dartTypeOfContractField(f as Field),
+    from: contractFromExpr(f as Field, wireName),
+  }));
+  return [
+    `/// Generated domain CONTRACT '${c.id}' (architecture/domain_contracts.md) — a public DTO: a named,`,
+    `/// stable shape other domains reference WITHOUT importing the concrete aggregate. Immutable; decoded`,
+    `/// from a projection row via [${cls}.fromJson]. Fields are nullable (a projected DTO is a partial fold).`,
+    `class ${cls} {`,
+    `  final String id;`,
+    ...fields.map((x) => `  final ${x.dartType}? ${x.member};`),
+    ``,
+    `  const ${cls}({`,
+    `    this.id = '',`,
+    ...fields.map((x) => `    this.${x.member},`),
+    `  });`,
+    ``,
+    `  factory ${cls}.fromJson(Map<String, dynamic> data, [String id = '']) => ${cls}(`,
+    `        id: id,`,
+    ...fields.map((x) => `        ${x.member}: ${x.from},`),
+    `      );`,
+    `}`,
+  ].join("\n");
+}
+
+/**
+ * The full source of the shared `contracts.dart` file — every domain contract's DTO class, emitted ONCE
+ * per package into the TYPES package (both the flat and the layered emit). Carries the standard support
+ * import header so `compile_package_main`'s uniform rewrite (→ vendored relative / → nomos_types) applies;
+ * the classes themselves reference only nomos_types primitives (+ shared VO classes), so the file is PURE.
+ */
+export function generateDartContracts(contracts: readonly import("./contract.js").ContractHandle[]): string {
+  const sorted = [...contracts].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return [
+    `// GENERATED by nomos-compile — the package's shared domain CONTRACTS (public DTOs). DO NOT EDIT.`,
+    `// Every domain depends on this shared layer; no domain imports another's concrete types (the acyclic graph).`,
+    `//`,
+    `// ignore_for_file: unused_import`,
+    `library;`,
+    ``,
+    `import 'package:nomos_client/nomos_client.dart';`,
+    ``,
+    ...sorted.map(emitDartContractClass),
+    ``,
+  ].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 {
@@ -3578,6 +3803,15 @@ export interface DomainModule {
    * additive `nomosValueObjects` USD key (`usd.ts`).
    */
   valueObjects?: readonly ValueObjectDescriptor[];
+  /**
+   * DOMAIN CONTRACTS (`architecture/domain_contracts.md`) — the public DTO shapes this domain declares
+   * (`contract(id, fields)`), discovered by shape and composed across the domain's modules. ADDITIVE +
+   * OPTIONAL: a contract-free domain omits this entirely and is byte-identical to before contracts existed.
+   * Contracts are PURE typing/codegen metadata (NOT hashed law); they drive the additive `nomosContracts`
+   * IR key + the shared `contracts.dart` DTO classes + the TS `<Id>Contract` interfaces. `implementedBy`
+   * lists the concrete aggregate ids that `.implements(...)` this contract (from `implementsContracts`).
+   */
+  contracts?: readonly import("./contract.js").ContractHandle[];
   /**
    * The domain's FIRST-CLASS WORKSPACE TYPES (`workspace_type.ts`; sharding §10
    * RATIFIED, slice 1) — the law-declared workspace taxonomy

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";
@@ -499,8 +500,14 @@ function tsBaseTypeOfField(field: Field): string {
     case "ref": {
       // A `t.foreignRef` field surfaces as a TYPED cross-workspace locator (hydrated by the accessors from
       // the raw id + the declared workspace field); a plain same-workspace `t.ref` stays the id string.
-      const fr = (field as { foreignRef?: { targetAggregateId: string } }).foreignRef;
-      return fr !== undefined ? `ForeignRef<${fr.targetAggregateId}Data>` : "string";
+      const fr = (field as { foreignRef?: { targetAggregateId: string; targetIsContract?: boolean } }).foreignRef;
+      // A contract target types against the shared `<ContractId>Contract` interface (the public DTO),
+      // not the concrete `<Agg>Data` — that is how the reference stays acyclic.
+      return fr !== undefined
+        ? fr.targetIsContract === true
+          ? `ForeignRef<${fr.targetAggregateId}Contract>`
+          : `ForeignRef<${fr.targetAggregateId}Data>`
+        : "string";
     }
     case "json":
       // A NAMED VALUE OBJECT field reads as its generated interface (`value_object.ts`);
@@ -659,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 {
@@ -684,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
@@ -847,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`,
@@ -1218,6 +1319,24 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     }
   }
 
+  // ── domain contracts: one `<Id>Contract` interface per public DTO shape, deduped across domains ──
+  const contractByIdTs = new Map<string, import("./contract.js").ContractHandle>();
+  for (const mod of modules) {
+    for (const c of ((mod as { contracts?: readonly import("./contract.js").ContractHandle[] }).contracts ?? [])) {
+      contractByIdTs.set(c.id, c);
+    }
+  }
+  if (contractByIdTs.size > 0) {
+    out.push(`// ── domain contracts (public DTO shapes — architecture/domain_contracts.md) ──`, ``);
+    for (const [, c] of [...contractByIdTs].sort(([a], [b]) => a.localeCompare(b))) {
+      out.push(`export interface ${c.id}Contract {`);
+      for (const [name, field] of Object.entries(c.fields)) {
+        out.push(`  ${name}?: ${tsTypeOfField(field as Field)};`);
+      }
+      out.push(`}`, ``);
+    }
+  }
+
   out.push(`// ── read models (projection \`data\` shapes; partial-fold optional, EXCEPT .fromBirth()`, `//    fields — their presence is gate law, so the type is non-optional) ──`, ``);
   const foreignRefFields: { agg: string; field: string; workspaceField: string; target: string }[] = [];
   // wrap a read accessor return expression through the foreignRef row-hydrator (identity + byte-identical
@@ -1465,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) {
@@ -1690,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`,