@githolon/dsl 0.66.0 → 0.68.0

package/src/codegen_dart_client.ts

@@ -87,10 +87,11 @@ function dartKeyParam(key: string): string {
   return safeMethod(safe);
 }
 
-/** Parse ONE bridge row (`{type,id,data}`) into a typed read model. Works for a `Map` (one-shot
+/** Parse ONE bridge row (`{type,id,data}`) into a typed read model, composing the canonical `.ref` from the
+ * session workspace (`_ws`, a getter on the client) + the row's type/id. Works for a `Map` (one-shot
  * `query`/`queryById` rows) or a `dynamic` (`watch` stream rows) — indexing resolves on both. */
 function rowToModel(model: string, rowVar: string): string {
-  return `${model}.fromProjected((${rowVar}['data'] as Map).cast<String, dynamic>(), (${rowVar}['id'] ?? '').toString())`;
+  return `${model}.fromProjected((${rowVar}['data'] as Map).cast<String, dynamic>(), (${rowVar}['id'] ?? '').toString(), _ws, (${rowVar}['type'] ?? '').toString())`;
 }
 
 export interface DartBridgeClientOptions {
@@ -121,6 +122,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. */
@@ -186,16 +200,19 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     // E2E SEALING (the sealing client): a directive with `.encrypted()` payload fields SEALS them via the
     // bound [keyStore] before dispatch (a missing key throws [EncryptionKeyUnavailable] — never a plaintext
     // write). One async block covers creates + mutate + gated + stamps; `seal: false` is the escape hatch.
+    // THE ONE WRITE OUTCOME (architecture/nomos_ref.md): EVERY directive method returns Future<NomosOfferOutcome>
+    // via the ONE lane `bridge.offerOutcome` — `outcome.created` carries every minted aggregate (each with its
+    // typed `.ref`), `outcome.head` the new local head. The breaking cut: creates AND non-creates alike.
+    const createsDoc = (d as { marker?: string }).marker === "creates"
+      ? ` The LAW mints the ${(d as { aggregateId?: string }).aggregateId ?? "aggregate"} id inside the sealed intent — it rides back on \`outcome.created\` (no id in the payload, no query-after).`
+      : "";
+    const stampsDoc = stamps.length > 0 ? `\n  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at offer.` : "";
     if (encMap?.directives?.[d.id] !== undefined) {
-      const isCreates = (d as { marker?: string }).marker === "creates";
-      const retType = isCreates ? "NomosOfferOutcome" : "String";
-      const offerFn = isCreates ? "offerCreates" : "offerDirective";
       methods.push(
-        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
-        `  /// Encrypted field(s) are SEALED via the bound [keyStore] before dispatch (pass \`seal: false\` to skip).`,
-        ...(stamps.length > 0 ? [`  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at offer.`] : []),
+        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}`,
+        `  /// Encrypted field(s) are SEALED via the bound [keyStore] before dispatch (pass \`seal: false\` to skip).${stampsDoc}`,
         ...(gateDoc ? [gateDoc] : []),
-        `  Future<${retType}> ${method}(${payloadClass} payload, {bool seal = true}) async {`,
+        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload, {bool seal = true}) async {`,
         ...(gateGuard ? [gateGuard] : []),
         `    final data = payload.toPayloadJson();`,
         ...(stamps.length > 0
@@ -205,64 +222,42 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
             ]
           : []),
         `    await _sealPayload(data, ${dartStr(d.id)}, seal);`,
-        `    return bridge.${offerFn}(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, actor: actor, domainHash: domainHash);`,
+        `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, actor: actor, domainHash: domainHash);`,
         `  }`,
         ``,
       );
       continue;
     }
-    if ((d as { marker?: string }).marker === "creates") {
-      // LAW-MINTED ID RETURN: a `.creates` plan mints its aggregate id inside the sealed intent (the payload
-      // carries none — callers never supply ids). The bridge's offerCreates hands the minted ids back with the
-      // head, so the create method returns the typed id with NO query-after round-trip.
+    if (stamps.length > 0) {
       methods.push(
-        `  /// Author \`${domain}/${d.id}\` — the LAW mints the ${(d as { aggregateId?: string }).aggregateId ?? "aggregate"} id inside the sealed`,
-        `  /// intent; it returns here (\`outcome.created\`) with the new local head. No id in the payload, no query-after.`,
-        ...(stamps.length > 0 ? [`  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at offer.`] : []),
+        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}${stampsDoc}`,
         ...(gateDoc ? [gateDoc] : []),
         `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload) {`,
         ...(gateGuard ? [gateGuard] : []),
         `    final data = payload.toPayloadJson();`,
-        ...(stamps.length > 0
-          ? [
-              `    final now = DateTime.now().toUtc().toIso8601String();`,
-              ...stamps.map((s) => `    data.putIfAbsent(${dartStr(s)}, () => now);`),
-            ]
-          : []),
-        `    return bridge.offerCreates(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, actor: actor, domainHash: domainHash);`,
-        `  }`,
-        ``,
-      );
-    } else if (stamps.length > 0) {
-      methods.push(
-        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
-        `  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at offer.`,
-        ...(gateDoc ? [gateDoc] : []),
-        `  Future<String> ${method}(${payloadClass} payload) {`,
-        ...(gateGuard ? [gateGuard] : []),
-        `    final data = payload.toPayloadJson();`,
         `    final now = DateTime.now().toUtc().toIso8601String();`,
         ...stamps.map((s) => `    data.putIfAbsent(${dartStr(s)}, () => now);`),
-        `    return bridge.offerDirective(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, actor: actor, domainHash: domainHash);`,
+        `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, actor: actor, domainHash: domainHash);`,
         `  }`,
         ``,
       );
     } else if (gateGuard) {
       // A gated directive with no `…At` sugar still needs a block body for the throw guard.
       methods.push(
-        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
+        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}`,
         gateDoc,
