@githolon/dsl 0.102.5 → 0.103.1

package/src/codegen_dart_application.ts

@@ -7,13 +7,14 @@ import type { z } from "zod";
 
 import type { AggregateHandle } from "./aggregate.js";
 import type { Directive } from "./directive.js";
-import type { Field } from "./fields.js";
+import { isSha256DigestSchema, type Field } from "./fields.js";
 import type { QueryDecl } from "./query.js";
 import type { DomainModule } from "./codegen_dart.js";
 import {
   cap,
   concreteClassName,
   dartBusinessRecordInputs,
+  dartForeignReferenceInputs,
   dartActionInputClassName,
   introspectPayload,
   readModelClassName,
@@ -22,7 +23,10 @@ import {
 import { dartClientClassName } from "./codegen_dart_client.js";
 import { finishCount } from "./count.js";
 import { finishSum } from "./sum.js";
-import { isNamespacedAggregate, qualifyReadProjectionType } from "./read_projection_namespace.js";
+import {
+  isNamespacedAggregate,
+  qualifyReadProjectionType,
+} from "./read_projection_namespace.js";
 import type { SurfacedResolverBinding } from "./surfaced_lint.js";
 import {
   isFrameworkAggregate,
@@ -39,14 +43,46 @@ import type {
 
 type AnyDirective = Directive<z.ZodTypeAny>;
 
-const camel = (s: string) => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
-const lcFirst = (s: string) => (s.length ? s[0]!.toLowerCase() + s.slice(1) : s);
+const camel = (s: string) =>
+  s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
+const lcFirst = (s: string) =>
+  s.length ? s[0]!.toLowerCase() + s.slice(1) : s;
 const reserved = new Set([
-  "assert", "break", "case", "catch", "class", "const", "continue", "default", "do", "else", "enum",
-  "extends", "false", "final", "for", "if", "in", "is", "new", "null", "rethrow", "return", "super",
-  "switch", "this", "throw", "true", "try", "var", "void", "while", "with", "dynamic",
+  "assert",
+  "break",
+  "case",
+  "catch",
+  "class",
+  "const",
+  "continue",
+  "default",
+  "do",
+  "else",
+  "enum",
+  "extends",
+  "false",
+  "final",
+  "for",
+  "if",
+  "in",
+  "is",
+  "new",
+  "null",
+  "rethrow",
+  "return",
+  "super",
+  "switch",
+  "this",
+  "throw",
+  "true",
+  "try",
+  "var",
+  "void",
+  "while",
+  "with",
+  "dynamic",
 ]);
-const safe = (s: string) => reserved.has(s) ? `${s}_` : s;
+const safe = (s: string) => (reserved.has(s) ? `${s}_` : s);
 const member = (s: string) => safe(lcFirst(camel(s)));
 const TENANT_ROOT_MEMBERS = new Map<string, string>([
   ["nomosWidget", "the generated Nomos Flutter bootstrap"],
@@ -66,7 +102,8 @@ function plural(name: string): string {
 
 function keyParam(key: string): string {
   const parts = key.split(".").filter(Boolean);
-  const raw = parts.length === 0 ? "key" : parts[0]! + parts.slice(1).map(cap).join("");
+  const raw =
+    parts.length === 0 ? "key" : parts[0]! + parts.slice(1).map(cap).join("");
   const cleaned = raw.replace(/[^A-Za-z0-9_]/g, "_");
   return safe(/^[0-9]/.test(cleaned) ? `v${cleaned}` : cleaned);
 }
@@ -77,12 +114,20 @@ function keyType(aggregate: AggregateHandle | undefined, key: string): string {
   if (field?.kind === "int" || field?.kind === "counter") return "int";
   if (field?.kind === "ref") {
     if (field.foreignRef !== undefined) {
-      const target = field.foreignRef.targetIsContract === true
-        ? contractTypeName(field.foreignRef.targetAggregateId)
-        : concreteClassName(field.foreignRef.targetAggregateId);
+      const target =
+        field.foreignRef.targetIsContract === true
+          ? contractTypeName(field.foreignRef.targetAggregateId)
+          : concreteClassName(field.foreignRef.targetAggregateId);
       return `ForeignRef<${target}>`;
     }
-    if (field.refAggregateId !== undefined) return `NomosRef<${concreteClassName(field.refAggregateId)}>`;
+    if (field.refAggregateId !== undefined)
+      return `NomosRef<${concreteClassName(field.refAggregateId)}>`;
+  }
+  if (
+    field?.kind === "string" &&
+    isSha256DigestSchema(field.zod as z.ZodTypeAny)
+  ) {
+    return "Sha256Digest";
   }
   return "String";
 }
@@ -90,13 +135,16 @@ function keyType(aggregate: AggregateHandle | undefined, key: string): string {
 function sharingOrderValue(
   policy: WorkspaceSharingPolicy,
   fieldName: string,
-  target: "wire" | "value" = "value",
+  target: "wire" | "value" = "value"
 ): string {
   const field = policy.orders.fields[fieldName];
   if (field === undefined) {
-    throw new Error(`workspaceSharing(${policy.orders.id}): unknown order field '${fieldName}'`);
+    throw new Error(
+      `workspaceSharing(${policy.orders.id}): unknown order field '${fieldName}'`
+    );
   }
-  const value = `(order.${member(fieldName)} ?? (throw StateError(` +
+  const value =
+    `(order.${member(fieldName)} ?? (throw StateError(` +
     `'Incomplete ${policy.orders.id} ${member(fieldName)}')))`;
   if (target === "wire" && field.kind === "enum") return `${value}.wire`;
   if (field.kind === "ref") return `NmsInternalNomosRefs.id(${value})`;
@@ -105,40 +153,51 @@ function sharingOrderValue(
 
 function sharingReceiptCondition(
   policy: WorkspaceSharingPolicy,
-  receipt: WorkspaceSharingReceipt,
+  receipt: WorkspaceSharingReceipt
 ): string {
   const condition = receipt.when;
   if (condition === undefined) return "true";
   const field = policy.orders.fields[condition.field];
   if (field === undefined) {
-    throw new Error(`workspaceSharing(${policy.orders.id}): unknown receipt field '${condition.field}'`);
+    throw new Error(
+      `workspaceSharing(${policy.orders.id}): unknown receipt field '${condition.field}'`
+    );
   }
   if (!field.isOptional) {
     if (condition.is === "absent") {
       throw new Error(
-        `workspaceSharing(${policy.orders.id}): '${condition.field}' cannot be absent because it is required`,
+        `workspaceSharing(${policy.orders.id}): '${condition.field}' cannot be absent because it is required`
       );
     }
     return "true";
   }
-  return `order.${member(condition.field)} ${condition.is === "present" ? "!=" : "=="} null`;
+  return `order.${member(condition.field)} ${
+    condition.is === "present" ? "!=" : "=="
+  } null`;
 }
 
 function sharingReceiptPayload(
   policy: WorkspaceSharingPolicy,
   receipt: WorkspaceSharingReceipt,
-  refused: boolean,
+  refused: boolean
 ): string[] {
-  const fields = introspectPayload(receipt.records.payloadSchema as z.ZodTypeAny, new Map());
+  const fields = introspectPayload(
+    receipt.records.payloadSchema as z.ZodTypeAny,
+    new Map()
+  );
   return fields.flatMap((target) => {
     if (target.name === "failureReason") {
       return refused
-        ? [`          'failureReason': share.message ?? 'shareDeliveryRefused',`]
+        ? [
+            `          'failureReason': share.message ?? 'shareDeliveryRefused',`,
+          ]
         : target.optional
-          ? []
-          : (() => { throw new Error(
-              `workspaceSharing(${policy.orders.id}): delivered receipt '${receipt.records.id}' requires failureReason`,
-            ); })();
+        ? []
+        : (() => {
+            throw new Error(
+              `workspaceSharing(${policy.orders.id}): delivered receipt '${receipt.records.id}' requires failureReason`
+            );
+          })();
     }
     if (target.name === "deliveryHead" && target.optional) return [];
     const sourceName = receipt.payload?.[target.name] ?? target.name;
@@ -147,7 +206,7 @@ function sharingReceiptPayload(
       if (target.optional) return [];
       throw new Error(
         `workspaceSharing(${policy.orders.id}): receipt '${receipt.records.id}' requires '${target.name}', ` +
-          `but the durable order does not record '${sourceName}'`,
+          `but the durable order does not record '${sourceName}'`
       );
     }
     const raw = sharingOrderValue(policy, sourceName);
@@ -156,34 +215,65 @@ function sharingReceiptPayload(
   });
 }
 
-export const dartApplicationClassName = (domain: string): string => `${cap(camel(domain))}Application`;
-export const dartApplicationActivityClassName = (domain: string): string => `${cap(camel(domain))}Activity`;
-export const dartAggregateCollectionClassName = (aggregate: AggregateHandle): string =>
-  `${concreteClassName(aggregate.id)}Collection`;
+export const dartApplicationClassName = (domain: string): string =>
+  `${cap(camel(domain))}Application`;
+export const dartApplicationActivityClassName = (domain: string): string =>
+  `${cap(camel(domain))}Activity`;
+export const dartAggregateCollectionClassName = (
+  aggregate: AggregateHandle
+): string => `${concreteClassName(aggregate.id)}Collection`;
 
-const aggregateConflictsClassName = (domain: string, aggregateId: string): string => {
+const aggregateConflictsClassName = (
+  domain: string,
+  aggregateId: string
+): string => {
   const aggregateName = cap(camel(concreteClassName(aggregateId)));
   return aggregateName === cap(camel(domain))
     ? `${aggregateName}AggregateConflicts`
     : `${aggregateName}Conflicts`;
 };
 
-const dartActionResultClassName = (directiveId: string): string => `${cap(camel(directiveId))}Result`;
+const dartActionResultClassName = (directiveId: string): string =>
+  `${cap(camel(directiveId))}Result`;
 
 function dartActionOutputs(
   directive: AnyDirective,
-  aggregates: readonly AggregateHandle[],
-): { aggregateId: string; field: string; dartType: string; many: boolean }[] {
-  const known = new Set(aggregates.filter((aggregate) => !isFrameworkAggregate(aggregate)).map((aggregate) => aggregate.id));
+  aggregates: readonly AggregateHandle[]
+): {
+  aggregateId: string;
+  field: string;
+  dartType: string;
+  many: boolean;
+  optional: boolean;
+}[] {
+  const known = new Set(
+    aggregates
+      .filter(
+        (aggregate) =>
+          !isFrameworkAggregate(aggregate) &&
+          (aggregate as { businessBirthInternal?: unknown })
+            .businessBirthInternal !== true
+      )
+      .map((aggregate) => aggregate.id)
+  );
   const raw = [
-    { aggregateId: directive.aggregateId, many: false },
-    ...((directive.secondaryOutputs ?? []).map((output) => ({
+    {
+      aggregateId: directive.aggregateId,
+      many: directive.outputCardinality === "many",
+      optional: directive.outputCardinality === "optional",
+    },
+    ...(directive.secondaryOutputs ?? []).map((output) => ({
       aggregateId: output.aggregateId,
       many: output.many === true,
-    }))),
+      optional: output.optional === true,
+    })),
   ].filter((output) => known.has(output.aggregateId));
-  const outputs = raw.filter((output, index) =>
-    raw.findIndex((candidate) => candidate.aggregateId === output.aggregateId) === index);
+  const outputs = raw.filter(
+    (output, index) =>
+      raw.findIndex(
+        (candidate) => candidate.aggregateId === output.aggregateId
+      ) === index
+  );
   const fields = new Set<string>();
   return outputs.map((output) => {
     const dartType = concreteClassName(output.aggregateId);
@@ -191,7 +281,7 @@ function dartActionOutputs(
     if (fields.has(field)) {
       throw new Error(
         `Dart application result for '${directive.id}' has two aggregate consequences named '${field}'; ` +
-          `rename one aggregate so the generated business result is unambiguous`,
+          `rename one aggregate so the generated business result is unambiguous`
       );
     }
     fields.add(field);
@@ -211,9 +301,16 @@ function dartConflictPublicClassNames(mod: DomainModule): string[] {
     const aggregateName = cap(camel(concreteClassName(binding.aggregateId)));
     names.add(aggregateConflictsClassName(domain, binding.aggregateId));
     names.add(`${aggregateName}PendingConflict`);
-    if (binding.valuePayloadField !== undefined && binding.idPayloadField !== undefined) {
+    if (
+      binding.valuePayloadField !== undefined &&
+      binding.idPayloadField !== undefined
+    ) {
       names.add(`${aggregateName}${cap(camel(binding.field))}Conflict`);
-      names.add(`${aggregateName}${cap(camel(binding.field))}ConflictModelUpdateRequired`);
+      names.add(
+        `${aggregateName}${cap(
+          camel(binding.field)
+        )}ConflictModelUpdateRequired`
+      );
     }
   }
   return [...names];
@@ -221,35 +318,50 @@ function dartConflictPublicClassNames(mod: DomainModule): string[] {
 
 export function dartApplicationPublicClassNames(
   mod: DomainModule,
-  opts: { readonly tenantRoot?: boolean } = {},
+  opts: { readonly tenantRoot?: boolean } = {}
 ): string[] {
   registerDartNames(mod.aggregates);
-  const actions = ((mod.applicationIntents ?? mod.directives) as AnyDirective[]).filter((directive) =>
-    directive &&
-    typeof directive.id === "string" &&
-    (directive as { businessBirthInternal?: unknown }).businessBirthInternal !== true &&
-    (directive as { businessBirth?: unknown }).businessBirth === undefined &&
-    (directive as { birthsChild?: unknown }).birthsChild !== true &&
-    !isFrameworkDirective(directive) &&
-    dartActionOutputs(directive, mod.aggregates).length > 0);
+  const actions = (
+    (mod.applicationIntents ?? mod.directives) as AnyDirective[]
+  ).filter(
+    (directive) =>
+      directive &&
+      typeof directive.id === "string" &&
+      (directive as { businessBirthInternal?: unknown })
+        .businessBirthInternal !== true &&
+      (directive as { businessBirth?: unknown }).businessBirth === undefined &&
+      (directive as { birthsChild?: unknown }).birthsChild !== true &&
+      !isFrameworkDirective(directive) &&
+      dartActionOutputs(directive, mod.aggregates).length > 0
+  );
   return [
     ...(opts.tenantRoot === true
-      ? ["Identity", "User", ...(mod.applicationWorkspaceSharing?.length ? ["Recipient", "Invitation"] : [])]
+      ? [
+          "Identity",
+          "User",
+          ...(mod.applicationWorkspaceSharing?.length
+            ? ["Recipient", "Invitation"]
+            : []),
+        ]
       : []),
     dartApplicationClassName(mod.domain ?? mod.name),
     dartApplicationActivityClassName(mod.domain ?? mod.name),
     ...actions.map((directive) => dartActionResultClassName(directive.id)),
     ...mod.aggregates
-      .filter((aggregate) =>
-        (aggregate as { businessBirthInternal?: unknown }).businessBirthInternal !== true &&
-        !isFrameworkAggregate(aggregate))
+      .filter(
+        (aggregate) =>
+          (aggregate as { businessBirthInternal?: unknown })
+            .businessBirthInternal !== true && !isFrameworkAggregate(aggregate)
+      )
       .map(dartAggregateCollectionClassName),
     ...dartConflictPublicClassNames(mod),
   ];
 }
 
 export interface DartApplicationOptions {
-  readonly packageAggregateDomains?: Readonly<Record<string, { domain: string; name: string }>>;
+  readonly packageAggregateDomains?: Readonly<
+    Record<string, { domain: string; name: string }>
+  >;
   readonly typesImportUri?: string;
   readonly explicitTypeImports?: readonly string[];
   readonly supportImport?: "vendored" | "package";
@@ -267,13 +379,18 @@ export interface DartApplicationOptions {
  * hosting and generated sibling facades import them directly from `src/generated`; tenant autocomplete sees
  * only `<Domain>Application`.
  */
-export function generateDartApplication(mod: DomainModule, opts: DartApplicationOptions = {}): string {
+export function generateDartApplication(
+  mod: DomainModule,
+  opts: DartApplicationOptions = {}
+): string {
   registerDartNames(mod.aggregates);
   const domain = mod.domain ?? mod.name;
   const application = dartApplicationClassName(domain);
   const activity = dartApplicationActivityClassName(domain);
   const client = dartClientClassName(domain);
-  const aggregates = new Map(mod.aggregates.map((aggregate) => [aggregate.id, aggregate]));
+  const aggregates = new Map(
+    mod.aggregates.map((aggregate) => [aggregate.id, aggregate])
+  );
   const packageDomains = opts.packageAggregateDomains ?? {};
   const appLines: string[] = [];
   const applicationMembers = new Map<string, string>();
@@ -282,7 +399,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
     if (prior !== undefined) {
       throw new Error(
         `Sorry mate — generated Dart application member '${name}' is already owned by ${prior}; ` +
-          `${owner} cannot be silently renamed or rerouted. Rename the tenant concept and compile again.`,
+          `${owner} cannot be silently renamed or rerouted. Rename the tenant concept and compile again.`
       );
     }
     applicationMembers.set(name, owner);
@@ -295,13 +412,114 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
   let usesWorkspaceName = false;
   let usesAffectedReference = false;
   let usesAffectedReferences = false;
+  let usesAffectedReferenceOrNull = false;
   const actionResultDeclarations: string[] = [];
   const conflictDeclarations: string[] = [];
-  const resolverBindings: readonly SurfacedResolverBinding[] = mod.surfacedResolvers ?? [];
-  const sharingPolicies: readonly WorkspaceSharingPolicy[] = mod.applicationWorkspaceSharing ?? [];
+  const resolverBindings: readonly SurfacedResolverBinding[] =
+    mod.surfacedResolvers ?? [];
+  const sharingPolicies: readonly WorkspaceSharingPolicy[] =
+    mod.applicationWorkspaceSharing ?? [];
+  const hasVersionedRefs = mod.aggregates.some((aggregate) =>
+    Object.values(aggregate.fields as Record<string, Field>).some(
+      (field) => field.versionedForeignRef !== undefined
+    )
+  );
+  if (hasVersionedRefs) {
+    claimApplicationMember(
+      "freshness",
+      "the generated versioned-reference boundary"
+    );
+    appLines.push(
+      `  /// Check whether [reference]'s immutable publication is still current. This reads the`,
+      `  /// stable series' one compiled pointer; it never reconstructs publication history.`,
+      `  Future<ReferenceFreshness<TVersion>> freshness<TVersion, TSeries>(`,
+      `      VersionedNomosRef<TVersion, TSeries> reference) =>`,
+      `      _client.referenceFreshness(reference);`,
+      ``
+    );
+  }
+  const versionedPayloadFactories = new Map<
+    string,
+    {
+      target: string;
+      series: string;
+      targetInput: string;
+      seriesInput: string;
+      targetWireType: string;
+      seriesWireType: string;
+      currentField: string;
+    }
+  >();
+  for (const directive of mod.directives as AnyDirective[]) {
+    if (!isBusinessIntent(directive)) continue;
+    for (const spec of introspectPayload(
+      directive.payloadSchema as z.ZodTypeAny,
+      new Map()
+    )) {
+      if (
+        spec.toJson !== "versionedRef" ||
+        spec.versionedRefTarget === undefined ||
+        spec.versionedRefSeries === undefined ||
+        spec.versionedRefTargetInput === undefined ||
+        spec.versionedRefSeriesInput === undefined ||
+        spec.versionedRefTargetWireType === undefined ||
+        spec.versionedRefSeriesWireType === undefined ||
+        spec.versionedRefCurrentField === undefined
+      )
+        continue;
+      const method = `pin${cap(camel(spec.name))}`;
+      const next = {
+        target: spec.versionedRefTarget,
+        series: spec.versionedRefSeries,
+        targetInput: spec.versionedRefTargetInput,
+        seriesInput: spec.versionedRefSeriesInput,
+        targetWireType: spec.versionedRefTargetWireType,
+        seriesWireType: spec.versionedRefSeriesWireType,
+        currentField: spec.versionedRefCurrentField,
+      };
+      const prior = versionedPayloadFactories.get(method);
+      if (
+        prior !== undefined &&
+        JSON.stringify(prior) !== JSON.stringify(next)
+      ) {
+        throw new Error(
+          `generated version-pin factory '${method}' names incompatible reference contracts; rename one payload field`
+        );
+      }
+      versionedPayloadFactories.set(method, next);
+    }
+  }
+  for (const [method, spec] of [...versionedPayloadFactories].sort(([a], [b]) =>
+    a.localeCompare(b)
+  )) {
+    claimApplicationMember(method, "the generated version-pin factory");
+    appLines.push(
+      `  /// Pin one immutable publication to its stable series. The current-pointer field is`,
+      `  /// compiled from domain law; callers provide typed records, never workspace/id strings.`,
+      `  VersionedNomosRef<${spec.target}, ${spec.series}> ${method}({`,
+      `    required NomosRef<${spec.targetInput}> pinned,`,
+      `    required NomosRef<${spec.seriesInput}> series,`,
+      `  }) {`,
+      `    if (pinned.workspace != series.workspace) {`,
+      `      throw ArgumentError('A version and its stable series must share one workspace');`,
+      `    }`,
+      `    return NmsInternalVersionedNomosRefs.create<${spec.target}, ${spec.series}>(`,
+      `      pinned: NmsInternalNomosRefs.retype<${
+        spec.target
+      }>(pinned, expectedType: ${JSON.stringify(spec.targetWireType)}),`,
+      `      series: NmsInternalNomosRefs.retype<${
+        spec.series
+      }>(series, expectedType: ${JSON.stringify(spec.seriesWireType)}),`,
+      `      currentField: ${JSON.stringify(spec.currentField)},`,
+      `    );`,
+      `  }`,
+      ``
+    );
+  }
   const tenantRoot = opts.tenantRoot ?? opts.flutterHost === true;
   if (tenantRoot) {
-    for (const [name, owner] of TENANT_ROOT_MEMBERS) claimApplicationMember(name, owner);
+    for (const [name, owner] of TENANT_ROOT_MEMBERS)
+      claimApplicationMember(name, owner);
   }
   if (!tenantRoot && sharingPolicies.length > 0) {
     for (const name of ["recipient", "createInvitation", "redeemInvitation"]) {
@@ -315,45 +533,76 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
   };
   const typeImportUriFor = (name: string): string => {
     for (const uri of explicitTypeImportUris) {
-      if (uri.endsWith(`/${name}.dart`) || uri.endsWith(`${name}.dart`)) return uri;
+      if (uri.endsWith(`/${name}.dart`) || uri.endsWith(`${name}.dart`))
+        return uri;
     }
     return `${name}.dart`;
   };
 
-  const actionDeclarations = (mod.applicationIntents ?? mod.directives) as AnyDirective[];
+  const actionDeclarations = (mod.applicationIntents ??
+    mod.directives) as AnyDirective[];
   const directives = actionDeclarations.filter(
-    (directive) => directive && typeof directive.id === "string" &&
-      typeof (directive as { payloadSchema?: unknown }).payloadSchema === "object" &&
-      (directive as { businessBirthInternal?: unknown }).businessBirthInternal !== true &&
-      !isFrameworkDirective(directive),
+    (directive) =>
+      directive &&
+      typeof directive.id === "string" &&
+      typeof (directive as { payloadSchema?: unknown }).payloadSchema ===
+        "object" &&
+      (directive as { businessBirthInternal?: unknown })
+        .businessBirthInternal !== true &&
+      !isFrameworkDirective(directive)
   );
   const actionReferenceChecks = (directive: AnyDirective): string[] => {
     let specs: ReturnType<typeof introspectPayload>;
     try {
-      specs = introspectPayload(directive.payloadSchema as z.ZodTypeAny, new Map());
+      specs = introspectPayload(
+        directive.payloadSchema as z.ZodTypeAny,
+        new Map()
+      );
     } catch {
       return [];
     }
     const recordInputIds = new Set(
-      dartBusinessRecordInputs(directive, mod.aggregates).map((input) => input.idField),
+      dartBusinessRecordInputs(directive, mod.aggregates).map(
+        (input) => input.idField
+      )
+    );
+    const foreignReferenceIds = new Set(
+      dartForeignReferenceInputs(directive, mod.aggregates).map(
+        (input) => input.idField
+      )
     );
     return specs
       .filter((spec) => spec.toJson === "ref" && !recordInputIds.has(spec.name))
       .map((spec) => {
-        const targetClass = spec.dartType.match(/^NomosRef<(.*)>$/)?.[1] ?? "Object?";
-        const targetWire = spec.referenceType ?? [...aggregates.values()].find(
-          (aggregate) => concreteClassName(aggregate.id) === targetClass,
-        )?.id ?? targetClass;
-        const value = `facts.${member(spec.name)}${spec.optional ? "!" : ""}`;
-        const check = `_nmsRequireReference(${value}, ${JSON.stringify(targetWire)}, _client.session?.workspace ?? '');`;
+        const targetClass =
+          spec.dartType.match(/^NomosRef<(.*)>$/)?.[1] ?? "Object?";
+        const targetWire =
+          spec.referenceType ??
+          [...aggregates.values()].find(
+            (aggregate) => concreteClassName(aggregate.id) === targetClass
+          )?.id ??
+          targetClass;
+        const expectedWorkspace = foreignReferenceIds.has(spec.name)
+          ? "''"
+          : "_client.session?.workspace ?? ''";
+        const value = `facts.${member(spec.name)}`;
+        const check = `_nmsRequireReference(${value}, ${JSON.stringify(
+          targetWire
+        )}, ${expectedWorkspace});`;
         return spec.optional
-          ? `    if (facts.${member(spec.name)} != null) ${check}`
+          ? `    ${value}.when(absent: () {}, present: (reference) => _nmsRequireReference(reference, ${JSON.stringify(
+              targetWire
+            )}, ${expectedWorkspace}));`
           : `    ${check}`;
       });
   };
 
   for (const aggregate of mod.aggregates) {
-    if ((aggregate as { businessBirthInternal?: unknown }).businessBirthInternal === true) continue;
+    if (
+      (aggregate as { businessBirthInternal?: unknown })
+        .businessBirthInternal === true
+    )
+      continue;
     if (isFrameworkAggregate(aggregate)) continue;
     collectionLines.set(aggregate.id, []);
     collectionMembers.set(aggregate.id, new Set());
@@ -367,7 +616,10 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
     const rowClass = `_${cap(camel(domain))}PendingConflictRow`;
     const byAggregate = new Map<string, SurfacedResolverBinding[]>();
     for (const binding of resolverBindings) {
-      byAggregate.set(binding.aggregateId, [...(byAggregate.get(binding.aggregateId) ?? []), binding]);
+      byAggregate.set(binding.aggregateId, [
+        ...(byAggregate.get(binding.aggregateId) ?? []),
+        binding,
+      ]);
     }
     claimApplicationMember("conflicts", "the generated conflict policy");
     appLines.push(`  final ${conflictsClass} conflicts;`);
@@ -398,17 +650,22 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
       `      byAggregate: Map.unmodifiable(byAggregate),`,
       `    );`,
       `  }`,
-      ...[...byAggregate.keys()].map((aggregateId) =>
-        `  ${aggregateConflictsClassName(domain, aggregateId)} get ${member(concreteClassName(aggregateId))} => ${aggregateConflictsClassName(domain, aggregateId)}._(_client);`,
+      ...[...byAggregate.keys()].map(
+        (aggregateId) =>
+          `  ${aggregateConflictsClassName(domain, aggregateId)} get ${member(
+            concreteClassName(aggregateId)
+          )} => ${aggregateConflictsClassName(domain, aggregateId)}._(_client);`
       ),
       `}`,
-      ``,
+      ``
     );
 
     for (const [aggregateId, bindings] of byAggregate) {
       const aggregate = aggregates.get(aggregateId);
       if (aggregate === undefined) {
-        throw new Error(`generated conflict policy refers to unknown aggregate '${aggregateId}' in domain '${domain}'`);
+        throw new Error(
+          `generated conflict policy refers to unknown aggregate '${aggregateId}' in domain '${domain}'`
+        );
       }
       const runtimeAggregateType = isNamespacedAggregate(aggregate)
         ? qualifyReadProjectionType(domain, aggregateId)
@@ -422,18 +679,23 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         `  String get aggregateId;`,
         `  String get field;`,
         `}`,
-        ``,
+        ``
       );
       for (const binding of bindings) {
-        if (binding.valuePayloadField === undefined || binding.idPayloadField === undefined) continue;
+        if (
+          binding.valuePayloadField === undefined ||
+          binding.idPayloadField === undefined
+        )
+          continue;
         const fieldKind = aggregate.fields[binding.field]?.kind;
-        const mergedType = fieldKind === "string" || fieldKind === "ref" || fieldKind === "enum"
-          ? "String"
-          : fieldKind === "int"
+        const mergedType =
+          fieldKind === "string" || fieldKind === "ref" || fieldKind === "enum"
+            ? "String"
+            : fieldKind === "int"
             ? "int"
             : fieldKind === "bool"
-              ? "bool"
-              : "Object?";
+            ? "bool"
+            : "Object?";
         const typeName = `${aggregateName}${cap(camel(binding.field))}Conflict`;
         const evolutionTypeName = `${typeName}ModelUpdateRequired`;
         const helper = `_merge${aggregateName}${cap(camel(binding.field))}`;
@@ -465,7 +727,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `  String get reason => _details.evolution?['reason']?.toString() ??`,
           `      'The business model cannot yet compare every retained version. Update its evolution policy; unrelated work can continue.';`,
           `}`,
-          ``,
+          ``
         );
       }
       conflictDeclarations.push(
@@ -473,13 +735,21 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         `  final ${client} _client;`,
         `  const ${aggregateClass}._(this._client);`,
         `  Future<List<${pendingClass}>> pending() async {`,
-        `    final rows = await _client._pendingConflictRows(${JSON.stringify(runtimeAggregateType)});`,
+        `    final rows = await _client._pendingConflictRows(${JSON.stringify(
+          runtimeAggregateType
+        )});`,
         `    final decisions = <${pendingClass}>[];`,
         `    for (final row in rows) {`,
         `      switch (row.field) {`,
         ...bindings.flatMap((binding) => {
-          if (binding.valuePayloadField === undefined || binding.idPayloadField === undefined) return [];
-          const typeName = `${aggregateName}${cap(camel(binding.field))}Conflict`;
+          if (
+            binding.valuePayloadField === undefined ||
+            binding.idPayloadField === undefined
+          )
+            return [];
+          const typeName = `${aggregateName}${cap(
+            camel(binding.field)
+          )}Conflict`;
           return [
             `        case ${JSON.stringify(binding.field)}:`,
             `          if (row.status == 'ready') {`,
@@ -496,94 +766,110 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         `    return List.unmodifiable(decisions);`,
         `  }`,
         `}`,
-        ``,
+        ``
       );
     }
   }
 
-  const addCollectionMember = (aggregateId: string, name: string, memberLines: string[]) => {
+  const addCollectionMember = (
+    aggregateId: string,
+    name: string,
+    memberLines: string[]
+  ) => {
     const target = collectionLines.get(aggregateId);
     if (target === undefined) return false;
     const names = collectionMembers.get(aggregateId)!;
     if (names.has(name)) {
-      throw new Error(`Dart application surface collision: '${aggregateId}.${name}' is declared more than once`);
+      throw new Error(
+        `Dart application surface collision: '${aggregateId}.${name}' is declared more than once`
+      );
     }
     names.add(name);
     target.push(...memberLines);
     return true;
   };
 
-  const sourceTrustAction = (directive: AnyDirective): {
+  const sourceTrustAction = (
+    directive: AnyDirective
+  ): {
     prelude: string[];
     call: string;
   } => {
+    const factPath = (path: string): string =>
+      path
+        .split(".")
+        .reduce((expr, part) => `${expr}.${member(part)}`, "facts");
     const trust = directive.businessSourceTrust;
     const method = member(directive.id);
     if (trust === undefined) {
       return { prelude: [], call: `_client.${method}(facts)` };
     }
-    const queryArgs = Object.entries(trust.queryArgs)
-      .sort(([a], [b]) => a.localeCompare(b))
-      .map(([argument, field]) => `${JSON.stringify(argument)}: facts.${member(field)}`);
     const copied = Object.entries(trust.copy)
       .sort(([a], [b]) => a.localeCompare(b))
-      .map(([target, field]) => `      ${JSON.stringify(target)}: facts.${member(field)},`);
+      .map(
+        ([target, field]) =>
+          `      ${JSON.stringify(target)}: ${factPath(field)},`
+      );
     return {
       prelude: [
-        `    final servedSource = await _client.bridge.attestedRead(`,
-        `      from: facts.${member(trust.fromPayload)},`,
-        `      queryId: ${JSON.stringify(trust.queryId)},`,
-        `      args: {${queryArgs.join(", ")}},`,
-        `    );`,
-        `    final sourceEntry = NmsInternalSourceTrust.entry(servedSource);`,
-        `    final sourceIdentity = NmsInternalSourceTrust.attestation(sourceEntry);`,
+        `    final sourceGenesis = await _client.bridge.nomosWorkspaceGenesis(${factPath(
+          trust.fromPayload
+        )});`,
         `    await _client._offer(`,
         `      ${JSON.stringify(trust.viaDirectiveId)},`,
         `      {`,
         ...copied,
-        `        ${JSON.stringify(trust.genesisField)}: NmsInternalSourceTrust.genesis(sourceIdentity),`,
-        `        ${JSON.stringify(trust.keyHashesField)}: [NmsInternalSourceTrust.keyHash(sourceIdentity)],`,
+        `        ${JSON.stringify(trust.genesisField)}: sourceGenesis,`,
+        `        ${JSON.stringify(trust.keyHashesField)}: [${JSON.stringify(
+          "0".repeat(64)
+        )}],`,
         `      },`,
         `    );`,
       ],
-      call: `_client.${method}(facts, attestations: [sourceEntry])`,
+      call: `_client.${method}(facts)`,
     };
   };
 
   if (sharingPolicies.length > 0) {
     appLines.push(
-        `  /// Turn an identity-provider uid into a typed business recipient.`,
-        `  ///`,
-        `  /// A uid crosses the string boundary once. Generated invitation actions then require`,
-        `  /// [Recipient<User>], so an email address, principal or record id cannot be substituted.`,
-        `  Recipient<User> recipient(String uid) =>`,
-        `      NmsInternalApplicationHost.recipient<User>(uid);`,
-        ``,
-        `  /// Create a single-use invitation. Transport [Invitation.link] however your product chooses.`,
-        `  Future<Invitation<User>> createInvitation() =>`,
-        `      NmsInternalApplicationHost.createInvitation<User>(_client.bridge);`,
-        ``,
-        `  /// Redeem a transported invitation link as the verified [currentUser].`,
-        `  Future<void> redeemInvitation(String link) =>`,
-        `      NmsInternalApplicationHost.redeemInvitation<User>(`,
-        `        _client.bridge,`,
-        `        link: link,`,
-        `        identity: _client.actor,`,
-        `        policies: [`,
-        ...sharingPolicies.map((policy) => [
+      `  /// Turn an identity-provider uid into a typed business recipient.`,
+      `  ///`,
+      `  /// A uid crosses the string boundary once. Generated invitation actions then require`,
+      `  /// [Recipient<User>], so an email address, principal or record id cannot be substituted.`,
+      `  Recipient<User> recipient(String uid) =>`,
+      `      NmsInternalApplicationHost.recipient<User>(uid);`,
+      ``,
+      `  /// Create a single-use invitation. Transport [Invitation.link] however your product chooses.`,
+      `  Future<Invitation<User>> createInvitation() =>`,
+      `      NmsInternalApplicationHost.createInvitation<User>(_client.bridge);`,
+      ``,
+      `  /// Redeem a transported invitation link as the verified [currentUser].`,
+      `  Future<void> redeemInvitation(String link) =>`,
+      `      NmsInternalApplicationHost.redeemInvitation<User>(`,
+      `        _client.bridge,`,
+      `        link: link,`,
+      `        identity: _client.actor,`,
+      `        policies: [`,
+      ...sharingPolicies
+        .map((policy) => [
           `          NmsInternalInvitationPolicy(`,
           `            domain: ${JSON.stringify(domain)},`,
           `            domainHash: _client.domainHash,`,
-          `            query: ${JSON.stringify(policy.invitationLaw.pendingByRecipient.id)},`,
-          `            redeem: ${JSON.stringify(policy.invitationLaw.redeem.id)},`,
+          `            query: ${JSON.stringify(
+            policy.invitationLaw.pendingByRecipient.id
+          )},`,
+          `            redeem: ${JSON.stringify(
+            policy.invitationLaw.redeem.id
+          )},`,
           `            personField: ${JSON.stringify(policy.person)},`,
           `            roleField: ${JSON.stringify(policy.role)},`,
           `            scopeField: ${JSON.stringify(policy.scope)},`,
           `          ),`,
-        ]).flat(),
-        `        ],`,
-        `      );`,
-        ``,
+        ])
+        .flat(),
+      `        ],`,
+      `      );`,
+      ``
     );
     for (const [index, policy] of sharingPolicies.entries()) {
       const pendingKey = policy.pending.key[0]!;
@@ -591,7 +877,10 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
       const person = sharingOrderValue(policy, policy.person, "wire");
       const role = sharingOrderValue(policy, policy.role, "wire");
       const scope = sharingOrderValue(policy, policy.scope, "wire");
-      const receiptLines = (receipt: WorkspaceSharingReceipt, refused: boolean): string[] => {
+      const receiptLines = (
+        receipt: WorkspaceSharingReceipt,
+        refused: boolean
+      ): string[] => {
         const condition = sharingReceiptCondition(policy, receipt);
         const body = [
           `        await _client._offer(`,
@@ -609,10 +898,18 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           ? body
           : [`      if (${condition}) {`, ...body, `      }`];
       };
-      const delivered = policy.delivered.flatMap((receipt) => receiptLines(receipt, false));
-      const refused = policy.refused.flatMap((receipt) => receiptLines(receipt, true));
-      const deliveredExhaustive = policy.delivered.some((receipt) => sharingReceiptCondition(policy, receipt) === "true");
-      const refusedExhaustive = policy.refused.some((receipt) => sharingReceiptCondition(policy, receipt) === "true");
+      const delivered = policy.delivered.flatMap((receipt) =>
+        receiptLines(receipt, false)
+      );
+      const refused = policy.refused.flatMap((receipt) =>
+        receiptLines(receipt, true)
+      );
+      const deliveredExhaustive = policy.delivered.some(
+        (receipt) => sharingReceiptCondition(policy, receipt) === "true"
+      );
+      const refusedExhaustive = policy.refused.some(
+        (receipt) => sharingReceiptCondition(policy, receipt) === "true"
+      );
       appLines.push(
         `  Future<void>? _nmsWorkspaceSharingDrain${index};`,
         `  StreamSubscription<Object?>? _nmsWorkspaceSharingSync${index};`,
@@ -662,34 +959,46 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         ...delivered,
         ...(deliveredExhaustive
           ? []
-          : [`        throw StateError('No delivered receipt matches ${policy.orders.id} \${NmsInternalNomosRefs.id(order.ref)}');`]),
+          : [
+              `        throw StateError('No delivered receipt matches ${policy.orders.id} \${NmsInternalNomosRefs.id(order.ref)}');`,
+            ]),
         `      }`,
         ...refused,
         ...(refusedExhaustive
           ? []
-          : [`      throw StateError('No refused receipt matches ${policy.orders.id} \${NmsInternalNomosRefs.id(order.ref)}');`]),
+          : [
+              `      throw StateError('No refused receipt matches ${policy.orders.id} \${NmsInternalNomosRefs.id(order.ref)}');`,
+            ]),
         `    }`,
         `  }`,
-        ``,
+        ``
       );
     }
     appLines.push(
       `  Future<void> _nmsStartWorkspaceSharing() async {`,
-      ...sharingPolicies.map((_policy, index) => `    await _nmsStartWorkspaceSharing${index}();`),
+      ...sharingPolicies.map(
+        (_policy, index) => `    await _nmsStartWorkspaceSharing${index}();`
+      ),
       `  }`,
       ``,
       `  Future<void> _nmsDrainWorkspaceSharing() async {`,
-      ...sharingPolicies.map((_policy, index) => `    await _nmsDrainWorkspaceSharing${index}();`),
+      ...sharingPolicies.map(
+        (_policy, index) => `    await _nmsDrainWorkspaceSharing${index}();`
+      ),
       `  }`,
-      ``,
+      ``
     );
   }
 
   const sharingInitiatorIds = new Set(
-    sharingPolicies.flatMap((policy) => policy.initiatedBy.map((intent) => intent.id)),
+    sharingPolicies.flatMap((policy) =>
+      policy.initiatedBy.map((intent) => intent.id)
+    )
   );
   const afterBusinessWrite = (directive: AnyDirective): string[] =>
-    sharingInitiatorIds.has(directive.id) ? [`    await _nmsDrainWorkspaceSharing();`] : [];
+    sharingInitiatorIds.has(directive.id)
+      ? [`    await _nmsDrainWorkspaceSharing();`]
+      : [];
   const businessActionDoc = (directive: AnyDirective): string => {
     return sharingInitiatorIds.has(directive.id)
       ? "One business action. Nomos durably delivers its access change and retries after restart or reconnect; do not mirror delivery in application state."
@@ -698,15 +1007,17 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
 
   const birthCollectionsWithMine = new Set<string>();
   for (const directive of directives) {
-    const birth = (directive as unknown as {
-      businessBirth?: {
-        aggregateId: string;
-        namespace: string;
-        rootId: string;
-        keyField: string;
-      };
-      birthsChild?: boolean;
-    }).businessBirth;
+    const birth = (
+      directive as unknown as {
+        businessBirth?: {
+          aggregateId: string;
+          namespace: string;
+          rootId: string;
+          keyField: string;
+        };
+        birthsChild?: boolean;
+      }
+    ).businessBirth;
     if (birth !== undefined) {
       // A business birth is declared on the parent domain but its aggregate
       // belongs to the child domain. Keep a generated collection for that
@@ -723,9 +1034,13 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
       const opener = `nomosInternalOpen${targetApplication}`;
       const rootAggregate = aggregates.get(birth.aggregateId);
       const rootType = concreteClassName(birth.aggregateId);
-      const rootCollection = member(plural(rootAggregate === undefined
-        ? birth.aggregateId
-        : concreteClassName(rootAggregate.id)));
+      const rootCollection = member(
+        plural(
+          rootAggregate === undefined
+            ? birth.aggregateId
+            : concreteClassName(rootAggregate.id)
+        )
+      );
       if (targetFile !== mod.name) {
         addSibling(`${targetFile}.application.dart`, targetApplication);
         addSibling(`${targetFile}.application.dart`, opener);
@@ -735,21 +1050,27 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         const method = member(directive.id);
         claimApplicationMember(method, `business intent '${directive.id}'`);
         appLines.push(
-          `  /// ${cap(camel(directive.id))}. One business action; the new ${birth.aggregateId} and every parent consequence commit atomically.`,
+          `  /// ${cap(camel(directive.id))}. One business action; the new ${
+            birth.aggregateId
+          } and every parent consequence commit atomically.`,
           `  /// Canonical write path: pass business facts here; never mirror this action in application state`,
           `  /// or call a lower-level client.`,
-          `  Future<${targetApplication}> ${method}(${dartActionInputClassName(directive)} facts) async {`,
+          `  Future<${targetApplication}> ${method}(${dartActionInputClassName(
+            directive
+          )} facts) async {`,
           `    final reference = await _client.${method}(facts);`,
           opts.supportImport === "package"
             ? `    return ${rootCollection}._nmsOpenReference(reference);`
             : `    return ${opener}(_client.bridge, reference, _client.actor);`,
           `  }`,
-          ``,
+          ``
         );
       } else {
         addCollectionMember(birth.aggregateId, "birth", [
           `  /// Give one ${birth.aggregateId} its own durable life.`,
-          `  Future<${targetApplication}> birth(Create${cap(camel(birth.aggregateId))}Input facts) async {`,
+          `  Future<${targetApplication}> birth(Create${cap(
+            camel(birth.aggregateId)
+          )}Input facts) async {`,
           `    final reference = await _client.birth(facts);`,
           opts.supportImport === "package"
             ? `    return _nmsOpenReference(reference);`
@@ -760,9 +1081,10 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
       }
       if (opts.supportImport === "package") {
         usesWorkspaceName = true;
-        const rootModel = rootAggregate === undefined
-          ? `${concreteClassName(birth.aggregateId)}ReadModel`
-          : readModelClassName(rootAggregate.id);
+        const rootModel =
+          rootAggregate === undefined
+            ? `${concreteClassName(birth.aggregateId)}ReadModel`
+            : readModelClassName(rootAggregate.id);
         addCollectionMember(birth.aggregateId, "open", [
           `  final Map<String, Future<${targetApplication}>> _nmsApplications = {};`,
           ``,
@@ -788,7 +1110,9 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `  /// Open the ${birth.aggregateId} whose ${birth.keyField} is [key].`,
           `  Future<${targetApplication}> open(String key) => _nmsOpenReference(`,
           `    NmsInternalNomosRefs.create<${rootType}>(`,
-          `      workspace: deriveWorkspaceName(${JSON.stringify(birth.namespace)}, key),`,
+          `      workspace: deriveWorkspaceName(${JSON.stringify(
+            birth.namespace
+          )}, key),`,
           `      type: ${JSON.stringify(birth.aggregateId)},`,
           `      id: ${JSON.stringify(birth.rootId)},`,
           `    ),`,
@@ -812,8 +1136,12 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `      final raw = row['data'];`,
           `      if (raw is! Map) continue;`,
           `      final child = (raw['child'] ?? '').toString();`,
-          `      if (!child.startsWith(${JSON.stringify(`${birth.namespace}-`)})) continue;`,
-          `      final reference = NmsInternalNomosRefs.create<${rootType}>(workspace: child, type: ${JSON.stringify(birth.aggregateId)}, id: ${JSON.stringify(birth.rootId)});`,
+          `      if (!child.startsWith(${JSON.stringify(
+            `${birth.namespace}-`
+          )})) continue;`,
+          `      final reference = NmsInternalNomosRefs.create<${rootType}>(workspace: child, type: ${JSON.stringify(
+            birth.aggregateId
+          )}, id: ${JSON.stringify(birth.rootId)});`,
           `      final application = await _nmsOpenReference(reference);`,
           `      final record = await application.${rootCollection}.find(reference);`,
           `      if (record != null) records.add(record);`,
@@ -840,18 +1168,34 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `    for (final record in records) {`,
           `      seen.add(NmsInternalRecordOrigins.require(record).workspace);`,
           `    }`,
-          `    final shares = await _client.bridge.query('aggregatesByType', {'__type': 'SharedWithMe'}, null, _client.actor);`,
+          `    for (final record in await shared()) {`,
+          `      final workspace = NmsInternalRecordOrigins.require(record).workspace;`,
+          `      if (seen.add(workspace)) records.add(record);`,
+          `    }`,
+          `    return records;`,
+          `  }`,
+          ``,
+          `  /// The ${birth.aggregateId} lives shared with the signed-in person.`,
+          `  /// Unlike [available], this does not open lives founded by that person.`,
+          `  Future<List<${rootModel}>> shared() async {`,
+          `    final records = <${rootModel}>[];`,
+          `    final seen = <String>{};`,
+          `    final shares = await _client.bridge.query('sharedByObject', {'object': 'workspace:self'}, null, _client.actor);`,
           `    for (final row in shares) {`,
           `      final raw = row['data'];`,
           `      if (raw is! Map) continue;`,
           `      final workspace = (raw['asserterWorkspace'] ?? '').toString();`,
           `      final object = (raw['object'] ?? '').toString();`,
           `      final prunedAt = (raw['prunedAt'] ?? '').toString();`,
-          `      if (!workspace.startsWith(${JSON.stringify(`${birth.namespace}-`)}) ||`,
+          `      if (!workspace.startsWith(${JSON.stringify(
+            `${birth.namespace}-`
+          )}) ||`,
           `          object != 'workspace:self' ||`,
           `          prunedAt.isNotEmpty ||`,
           `          !seen.add(workspace)) continue;`,
-          `      final reference = NmsInternalNomosRefs.create<${rootType}>(workspace: workspace, type: ${JSON.stringify(birth.aggregateId)}, id: ${JSON.stringify(birth.rootId)});`,
+          `      final reference = NmsInternalNomosRefs.create<${rootType}>(workspace: workspace, type: ${JSON.stringify(
+            birth.aggregateId
+          )}, id: ${JSON.stringify(birth.rootId)});`,
           `      final application = await _nmsOpenReference(reference);`,
           `      final record = await application.${rootCollection}.find(reference);`,
           `      if (record != null) records.add(record);`,
@@ -859,17 +1203,56 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `    return records;`,
           `  }`,
           ``,
+          `  /// React when this person's shared ${birth.aggregateId} lives change.`,
+          `  Stream<List<${rootModel}>> watchShared() =>`,
+          `      _client.bridge`,
+          `          .watch('sharedByObject', {'object': 'workspace:self'}, null, _client.actor, 60000)`,
+          `          .asyncMap((_) => shared());`,
+          ``,
           `  /// React when this person's available ${birth.aggregateId} lives change.`,
           `  Stream<List<${rootModel}>> watchAvailable() =>`,
-          `      _client.bridge`,
-          `          .watch('aggregatesByType', {'__type': 'SharedWithMe'}, null, _client.actor)`,
-          `          .asyncMap((_) => available());`,
+          `      Stream<List<${rootModel}>>.multi((events) {`,
+          `        var reading = false;`,
+          `        var reread = false;`,
+          `        Future<void> refresh() async {`,
+          `          if (reading) {`,
+          `            reread = true;`,
+          `            return;`,
+          `          }`,
+          `          reading = true;`,
+          `          do {`,
+          `            reread = false;`,
+          `            try {`,
+          `              final records = await available();`,
+          `              if (!events.isClosed) events.add(records);`,
+          `            } catch (error, stackTrace) {`,
+          `              if (!events.isClosed) events.addError(error, stackTrace);`,
+          `            }`,
+          `          } while (reread && !events.isClosed);`,
+          `          reading = false;`,
+          `        }`,
+          `        final birthChanges = _client.bridge`,
+          `            .watch('birthRecordsByPrincipal', {'principal': _client.actor}, null, null, 60000)`,
+          `            .skip(1)`,
+          `            .listen((_) { refresh(); }, onError: events.addError);`,
+          `        final shareChanges = _client.bridge`,
+          `            .watch('sharedByObject', {'object': 'workspace:self'}, null, _client.actor, 60000)`,
+          `            .skip(1)`,
+          `            .listen((_) { refresh(); }, onError: events.addError);`,
+          `        events.onCancel = () async {`,
+          `          await birthChanges.cancel();`,
+          `          await shareChanges.cancel();`,
+          `        };`,
+          `        refresh();`,
+          `      });`,
           ``,
           `  /// Continue working in the business application that produced [record].`,
           `  Future<${targetApplication}> applicationOf(${rootModel} record) {`,
           `    final origin = NmsInternalRecordOrigins.require(record);`,
           `    return _nmsOpenReference(`,
-          `      NmsInternalNomosRefs.create<${rootType}>(workspace: origin.workspace, type: ${JSON.stringify(birth.aggregateId)}, id: origin.id),`,
+          `      NmsInternalNomosRefs.create<${rootType}>(workspace: origin.workspace, type: ${JSON.stringify(
+            birth.aggregateId
+          )}, id: origin.id),`,
           `    );`,
           `  }`,
           ``,
@@ -889,24 +1272,42 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
     if (outputs.length > 0) {
       usesAffectedReference = true;
       usesAffectedReferences ||= outputs.some((output) => output.many);
+      usesAffectedReferenceOrNull ||= outputs.some((output) => output.optional);
       actionResultDeclarations.push(
         `/// Every business record affected by ${cap(camel(directive.id))}.`,
         `final class ${resultClass} {`,
         ...outputs.map((output) =>
           output.many
             ? `  final List<NomosRef<${output.dartType}>> ${output.field};`
-            : `  final NomosRef<${output.dartType}> ${output.field};`),
-        `  const ${resultClass}({${outputs.map((output) => `required this.${output.field}`).join(", ")}});`,
+            : output.optional
+            ? `  final NomosRef<${output.dartType}>? ${output.field};`
+            : `  final NomosRef<${output.dartType}> ${output.field};`
+        ),
+        `  const ${resultClass}({${outputs
+          .map((output) => `required this.${output.field}`)
+          .join(", ")}});`,
         `}`,
-        ``,
+        ``
       );
     }
-    const resultExpression = outputs.length === 0
-      ? undefined
-      : `${resultClass}(${outputs.map((output) =>
-          output.many
-            ? `${output.field}: _nmsAffectedReferences<${output.dartType}>(change, ${JSON.stringify(output.aggregateId)})`
-            : `${output.field}: _nmsAffectedReference<${output.dartType}>(change, ${JSON.stringify(output.aggregateId)})`).join(", ")})`;
+    const resultExpression =
+      outputs.length === 0
+        ? undefined
+        : `${resultClass}(${outputs
+            .map((output) =>
+              output.many
+                ? `${output.field}: _nmsAffectedReferences<${
+                    output.dartType
+                  }>(change, ${JSON.stringify(output.aggregateId)})`
+                : output.optional
+                ? `${output.field}: _nmsAffectedReferenceOrNull<${
+                    output.dartType
+                  }>(change, ${JSON.stringify(output.aggregateId)})`
+                : `${output.field}: _nmsAffectedReference<${
+                    output.dartType
+                  }>(change, ${JSON.stringify(output.aggregateId)})`
+            )
+            .join(", ")})`;
     if (isBusinessIntent(directive)) {
       claimApplicationMember(method, `business intent '${directive.id}'`);
       const sourceTrust = sourceTrustAction(directive);
@@ -922,7 +1323,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           ...afterBusinessWrite(directive),
           `    return ${resultExpression};`,
           `  }`,
-          ``,
+          ``
         );
       } else {
         appLines.push(
@@ -935,27 +1336,25 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `    await ${sourceTrust.call};`,
           ...afterBusinessWrite(directive),
           `  }`,
-          ``,
+          ``
         );
       }
       continue;
     }
     const sourceTrust = sourceTrustAction(directive);
     if (resultExpression !== undefined) {
-      addCollectionMember(
-        directive.aggregateId,
-        method,
-        [
-          `  /// ${cap(camel(directive.id))}. Returns every affected typed business record reference.`,
-          `  Future<${resultClass}> ${method}(${payload} facts) async {`,
-          ...referenceChecks,
-          ...sourceTrust.prelude,
-          `    final change = await ${sourceTrust.call};`,
-          `    return ${resultExpression};`,
-          `  }`,
-          ``,
-        ],
-      );
+      addCollectionMember(directive.aggregateId, method, [
+        `  /// ${cap(
+          camel(directive.id)
+        )}. Returns every affected typed business record reference.`,
+        `  Future<${resultClass}> ${method}(${payload} facts) async {`,
+        ...referenceChecks,
+        ...sourceTrust.prelude,
+        `    final change = await ${sourceTrust.call};`,
+        `    return ${resultExpression};`,
+        `  }`,
+        ``,
+      ]);
     } else {
       addCollectionMember(directive.aggregateId, method, [
         `  /// ${cap(camel(directive.id))}.`,
@@ -972,7 +1371,8 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
   const publicQueries = ((mod.queries ?? []) as QueryDecl[]).filter(
     (candidate) =>
       !isFrameworkQuery(candidate) &&
-      (candidate as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
+      (candidate as { businessBirthInternal?: unknown })
+        .businessBirthInternal !== true
   );
   const signedInSubjectKey = (query: QueryDecl): string | undefined => {
     if (query.key.length !== 1) return undefined;
@@ -985,31 +1385,46 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
     if (signedInSubjectKey(query) !== undefined) {
       mineQueriesByAggregate.set(
         query.returns,
-        (mineQueriesByAggregate.get(query.returns) ?? 0) + 1,
+        (mineQueriesByAggregate.get(query.returns) ?? 0) + 1
       );
     }
   }
   for (const query of publicQueries) {
     const model = readModelClassName(query.returns);
     const aggregate = aggregates.get(query.returns);
-    const params = query.key.map((key) => `required ${keyType(aggregate, key)} ${keyParam(key)}`).join(", ");
-    const args = query.key.map((key) => `${keyParam(key)}: ${keyParam(key)}`).join(", ");
+    const params = query.key
+      .map((key) => `required ${keyType(aggregate, key)} ${keyParam(key)}`)
+      .join(", ");
+    const args = query.key
+      .map((key) => `${keyParam(key)}: ${keyParam(key)}`)
+      .join(", ");
     const method = member(query.id);
     addCollectionMember(query.returns, method, [
       `  Future<List<${model}>> ${method}({${params}}) => _client.${method}(${args});`,
-      `  Stream<List<${model}>> watch${cap(camel(query.id))}({${params}}) => _client.watch${cap(camel(query.id))}(${args});`,
+      `  Stream<List<${model}>> watch${cap(
+        camel(query.id)
+      )}({${params}}) => _client.watch${cap(camel(query.id))}(${args});`,
       ``,
     ]);
     const subjectKey = signedInSubjectKey(query);
-    if (subjectKey !== undefined && !birthCollectionsWithMine.has(query.returns)) {
+    if (
+      subjectKey !== undefined &&
+      !birthCollectionsWithMine.has(query.returns)
+    ) {
       const subjectParam = keyParam(subjectKey);
       const subjectQueryCount = mineQueriesByAggregate.get(query.returns) ?? 0;
       const role = cap(camel(subjectKey.replace(/Subject$/, "") || "subject"));
       const mineMethod = subjectQueryCount === 1 ? "mine" : `mineAs${role}`;
-      const watchMineMethod = subjectQueryCount === 1 ? "watchMine" : `watchMineAs${role}`;
-      const relationship = subjectQueryCount === 1 ? "belonging to" : `where they are the ${role.toLowerCase()}`;
+      const watchMineMethod =
+        subjectQueryCount === 1 ? "watchMine" : `watchMineAs${role}`;
+      const relationship =
+        subjectQueryCount === 1
+          ? "belonging to"
+          : `where they are the ${role.toLowerCase()}`;
       addCollectionMember(query.returns, mineMethod, [
-        `  /// ${cap(camel(query.returns))} records ${relationship} the signed-in person.`,
+        `  /// ${cap(
+          camel(query.returns)
+        )} records ${relationship} the signed-in person.`,
         `  Future<List<${model}>> ${mineMethod}() {`,
         `    final subject = _client.actor;`,
         `    if (subject == null || subject.trim().isEmpty) {`,
@@ -1023,7 +1438,9 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         `    if (subject == null || subject.trim().isEmpty) {`,
         `      throw StateError('The signed-in person is not available.');`,
         `    }`,
-        `    return _client.watch${cap(camel(query.id))}(${subjectParam}: subject);`,
+        `    return _client.watch${cap(
+          camel(query.id)
+        )}(${subjectParam}: subject);`,
         `  }`,
         ``,
       ]);
@@ -1036,7 +1453,8 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
   for (const aggregate of mod.aggregates.filter(
     (candidate) =>
       !isFrameworkAggregate(candidate) &&
-      (candidate as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
+      (candidate as { businessBirthInternal?: unknown })
+        .businessBirthInternal !== true
   )) {
     const sourceModel = readModelClassName(aggregate.id);
     for (const contractId of aggregate.implementsContracts ?? []) {
@@ -1049,7 +1467,9 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         `  /// the contract that this aggregate explicitly implements. This does not grant access.`,
         `  NomosRef<${contract}> ${method}(${sourceModel} record) {`,
         `    final reference = record.ref;`,
-        `    _nmsRequireReference(reference, ${JSON.stringify(aggregate.id)}, '');`,
+        `    _nmsRequireReference(reference, ${JSON.stringify(
+          aggregate.id
+        )}, '');`,
         `    return NmsInternalNomosRefs.create<${contract}>(`,
         `      workspace: reference.workspace,`,
         `      type: ${JSON.stringify(contractId)},`,
@@ -1065,8 +1485,12 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         `  /// Use this after following a generated cross-application reference and opening`,
         `  /// its business application. Nomos checks the declared contract and access on read.`,
         `  Future<${sourceModel}?> ${resolveMethod}(ForeignRef<${contract}> reference) {`,
-        `    _nmsRequireReference(reference.ref, ${JSON.stringify(contractId)}, '');`,
-        `    return find(NmsInternalNomosRefs.create<${concreteClassName(aggregate.id)}>(`,
+        `    _nmsRequireReference(reference.ref, ${JSON.stringify(
+          contractId
+        )}, '');`,
+        `    return find(NmsInternalNomosRefs.create<${concreteClassName(
+          aggregate.id
+        )}>(`,
         `      workspace: reference.workspace,`,
         `      type: ${JSON.stringify(aggregate.id)},`,
         `      id: reference.id,`,
@@ -1078,8 +1502,12 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
       addCollectionMember(aggregate.id, watchMethod, [
         `  /// React when the concrete record behind [reference] changes.`,
         `  Stream<${sourceModel}?> ${watchMethod}(ForeignRef<${contract}> reference) {`,
-        `    _nmsRequireReference(reference.ref, ${JSON.stringify(contractId)}, '');`,
-        `    return watchOne(NmsInternalNomosRefs.create<${concreteClassName(aggregate.id)}>(`,
+        `    _nmsRequireReference(reference.ref, ${JSON.stringify(
+          contractId
+        )}, '');`,
+        `    return watchOne(NmsInternalNomosRefs.create<${concreteClassName(
+          aggregate.id
+        )}>(`,
         `      workspace: reference.workspace,`,
         `      type: ${JSON.stringify(aggregate.id)},`,
         `      id: reference.id,`,
@@ -1088,20 +1516,31 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         ``,
       ]);
     }
-    const sameDomainRefs = Object.entries(aggregate.fields).filter(([, field]) =>
-      field.kind === "ref" &&
-      field.foreignRef === undefined &&
-      field.refAggregateId !== undefined &&
-      field.refAggregateId !== aggregate.id &&
-      aggregates.has(field.refAggregateId),
+    const sameDomainRefs = Object.entries(aggregate.fields).filter(
+      ([, field]) =>
+        field.kind === "ref" &&
+        field.foreignRef === undefined &&
+        field.refAggregateId !== undefined &&
+        field.refAggregateId !== aggregate.id &&
+        aggregates.has(field.refAggregateId)
+    );
+    const crossDomainRefs = Object.entries(aggregate.fields).filter(
+      ([, field]) => {
+        if (
+          field.kind !== "ref" ||
+          field.foreignRef !== undefined ||
+          field.refAggregateId === undefined
+        )
+          return false;
+        if (aggregates.has(field.refAggregateId)) return false;
+        const owner = packageDomains[field.refAggregateId];
+        return owner !== undefined && owner.domain !== domain;
+      }
     );
-    const crossDomainRefs = Object.entries(aggregate.fields).filter(([, field]) => {
-      if (field.kind !== "ref" || field.foreignRef !== undefined || field.refAggregateId === undefined) return false;
-      if (aggregates.has(field.refAggregateId)) return false;
-      const owner = packageDomains[field.refAggregateId];
-      return owner !== undefined && owner.domain !== domain;
-    });
-    for (const [fieldName, field] of Object.entries(aggregate.fields) as [string, Field][]) {
+    for (const [fieldName, field] of Object.entries(aggregate.fields) as [
+      string,
+      Field
+    ][]) {
       const foreign = field.foreignRef;
       if (field.kind !== "ref") continue;
       if (foreign === undefined) {
@@ -1116,13 +1555,19 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         const sourceFieldValue = admitsNull(field)
           ? `record.${sourceFieldMember}.valueOrNull`
           : `record.${sourceFieldMember}`;
-        const isSameDomain = sameDomainRefs.some(([name]) => name === fieldName);
-        const isCrossDomain = crossDomainRefs.some(([name]) => name === fieldName);
+        const isSameDomain = sameDomainRefs.some(
+          ([name]) => name === fieldName
+        );
+        const isCrossDomain = crossDomainRefs.some(
+          ([name]) => name === fieldName
+        );
         if (!isSameDomain && !isCrossDomain) continue;
 
         if (isSameDomain) {
           const targetModel = readModelClassName(targetAggregateId);
-          const targetById = safe(`${lcFirst(camel(concreteClassName(targetAggregateId)))}ById`);
+          const targetById = safe(
+            `${lcFirst(camel(concreteClassName(targetAggregateId)))}ById`
+          );
           addCollectionMember(aggregate.id, method, [
             `  /// Resolve [record]'s ${fieldName} inside this business application.`,
             `  Future<${targetModel}?> ${method}(${sourceModel} record) async {`,
@@ -1132,7 +1577,9 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
                   `    if (id == null) return null;`,
                   `    final rows = await _client.${targetById}(NmsInternalNomosRefs.id(id));`,
                 ]
-              : [`    final rows = await _client.${targetById}(NmsInternalNomosRefs.id(record.${sourceFieldMember}));`]),
+              : [
+                  `    final rows = await _client.${targetById}(NmsInternalNomosRefs.id(record.${sourceFieldMember}));`,
+                ]),
             `    return rows.isEmpty ? null : rows.first;`,
             `  }`,
             ``,
@@ -1143,13 +1590,18 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         const owner = packageDomains[targetAggregateId];
         if (owner === undefined) continue;
         const targetModel = readModelClassName(targetAggregateId);
-        const targetCollection = member(plural(concreteClassName(targetAggregateId)));
+        const targetCollection = member(
+          plural(concreteClassName(targetAggregateId))
+        );
         const targetApplication = dartApplicationClassName(owner.domain);
         const opener = `nomosInternalOpen${targetApplication}`;
         // Flat output needs the sibling type file. Layered output's ordinary
         // types barrel already exports every domain; the explicit-barrel mode
         // supplies direct package imports in explicitTypeImportUris.
-        if (opts.typesImportUri === undefined || explicitTypeImportUris.size > 0) {
+        if (
+          opts.typesImportUri === undefined ||
+          explicitTypeImportUris.size > 0
+        ) {
           explicitTypeImportUris.add(typeImportUriFor(owner.name));
         }
         addSibling(`${owner.name}.application.dart`, targetApplication);
@@ -1211,14 +1663,17 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         ]);
         continue;
       }
-      const target = foreign.targetIsContract === true
-        ? contractTypeName(foreign.targetAggregateId)
-        : concreteClassName(foreign.targetAggregateId);
+      const target =
+        foreign.targetIsContract === true
+          ? contractTypeName(foreign.targetAggregateId)
+          : concreteClassName(foreign.targetAggregateId);
       const fieldMember = member(fieldName);
       const fieldValue = admitsNull(field)
         ? `record.${fieldMember}.valueOrNull`
         : `record.${fieldMember}`;
-      const stem = fieldMember.endsWith("Id") ? fieldMember.slice(0, -2) : fieldMember;
+      const stem = fieldMember.endsWith("Id")
+        ? fieldMember.slice(0, -2)
+        : fieldMember;
       const method = member(`${stem}Of`);
       addCollectionMember(aggregate.id, method, [
         `  /// Follow [record]'s ${fieldName} to its typed business record.`,
@@ -1227,15 +1682,18 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         `    if (reference == null) return null;`,
         `    final target = await NmsInternalForeignRefs.resolve(reference, _client.bridge.foreignReader());`,
         `    if (target == null) return null;`,
-        `    return NmsInternalRecordOrigins.remember(target, workspace: NmsInternalNomosRefs.workspace(reference.ref), type: ${JSON.stringify(foreign.targetAggregateId)}, id: NmsInternalNomosRefs.id(reference.ref));`,
+        `    return NmsInternalRecordOrigins.remember(target, workspace: NmsInternalNomosRefs.workspace(reference.ref), type: ${JSON.stringify(
+          foreign.targetAggregateId
+        )}, id: NmsInternalNomosRefs.id(reference.ref));`,
         `  }`,
         ``,
       ]);
-      const targetOwner = packageDomains[foreign.targetAggregateId] ??
+      const targetOwner =
+        packageDomains[foreign.targetAggregateId] ??
         (foreign.targetDomain === undefined
           ? undefined
           : Object.values(packageDomains).find(
-              (candidate) => candidate.domain === foreign.targetDomain,
+              (candidate) => candidate.domain === foreign.targetDomain
             ));
       if (targetOwner !== undefined && targetOwner.domain !== domain) {
         const targetApplication = dartApplicationClassName(targetOwner.domain);
@@ -1262,21 +1720,35 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
 
   for (const count of (mod.counts ?? []).map((raw) => finishCount(raw))) {
     const method = member(count.id);
-    const groupType = count.by == null ? "" : keyType(aggregates.get(count.of), count.by);
-    addCollectionMember(count.of, method, [count.by == null
-      ? `  Future<int> ${method}() => _client.${method}();`
-      : `  Future<int> ${method}(${groupType} ${keyParam(count.by)}) => _client.${method}(${keyParam(count.by)});`]);
+    const groupType =
+      count.by == null ? "" : keyType(aggregates.get(count.of), count.by);
+    addCollectionMember(count.of, method, [
+      count.by == null
+        ? `  Future<int> ${method}() => _client.${method}();`
+        : `  Future<int> ${method}(${groupType} ${keyParam(
+            count.by
+          )}) => _client.${method}(${keyParam(count.by)});`,
+    ]);
   }
   for (const sum of (mod.sums ?? []).map((raw) => finishSum(raw))) {
     const method = member(sum.id);
-    const groupType = sum.by == null ? "" : keyType(aggregates.get(sum.of), sum.by);
-    addCollectionMember(sum.of, method, [sum.by == null
-      ? `  Future<int> ${method}() => _client.${method}();`
-      : `  Future<int> ${method}(${groupType} ${keyParam(sum.by)}) => _client.${method}(${keyParam(sum.by)});`]);
+    const groupType =
+      sum.by == null ? "" : keyType(aggregates.get(sum.of), sum.by);
+    addCollectionMember(sum.of, method, [
+      sum.by == null
+        ? `  Future<int> ${method}() => _client.${method}();`
+        : `  Future<int> ${method}(${groupType} ${keyParam(
+            sum.by
+          )}) => _client.${method}(${keyParam(sum.by)});`,
+    ]);
   }
 
   for (const aggregate of mod.aggregates) {
-    if ((aggregate as { businessBirthInternal?: unknown }).businessBirthInternal === true) continue;
+    if (
+      (aggregate as { businessBirthInternal?: unknown })
+        .businessBirthInternal === true
+    )
+      continue;
     if (isFrameworkAggregate(aggregate)) continue;
     const concrete = concreteClassName(aggregate.id);
     const model = readModelClassName(aggregate.id);
@@ -1284,6 +1756,27 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
     const Cap = cap(camel(concrete));
     const aggregateRefType = `NomosRef<${concrete}>`;
     const clientList = safe(`list${Cap}s`);
+    addCollectionMember(aggregate.id, "ref", [
+      `  /// Qualify [id] as a typed ${concrete} reference in this application workspace.`,
+      `  ///`,
+      `  /// Use this at UI boundaries such as route parameters that intentionally retain only`,
+      `  /// the local aggregate id. Use [fromAddress] when the workspace is part of the value.`,
+      `  ${aggregateRefType} ref(String id) {`,
+      `    final workspace = _client.session?.workspace ?? '';`,
+      `    if (workspace.isEmpty) {`,
+      `      throw StateError('Cannot qualify a ${concrete} id before its application workspace is open.');`,
+      `    }`,
+      `    if (id.trim().isEmpty) {`,
+      `      throw ArgumentError.value(id, 'id', 'A business id cannot be empty.');`,
+      `    }`,
+      `    return NmsInternalNomosRefs.create<${concrete}>(`,
+      `      workspace: workspace,`,
+      `      type: ${JSON.stringify(aggregate.id)},`,
+      `      id: id,`,
+      `    );`,
+      `  }`,
+      ``,
+    ]);
     addCollectionMember(aggregate.id, "fromAddress", [
       `  /// Recover a typed ${concrete} reference from its stable public address.`,
       `  ///`,
@@ -1291,14 +1784,18 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
       `  /// still verify the signed-in person's access when the reference is used.`,
       `  ${aggregateRefType} fromAddress(String address) {`,
       `    final reference = NmsInternalNomosRefs.fromUri<${concrete}>(address);`,
-      `    _nmsRequireReference(reference, ${JSON.stringify(aggregate.id)}, '');`,
+      `    _nmsRequireReference(reference, ${JSON.stringify(
+        aggregate.id
+      )}, '');`,
       `    return reference;`,
       `  }`,
       ``,
     ]);
     addCollectionMember(aggregate.id, "find", [
       `  Future<${model}?> find(${aggregateRefType} reference) async {`,
-      `    _nmsRequireReference(reference, ${JSON.stringify(aggregate.id)}, '');`,
+      `    _nmsRequireReference(reference, ${JSON.stringify(
+        aggregate.id
+      )}, '');`,
       `    final targetWorkspace = NmsInternalNomosRefs.workspace(reference);`,
       `    final currentWorkspace = _client.session?.workspace ?? '';`,
       `    if (currentWorkspace.isNotEmpty && targetWorkspace != currentWorkspace) {`,
@@ -1307,21 +1804,27 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
       `      );`,
       `      return application.${member(plural(concrete))}.find(reference);`,
       `    }`,
-      `    final matches = await _client.${safe(`${stem}ById`)}(NmsInternalNomosRefs.id(reference));`,
+      `    final matches = await _client.${safe(
+        `${stem}ById`
+      )}(NmsInternalNomosRefs.id(reference));`,
       `    return matches.isEmpty ? null : matches.single;`,
       `  }`,
       ``,
     ]);
     addCollectionMember(aggregate.id, "watchOne", [
       `  Stream<${model}?> watchOne(${aggregateRefType} reference) {`,
-      `    _nmsRequireReference(reference, ${JSON.stringify(aggregate.id)}, '');`,
+      `    _nmsRequireReference(reference, ${JSON.stringify(
+        aggregate.id
+      )}, '');`,
       `    final targetWorkspace = NmsInternalNomosRefs.workspace(reference);`,
       `    final currentWorkspace = _client.session?.workspace ?? '';`,
       `    if (currentWorkspace.isNotEmpty && targetWorkspace != currentWorkspace) {`,
       `      return Stream.fromFuture(nomosInternalOpen${application}(`,
       `        _client.bridge, reference, _client.actor,`,
       `      )).asyncExpand(`,
-      `        (application) => application.${member(plural(concrete))}.watchOne(reference),`,
+      `        (application) => application.${member(
+        plural(concrete)
+      )}.watchOne(reference),`,
       `      );`,
       `    }`,
       `    return _client.watch${Cap}ById(NmsInternalNomosRefs.id(reference))`,
@@ -1343,12 +1846,14 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
   const initializers: string[] = [];
   for (const [aggregateId, members] of collectionLines) {
     const aggregate = aggregates.get(aggregateId);
-    const concrete = aggregate === undefined
-      ? concreteClassName(aggregateId)
-      : concreteClassName(aggregate.id);
-    const collection = aggregate === undefined
-      ? `${concrete}Collection`
-      : dartAggregateCollectionClassName(aggregate);
+    const concrete =
+      aggregate === undefined
+        ? concreteClassName(aggregateId)
+        : concreteClassName(aggregate.id);
+    const collection =
+      aggregate === undefined
+        ? `${concrete}Collection`
+        : dartAggregateCollectionClassName(aggregate);
     const property = member(plural(concrete));
     claimApplicationMember(property, `aggregate collection '${aggregateId}'`);
     appLines.push(`  final ${collection} ${property};`);
@@ -1365,39 +1870,65 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
       ``,
       ...members,
       `}`,
-      ``,
+      ``
     );
   }
 
   const imports = [...siblingImports.entries()]
     .sort(([a], [b]) => a.localeCompare(b))
-    .map(([file, names]) => `import '${file}' show ${[...names].sort().join(", ")};`);
+    .map(
+      ([file, names]) =>
+        `import '${file}' show ${[...names].sort().join(", ")};`
+    );
   const typesImport = opts.typesImportUri ?? `${mod.name}.dart`;
-  const runtimeImport = opts.supportImport === "package"
-    ? "package:nomos_client/src/nms_generated_runtime.dart"
-    : "nomos_client.dart";
+  const runtimeImport =
+    opts.supportImport === "package"
+      ? "package:nomos_client/src/nms_generated_runtime.dart"
+      : "nomos_client.dart";
   const applicationInitializers = [
     "_client = client",
     ...(tenantRoot ? ["currentUser = currentUser"] : []),
     `activity = ${activity}._(client)`,
-    ...(resolverBindings.length > 0 ? [`conflicts = ${cap(camel(domain))}Conflicts._(client)`] : []),
+    ...(resolverBindings.length > 0
+      ? [`conflicts = ${cap(camel(domain))}Conflicts._(client)`]
+      : []),
     ...initializers,
   ];
   return [
     `// AUTO-GENERATED by nomos-compile — the tenant application surface for "${domain}".`,
     `// Business facts in, business records out. Runtime lifecycle is deliberately absent.`,
-    ...(sharingPolicies.length > 0 ? [`import 'dart:async' show StreamSubscription, unawaited;`] : []),
-    `import '${runtimeImport}' show NmsInternalForeignRefs, NmsInternalNomosRefs, NmsInternalRecordOrigins, NomosBridge, NomosOfferOutcome, NomosRef, NomosSession${usesWorkspaceName ? ", deriveWorkspaceName" : ""}${sharingPolicies.length > 0 ? ", Invitation, Recipient, SyncPhase, User" : ""}${tenantRoot ? ", NmsInternalUsers, nmsInternalReceivingGroupNameOf" : ""};`,
+    ...(sharingPolicies.length > 0
+      ? [`import 'dart:async' show StreamSubscription, unawaited;`]
+      : []),
+    `import '${runtimeImport}' show NmsInternalForeignRefs, NmsInternalNomosRefs, NmsInternalRecordOrigins, NomosBridge, NomosOfferOutcome, NomosRef, NomosSession${
+      usesWorkspaceName ? ", deriveWorkspaceName" : ""
+    }${
+      sharingPolicies.length > 0
+        ? ", Invitation, Recipient, SyncPhase, User"
+        : ""
+    }${
+      tenantRoot ? ", NmsInternalUsers, nmsInternalReceivingGroupNameOf" : ""
+    };`,
     ...(opts.flutterHost === true || sharingPolicies.length > 0
       ? [
           ...(tenantRoot ? [`import 'package:flutter/widgets.dart';`] : []),
           ...(sharingPolicies.length > 0
-            ? [`import 'package:nomos_flutter/src/application_share.dart' show ApplicationShareResult;`]
+            ? [
+                `import 'package:nomos_flutter/src/application_share.dart' show ApplicationShareResult;`,
+              ]
             : []),
           ...(opts.flutterHost === true && tenantRoot
-            ? [`import 'package:nomos_flutter/src/application_status.dart' show ApplicationSignIn, ApplicationStatus;`]
+            ? [
+                `import 'package:nomos_flutter/src/application_status.dart' show ApplicationSignIn, ApplicationStatus;`,
+              ]
             : []),
-          `import 'package:nomos_flutter/src/generated_application_host.dart' show NmsInternalApplicationUserBinding${tenantRoot || sharingPolicies.length > 0 ? ", NmsInternalApplicationHost" : ""}${sharingPolicies.length > 0 ? ", NmsInternalInvitationPolicy" : ""};`,
+          `import 'package:nomos_flutter/src/generated_application_host.dart' show NmsInternalApplicationUserBinding${
+            tenantRoot || sharingPolicies.length > 0
+              ? ", NmsInternalApplicationHost"
+              : ""
+          }${
+            sharingPolicies.length > 0 ? ", NmsInternalInvitationPolicy" : ""
+          };`,
         ]
       : []),
     `import '${typesImport}';`,
@@ -1406,9 +1937,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
     ...imports,
     ``,
     ...(tenantRoot
-      ? [
-          `/// The canonical stateful entry point for this business domain.`,
-        ]
+      ? [`/// The canonical stateful entry point for this business domain.`]
       : [
           `/// A business domain handle owned by the generated package application.`,
         ]),
@@ -1440,7 +1969,9 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
     ...(tenantRoot ? [`  final User currentUser;`] : []),
     `  final ${activity} activity;`,
     ...appLines,
-    `  ${application}._(${client} client${tenantRoot ? ", User currentUser" : ""}) : ${applicationInitializers.join(", ")};`,
+    `  ${application}._(${client} client${
+      tenantRoot ? ", User currentUser" : ""
+    }) : ${applicationInitializers.join(", ")};`,
     ...(opts.flutterHost === true && tenantRoot
       ? [
           ``,
@@ -1473,14 +2004,23 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
       : []),
     `}`,
     ``,
-    `/// The verified business history of this application, newest first.`,
+    `/// The verified recent business activity of this application, newest first.`,
     `final class ${activity} {`,
     `  final ${client} _client;`,
     `  const ${activity}._(this._client);`,
     ``,
-    `  Future<List<ActivityEvent>> all({int? limit}) => _client.activityLog(limit: limit);`,
+    `  Future<List<ActivityEvent>> recent({required int limit}) =>`,
+    `      _client.recentActivity(limit: limit);`,
+    ``,
+    `  Stream<List<ActivityEvent>> watchRecent({required int limit}) =>`,
+    `      _client.watchRecentActivity(limit: limit);`,
+    ``,
+    `  @Deprecated('Reads ledger history. Use recent with an explicit limit, or a DSL managed count for quantities.')`,
+    `  Future<List<ActivityEvent>> all({int? limit}) =>`,
+    `      recent(limit: limit ?? 50);`,
     ``,
-    `  Stream<List<ActivityEvent>> watchAll() => _client.watchActivity();`,
+    `  @Deprecated('Reads ledger history. Use watchRecent with an explicit limit.')`,
+    `  Stream<List<ActivityEvent>> watchAll() => watchRecent(limit: 50);`,
     `}`,
     ``,
     ...actionResultDeclarations,
@@ -1518,6 +2058,26 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `  return NmsInternalNomosRefs.create<T>(workspace: workspace, type: affected.type, id: affected.id);`,
           `}`,
           ``,
+          ...(usesAffectedReferenceOrNull
+            ? [
+                `NomosRef<T>? _nmsAffectedReferenceOrNull<T>(NomosOfferOutcome change, String expectedType) {`,
+                `  final matches = change.affected`,
+                `      .where((affected) => _nmsReferenceTypeMatches(affected.type, expectedType))`,
+                `      .toList(growable: false);`,
+                `  if (matches.length > 1) {`,
+                `    throw StateError('The business action expected at most one affected $expectedType record, received \${matches.length}');`,
+                `  }`,
+                `  if (matches.isEmpty) return null;`,
+                `  final affected = matches.single;`,
+                `  final workspace = affected.workspace.isNotEmpty ? affected.workspace : change.workspace;`,
+                `  if (workspace.isEmpty) {`,
+                `    throw StateError('The affected record did not carry its business workspace');`,
+                `  }`,
+                `  return NmsInternalNomosRefs.create<T>(workspace: workspace, type: affected.type, id: affected.id);`,
+                `}`,
+                ``,
+              ]
+            : []),
           ...(usesAffectedReferences
             ? [
                 `List<NomosRef<T>> _nmsAffectedReferences<T>(NomosOfferOutcome change, String expectedType) {`,
@@ -1542,9 +2102,13 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `Future<${application}> nomosInternalBind${application}(`,
           `    NomosSession session, NmsInternalApplicationUserBinding user) async {`,
           `  final application = ${application}._(`,
-          `    await ${client}.bind(session, actor: user.nmsInternalActor)${tenantRoot ? "," : ""}`,
+          `    await ${client}.bind(session, actor: user.nmsInternalActor)${
+            tenantRoot ? "," : ""
+          }`,
           ...(tenantRoot
-            ? [`    NmsInternalUsers.create(identityId: user.nmsInternalIdentityId, identityAddress: user.nmsInternalIdentityAddress),`]
+            ? [
+                `    NmsInternalUsers.create(identityId: user.nmsInternalIdentityId, identityAddress: user.nmsInternalIdentityAddress),`,
+              ]
             : []),
           `  );`,
         ]
@@ -1552,7 +2116,9 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `Future<${application}> nomosInternalBind${application}(NomosSession session, String? actor) async {`,
           `  final application = ${application}._(await ${client}.bind(session, actor: actor));`,
         ]),
-    ...(sharingPolicies.length > 0 ? [`  await application._nmsStartWorkspaceSharing();`] : []),
+    ...(sharingPolicies.length > 0
+      ? [`  await application._nmsStartWorkspaceSharing();`]
+      : []),
     `  return application;`,
     `}`,
     ``,
@@ -1570,8 +2136,12 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `    ),`,
           `  );`,
         ]
-      : [`  final application = ${application}._(await ${client}.open(bridge, ref: reference, actor: actor));`]),
-    ...(sharingPolicies.length > 0 ? [`  await application._nmsStartWorkspaceSharing();`] : []),
+      : [
+          `  final application = ${application}._(await ${client}.open(bridge, ref: reference, actor: actor));`,
+        ]),
+    ...(sharingPolicies.length > 0
+      ? [`  await application._nmsStartWorkspaceSharing();`]
+      : []),
     `  return application;`,
     `}`,
     ``,