-        `  Future<String> ${method}(${payloadClass} payload) {`,
+        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload) {`,
         gateGuard,
-        `    return bridge.offerDirective(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.toPayloadJson(), actor: actor, domainHash: domainHash);`,
+        `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.toPayloadJson(), actor: actor, domainHash: domainHash);`,
         `  }`,
         ``,
       );
     } else {
       methods.push(
-        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
-        `  Future<String> ${method}(${payloadClass} payload) =>`,
-        `      bridge.offerDirective(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.toPayloadJson(), actor: actor, domainHash: domainHash);`,
+        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}`,
+        ...(gateDoc ? [gateDoc] : []),
+        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload) =>`,
+        `      bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.toPayloadJson(), actor: actor, domainHash: domainHash);`,
         ``,
       );
     }
@@ -345,6 +340,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 +412,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}';`] : []),
@@ -375,7 +422,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `// client file gives an app the whole typed surface.`,
     ...(opts.typesImportUri !== undefined ? [`export '${opts.typesImportUri}';`] : [`export '${mod.name}.dart';`]),
     ...(opts.typesImportUri === undefined && opts.frameworkImportUri !== undefined ? [`export '${opts.frameworkImportUri}';`] : []),
-    `export '${supportImport}' show NomosBridge, BridgeTransport, NomosBridgeError, MissingOfferAuthority, kWebviewBridgeVersion, NomosCompat, NomosCompatMember${encPresent ? ", NomosScopeKey, NomosKeyStore, EncryptionKeyUnavailable, WrappedKeyStore, NomosEncryption, NomosEpochResult, EncryptionMemberKeyMissing, EncryptionRosterMismatch" : ""};`,
+    `export '${supportImport}' show NomosBridge, NomosSession, BridgeTransport, NomosBridgeError, MissingOfferAuthority, kWebviewBridgeVersion, NomosCompat, NomosCompatMember, NomosOfferOutcome, NomosCreated, NomosRef${encPresent ? ", NomosScopeKey, NomosKeyStore, EncryptionKeyUnavailable, WrappedKeyStore, NomosEncryption, NomosEpochResult, EncryptionMemberKeyMissing, EncryptionRosterMismatch" : ""};`,
     ``,
     `/// sha256 of the deployed \`.package.usda\` — the installed law this client offers under.`,
     `const String ${hashConst} = ${dartStr(opts.domainHash)};`,
@@ -425,6 +472,13 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       : []),
     `  ${className}(this.bridge, {this.domainHash = ${hashConst}, this.actor${encPresent ? ", this.keyStore" : ""}});`,
     ``,
+    `  /// The session workspace this client is bound to (from the [NomosSession] handle, when constructed with`,
+    `  /// one) — the \`workspace\` of every read row's canonical [NomosRef]. '' on a bare (non-session) bridge.`,
+    `  String get _ws {`,
+    `    final b = bridge;`,
+    `    return b is NomosSession ? b.workspace : '';`,
+    `  }`,
+    ``,
     ...(encPresent ? dartEncClassMembers(encMap!) : []),
     // THE OWNER CEREMONY (slice 2): grantAndWrap / revokeAndRotate / rotate — the operator-blind key-epoch
     // handshake as one call. Bind `actor` (the owner) to author the fan-out. Only for a domain with a scope.

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,102 @@ 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) => {
+        // A `from: "@created"` ref reads the id the LAW MINTED (the row's `created` list, first type match);
+        // any other `from` is a payload path. Every ref carries the session workspace (the row's `workspace`).
+        const id = r.from === "@created"
+          ? `_activityCreatedId(row.created, ${_actLit(r.type)})`
+          : `_activityPayloadPath(row.payload, ${_actLit(r.from)})`;
+        return `${_actLit(r.name)}: { workspace: row.workspace ?? "", type: ${_actLit(r.type)}, id: ${id} }`;
+      })
+      .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 canonical [NomosRef] triple (workspace + type +`,
+    ` *  resolved id). A \`from: "@created"\` ref resolves the id the LAW minted; others a payload path. */`,
+    `export interface ActivityRef { workspace: string; 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>; created?: { type: string; id: string }[]; workspace?: string }`,
+    `/** 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);`,
+    `}`,
+    `/** The id the LAW minted for a \`from: "@created"\` ref — the first entry of the row's \`created\` list whose`,
+    ` *  type matches the declared aggregate (the runtime type is uuid-stripped + may be namespaced, so match on`,
+    ` *  equality OR \`<domain>.<Type>\` suffix). "" when the holon returned no created list (era-safe). */`,
+    `function _activityCreatedId(created: { type: string; id: string }[] | undefined, declared: string): string {`,
+    `  if (created === undefined) return "";`,
+    `  for (const c of created) if (c.type === declared || c.type.endsWith("." + declared)) return c.id;`,
+    `  return "";`,
+    `}`,
+    `/** 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 +787,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
@@ -728,8 +829,46 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           ``,
         ]
       : []),
-    `/** One projection row: the aggregate's wire type, its id, and the folded fields. */`,
-    `export interface Row<T> { type: string; id: string; data: T }`,
+    `/** THE ONE REFERENCE (architecture/nomos_ref.md) — the canonical, workspace-qualified identity of an`,
+    ` *  aggregate instance: \`{ workspace, type, id }\`, with the stable interop string`,
+    ` *  \`nomos://<workspace>/<type>/<id>\`. Carried on every read \`Row.ref\` + write outcome + activity ref. */`,
+    `export interface NomosRef { workspace: string; type: string; id: string }`,
+    `/** The stable \`nomos://<workspace>/<type>/<id>\` string form (each segment URI-encoded — a workspace/`,
+    ` *  type/id containing \`/\` or spaces round-trips). Survives URLs, nav params, JSON, logs. */`,
+    `export function nomosRefUri(ref: NomosRef): string {`,
+    `  return "nomos://" + encodeURIComponent(ref.workspace) + "/" + encodeURIComponent(ref.type) + "/" + encodeURIComponent(ref.id);`,
+    `}`,
+    `/** Parse a \`nomos://<workspace>/<type>/<id>\` string back into a [NomosRef] (the inverse of [nomosRefUri]);`,
+    ` *  throws on anything else. */`,
+    `export function parseNomosRef(uri: string): NomosRef {`,
+    "  const m = /^nomos:\\/\\/([^/]+)\\/([^/]+)\\/([^/]+)$/.exec(uri);",
+    `  if (m === null) throw new Error("parseNomosRef: expected nomos://<workspace>/<type>/<id>: " + uri);`,
+    `  return { workspace: decodeURIComponent(m[1]!), type: decodeURIComponent(m[2]!), id: decodeURIComponent(m[3]!) };`,
+    `}`,
+    `/** One projection row: the aggregate's wire type, its id, the folded fields, and the canonical [NomosRef]`,
+    ` *  (composed at decode from the session workspace + the row's type/id — additive, the \`data\` is untouched). */`,
+    `export interface Row<T> { type: string; id: string; data: T; ref: NomosRef }`,
+    `/** Stamp each row's canonical [NomosRef] from the session \`ws\` + the row's type/id (additive — already-`,
+    ` *  stamped rows pass through). */`,
+    `function _stampRefs<T>(ws: string, rows: Row<T>[]): Row<T>[] {`,
+    `  return rows.map((r) => (r.ref !== undefined ? r : { ...r, ref: { workspace: ws, type: r.type, id: r.id } }));`,
+    `}`,
+    `function _stampRefsP<T>(ws: string, p: Promise<Row<T>[]>): Promise<Row<T>[]> { return p.then((rows) => _stampRefs(ws, rows)); }`,
+    `/** THE TYPED WRITE OUTCOME (architecture/nomos_ref.md) — every generated directive method returns this.`,
+    ` *  \`created\` is EVERY aggregate the plan minted (typed [NomosRef]s, composed with the session workspace;`,
+    ` *  \`[]\` on a holon too old to return them — never a fake id). \`target\` is the addressed instance for a`,
+    ` *  front-door-mint lane (statically known); omitted otherwise. \`head\` is the new local head. */`,
+    `export interface NomosOutcome { head: string; created: NomosRef[]; target?: NomosRef }`,
+    `/** Fold a holon offer result (a bare head, or \`{ head, created }\` under returnCreated) into a [NomosOutcome]`,
+    ` *  — composing each created \`{type,id}\` with the session \`ws\`. \`target\` rides through when the caller`,
+    ` *  statically knows the addressed instance (the front-door mint). */`,
+    `async function _outcome(ws: string, r: Promise<string | { head: string; created?: { type: string; id: string }[] }>, target?: NomosRef): Promise<NomosOutcome> {`,
+    `  const v = await r;`,
+    `  const obj = typeof v === "object" && v !== null;`,
+    `  const head = obj ? v.head : String(v);`,
+    `  const created = (obj ? v.created ?? [] : []).map((c) => ({ workspace: ws, type: c.type, id: c.id }));`,
+    `  return target !== undefined ? { head, created, target } : { head, created };`,
+    `}`,
     // MULTI-WORKSPACE LOCATORS (t.foreignRef): a TYPED cross-workspace edge — the foreign aggregate's id +
     // the foreign workspace id (from a sibling field). NOT an atomic FK: it does not clone/open the other
     // holon; `resolve`/`watch` open it ON DEMAND over a realm (openRealm's `.workspace(ws)` surface).
@@ -814,6 +953,8 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  offerDirective(domain: string, directiveId: string, payload: unknown, opts?: { domainHash?: string; actor?: string; returnCreated?: boolean }): Promise<string>;`,
     `  /** Opaque-bytes offer — retained for carriers that already hold an encoded envelope (back-compat). */`,
     `  offer(intentBytes: string | Uint8Array): Promise<string>;`,
+    `  /** The workspace this holon is bound to — the \`workspace\` of every [NomosRef] this client composes. */`,
+    `  workspace: string;`,
     ...(encPresent
       ? [
           `  /** \`keys\` (E2E sealing): the reader's held scope keys, injected so encrypted fields decrypt;`,
@@ -853,6 +994,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`,
@@ -1246,8 +1397,12 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   const foreignRefFields: { agg: string; field: string; workspaceField: string; target: string }[] = [];
   // wrap a read accessor return expression through the foreignRef row-hydrator (identity + byte-identical
   // when the package declares no foreignRef, so non-foreignRef packages are unchanged).
-  const wrapP = (expr: string): string => (foreignRefFields.length > 0 ? `_hydrateP(${expr})` : expr);
-  const wrapRows = (expr: string): string => (foreignRefFields.length > 0 ? `_hydrateRows(${expr})` : expr);
+  // Every read accessor's rows get their canonical `.ref` stamped from `holon.workspace` (additive); a
+  // foreignRef-declaring package ALSO hydrates its foreignRef fields into typed locators first.
+  const wrapP = (expr: string): string =>
+    `_stampRefsP(holon.workspace, ${foreignRefFields.length > 0 ? `_hydrateP(${expr})` : expr})`;
+  const wrapRows = (expr: string): string =>
+    `_stampRefs(holon.workspace, ${foreignRefFields.length > 0 ? `_hydrateRows(${expr})` : expr})`;
   for (const [typeId, agg] of [...aggByType].sort(([a], [b]) => a.localeCompare(b))) {
     out.push(`export interface ${typeId}Data {`);
     for (const [name, field] of Object.entries(agg.fields)) {
@@ -1489,6 +1644,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) {
@@ -1565,6 +1723,9 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         `export type ${payloadName} = ${tsTypeOfPayload(schema, stamps, mint ? [mint.field] : [], placed, lazyReg, d.id)};`,
         ``,
       );
+      // THE ONE WRITE OUTCOME (architecture/nomos_ref.md): EVERY directive method returns Promise<NomosOutcome>
+      // — `created` (typed refs of all minted aggregates, from returnCreated) + `head`, plus `target` for the
+      // front-door-mint lane (the one statically-known addressed instance). One async block covers every case.
       if (mint !== undefined) {
         const mintOpts =
           mint.homeKeyField !== undefined
@@ -1577,65 +1738,31 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           : `{ ...${pv}, ${mint.field} }`;
         methods.push(
           `    /** Author \`${domain}/${d.id}\`: the front-door MINTS \`${mint.field}\` (route-tagged) when omitted`,
-          `     *  — ids stay internal plumbing — and returns it with the new local head.${gate ? ` GATED: needs \`{ actor }\` (\`${gate.relation}\`).` : ""} */`,
-          `    ${d.id}: async (${paramSig}): Promise<{ head: string; ${mint.field}: string }> => {`,
+          `     *  — ids stay internal plumbing — and returns the outcome (\`target\` = the minted ${dd.aggregateId ?? "aggregate"}).${gate ? ` GATED: needs \`{ actor }\` (\`${gate.relation}\`).` : ""} */`,
+          `    ${d.id}: async (${paramSig}): Promise<NomosOutcome> => {`,
           ...(gateGuard ? [gateGuard.replace(/\n$/, "")] : []),
           ...(sealPrelude ? [sealPrelude] : []),
           `      const ${mint.field} = payload.${mint.field} ?? (await (holon as NomosRoutedHolon).mint(${JSON.stringify(mint.mintType)}${mintOpts}));`,
-          `      const head = await holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, { domainHash, actor });`,
-          `      return { head, ${mint.field} };`,
+          `      return _outcome(holon.workspace, holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, { domainHash, actor, returnCreated: true }) as Promise<string | { head: string; created?: { type: string; id: string }[] }>, { workspace: holon.workspace, type: ${JSON.stringify(dd.aggregateId ?? mint.mintType)}, id: ${mint.field} });`,
           `    },`,
         );
         continue;
       }
       const offerPayload = stamps.length ? `stampNow(${pv}, ${JSON.stringify(stamps)})` : pv;
-      if (d.marker === "creates") {
-        // LAW-MINTED ID RETURN: a `.creates` plan mints its aggregate id inside the sealed intent (the payload
-        // carries none). The holon hands the minted ids back on the offer (`returnCreated`), so the create
-        // method returns the typed id with NO query-after. Older holons (pre-returnCreated) answer a bare head
-        // string — degrade to id:"" rather than refuse (structural binding, era-safe).
-        methods.push(
-          `    /** Author \`${domain}/${d.id}\`: the LAW mints the ${d.aggregateId ?? "aggregate"} id inside the sealed intent`,
-          `     *  and it returns here with the new local head — no id in the payload, no query-after.${gate ? ` GATED: needs \`{ actor }\` (\`${gate.relation}\`).` : ""} */`,
-          `    ${d.id}: async (${paramSig}): Promise<{ head: string; id: string }> => {`,
-          ...(gateGuard ? [gateGuard.replace(/\n$/, "")] : []),
-          ...(sealPrelude ? [sealPrelude] : []),
-          `      const r = await (holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${offerPayload}, { domainHash, actor, returnCreated: true }) as Promise<string | { head: string; created?: { type: string; id: string }[] }>);`,
-          `      return typeof r === "object" && r !== null ? { head: r.head, id: r.created?.[0]?.id ?? "" } : { head: String(r), id: "" };`,
-          `    },`,
-        );
-        continue;
-      }
-      const offerCall = `holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${offerPayload}, { domainHash, actor })`;
-      if (wantSeal) {
-        // SEALING directive (optionally also gated): an ASYNC block — seal the encrypted fields via the
-        // bound { keyStore } (+ throw MissingOfferAuthority first if gated) before dispatch.
-        methods.push(
-          `    /** Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
-          `     *  Encrypted field(s) are SEALED via the bound { keyStore } before dispatch (pass { seal: false } to skip).${gate ? ` GATED: needs \`{ actor }\` (\`${gate.relation}\`).` : ""} */`,
-          `    ${d.id}: async (${paramSig}): Promise<string> => {`,
-          ...(gateGuard ? [gateGuard.replace(/\n$/, "")] : []),
-          sealPrelude,
-          `      return ${offerCall};`,
-          `    },`,
-        );
-      } else if (gateGuard) {
-        // GATED directive: a block body that throws MissingOfferAuthority when no actor is bound — an
-        // actorless gated offer can't be constructed (the war: the gate is structural, not just kernel-side).
-        methods.push(
-          `    /** Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
-          `     *  GATED: needs \`{ actor }\` (the \`${gate!.relation}\` relation) — throws MissingOfferAuthority otherwise. */`,
-          `    ${d.id}: (payload: ${payloadName}): Promise<string> => {`,
-          gateGuard.replace(/\n$/, ""),
-          `      return ${offerCall};`,
-          `    },`,
-        );
-      } else {
-        methods.push(
-          `    /** Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head. */`,
-          `    ${d.id}: (payload: ${payloadName}) => ${offerCall},`,
-        );
-      }
+      const outcomeDoc =
+        d.marker === "creates"
+          ? `Author \`${domain}/${d.id}\`: the LAW mints the ${d.aggregateId ?? "aggregate"} id inside the sealed intent; it rides back on \`outcome.created\` — no id in the payload, no query-after.`
+          : `Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOutcome] (\`head\` + any \`created\` refs).`;
+      const sealDoc = wantSeal ? " Encrypted field(s) are SEALED via the bound { keyStore } before dispatch (pass { seal: false } to skip)." : "";
+      const gateDoc = gate ? ` GATED: needs \`{ actor }\` (\`${gate.relation}\`) — throws MissingOfferAuthority otherwise.` : "";
+      methods.push(
+        `    /** ${outcomeDoc}${sealDoc}${gateDoc} */`,
+        `    ${d.id}: async (${paramSig}): Promise<NomosOutcome> => {`,
+        ...(gateGuard ? [gateGuard.replace(/\n$/, "")] : []),
+        ...(sealPrelude ? [sealPrelude] : []),
+        `      return _outcome(holon.workspace, holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${offerPayload}, { domainHash, actor, returnCreated: true }) as Promise<string | { head: string; created?: { type: string; id: string }[] }>);`,
+        `    },`,
+      );
     }
 
     for (const sp of (mod.spatials ?? []) as { id: string; of: string; on: string }[]) {
@@ -1708,9 +1835,39 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           : `    list${agg.id}s: () => ${wrapP(`holon.query("aggregatesByType", { __type: ${JSON.stringify(agg.id)} }) as Promise<Row<${agg.id}Data>[]>`)},`,
         `    /** Watch one ${agg.id} by aggregate id (local reactive read; returns stop()). */`,
         `    watch${agg.id}ById: (id: string, cb: (rows: Row<${agg.id}Data>[]) => void, opts?: { intervalMs?: number }) =>`,
-        foreignRefFields.length > 0
-          ? `      holon.watchById(id, ((rows: Row<${agg.id}Data>[]) => cb(_hydrateRows(rows))) as (rows: unknown) => void, opts),`
-          : `      holon.watchById(id, cb as (rows: unknown) => void, opts),`,
+        `      holon.watchById(id, ((rows: Row<${agg.id}Data>[]) => cb(${wrapRows("rows")})) as (rows: unknown) => void, opts),`,
+      );
+    }
+
+    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) };`,
+        `    },`,
       );
     }