@githolon/dsl 0.101.6 → 0.102.0

package/src/codegen_dart_application.ts

@@ -0,0 +1,1508 @@
+// Generated tenant-facing Dart application facade.
+//
+// The bridge-bound `<domain>.client.dart` is an implementation detail. This file is the exported
+// application contract: business inputs in, business ids/models out. It deliberately has no public
+// bridge/session/workspace/actor/sync surface.
+import type { z } from "zod";
+
+import type { AggregateHandle } from "./aggregate.js";
+import type { Directive } from "./directive.js";
+import type { Field } from "./fields.js";
+import type { QueryDecl } from "./query.js";
+import type { DomainModule } from "./codegen_dart.js";
+import {
+  cap,
+  concreteClassName,
+  dartBusinessRecordInputs,
+  dartActionInputClassName,
+  introspectPayload,
+  readModelClassName,
+  registerDartNames,
+} from "./codegen_dart.js";
+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 type { SurfacedResolverBinding } from "./surfaced_lint.js";
+import {
+  isFrameworkAggregate,
+  isFrameworkDirective,
+  isFrameworkQuery,
+} from "./framework/framework_aggregates.js";
+import { isBusinessIntent } from "./intent.js";
+import { contractTypeName } from "./contract.js";
+import type {
+  WorkspaceSharingPolicy,
+  WorkspaceSharingReceipt,
+} from "./workspace_sharing.js";
+
+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 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",
+]);
+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"],
+  ["currentUser", "the generated signed-in application participant"],
+  ["currentStatus", "the generated application status"],
+  ["watchStatus", "the generated application status watch"],
+  ["recipient", "the generated typed recipient boundary"],
+  ["createInvitation", "the generated invitation capability"],
+  ["redeemInvitation", "the generated invitation redemption"],
+]);
+
+function plural(name: string): string {
+  if (/[^aeiou]y$/i.test(name)) return `${name.slice(0, -1)}ies`;
+  if (/(?:s|x|z|ch|sh)$/i.test(name)) return `${name}es`;
+  return `${name}s`;
+}
+
+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 cleaned = raw.replace(/[^A-Za-z0-9_]/g, "_");
+  return safe(/^[0-9]/.test(cleaned) ? `v${cleaned}` : cleaned);
+}
+
+function keyType(aggregate: AggregateHandle | undefined, key: string): string {
+  const first = key.includes(".") ? key.split(".")[0]! : key;
+  const field = aggregate?.fields[first] as Field | undefined;
+  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);
+      return `ForeignRef<${target}>`;
+    }
+    if (field.refAggregateId !== undefined) return `NomosRef<${concreteClassName(field.refAggregateId)}>`;
+  }
+  return "String";
+}
+
+function sharingOrderValue(
+  policy: WorkspaceSharingPolicy,
+  fieldName: string,
+  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}'`);
+  }
+  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})`;
+  return value;
+}
+
+function sharingReceiptCondition(
+  policy: WorkspaceSharingPolicy,
+  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}'`);
+  }
+  if (!field.isOptional) {
+    if (condition.is === "absent") {
+      throw new Error(
+        `workspaceSharing(${policy.orders.id}): '${condition.field}' cannot be absent because it is required`,
+      );
+    }
+    return "true";
+  }
+  return `order.${member(condition.field)} ${condition.is === "present" ? "!=" : "=="} null`;
+}
+
+function sharingReceiptPayload(
+  policy: WorkspaceSharingPolicy,
+  receipt: WorkspaceSharingReceipt,
+  refused: boolean,
+): string[] {
+  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',`]
+        : target.optional
+          ? []
+          : (() => { 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;
+    const source = policy.orders.fields[sourceName];
+    if (source === undefined) {
+      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}'`,
+      );
+    }
+    const raw = sharingOrderValue(policy, sourceName);
+    const expression = source.kind === "enum" ? `${raw}.wire` : raw;
+    return [`          ${JSON.stringify(target.name)}: ${expression},`];
+  });
+}
+
+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 aggregateName = cap(camel(concreteClassName(aggregateId)));
+  return aggregateName === cap(camel(domain))
+    ? `${aggregateName}AggregateConflicts`
+    : `${aggregateName}Conflicts`;
+};
+
+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));
+  const raw = [
+    { aggregateId: directive.aggregateId, many: false },
+    ...((directive.secondaryOutputs ?? []).map((output) => ({
+      aggregateId: output.aggregateId,
+      many: output.many === true,
+    }))),
+  ].filter((output) => known.has(output.aggregateId));
+  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);
+    const field = member(dartType);
+    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`,
+      );
+    }
+    fields.add(field);
+    return { ...output, field, dartType };
+  });
+}
+
+function dartConflictPublicClassNames(mod: DomainModule): string[] {
+  const domain = mod.domain ?? mod.name;
+  const bindings = mod.surfacedResolvers ?? [];
+  if (bindings.length === 0) return [];
+  const names = new Set<string>([
+    `${cap(camel(domain))}Conflicts`,
+    `${cap(camel(domain))}ConflictSummary`,
+  ]);
+  for (const binding of bindings) {
+    const aggregateName = cap(camel(concreteClassName(binding.aggregateId)));
+    names.add(aggregateConflictsClassName(domain, binding.aggregateId));
+    names.add(`${aggregateName}PendingConflict`);
+    if (binding.valuePayloadField !== undefined && binding.idPayloadField !== undefined) {
+      names.add(`${aggregateName}${cap(camel(binding.field))}Conflict`);
+      names.add(`${aggregateName}${cap(camel(binding.field))}ConflictModelUpdateRequired`);
+    }
+  }
+  return [...names];
+}
+
+export function dartApplicationPublicClassNames(
+  mod: DomainModule,
+  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);
+  return [
+    ...(opts.tenantRoot === true
+      ? ["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))
+      .map(dartAggregateCollectionClassName),
+    ...dartConflictPublicClassNames(mod),
+  ];
+}
+
+export interface DartApplicationOptions {
+  readonly packageAggregateDomains?: Readonly<Record<string, { domain: string; name: string }>>;
+  readonly typesImportUri?: string;
+  readonly explicitTypeImports?: readonly string[];
+  readonly supportImport?: "vendored" | "package";
+  readonly flutterHost?: boolean;
+  /// Whether this domain application is the tenant's one public Flutter root.
+  /// Multi-domain package children remain stateful business handles, but only
+  /// the generated package application may mount or expose application status.
+  readonly tenantRoot?: boolean;
+}
+
+/**
+ * Emit the exported business facade for one generated domain.
+ *
+ * The two `nomosInternal...` functions are intentionally omitted from package barrels. Generated Flutter
+ * 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 {
+  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 packageDomains = opts.packageAggregateDomains ?? {};
+  const appLines: string[] = [];
+  const applicationMembers = new Map<string, string>();
+  const claimApplicationMember = (name: string, owner: string): void => {
+    const prior = applicationMembers.get(name);
+    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.`,
+      );
+    }
+    applicationMembers.set(name, owner);
+  };
+  claimApplicationMember("activity", "the generated business history");
+  const collectionLines = new Map<string, string[]>();
+  const collectionMembers = new Map<string, Set<string>>();
+  const siblingImports = new Map<string, Set<string>>();
+  const explicitTypeImportUris = new Set(opts.explicitTypeImports ?? []);
+  let usesWorkspaceName = false;
+  let usesAffectedReference = false;
+  let usesAffectedReferences = false;
+  const actionResultDeclarations: string[] = [];
+  const conflictDeclarations: string[] = [];
+  const resolverBindings: readonly SurfacedResolverBinding[] = mod.surfacedResolvers ?? [];
+  const sharingPolicies: readonly WorkspaceSharingPolicy[] = mod.applicationWorkspaceSharing ?? [];
+  const tenantRoot = opts.tenantRoot ?? opts.flutterHost === true;
+  if (tenantRoot) {
+    for (const [name, owner] of TENANT_ROOT_MEMBERS) claimApplicationMember(name, owner);
+  }
+  if (!tenantRoot && sharingPolicies.length > 0) {
+    for (const name of ["recipient", "createInvitation", "redeemInvitation"]) {
+      claimApplicationMember(name, "the generated invitation boundary");
+    }
+  }
+  const addSibling = (file: string, name: string) => {
+    if (explicitTypeImportUris.has(file)) return;
+    if (!siblingImports.has(file)) siblingImports.set(file, new Set());
+    siblingImports.get(file)!.add(name);
+  };
+  const typeImportUriFor = (name: string): string => {
+    for (const uri of explicitTypeImportUris) {
+      if (uri.endsWith(`/${name}.dart`) || uri.endsWith(`${name}.dart`)) return uri;
+    }
+    return `${name}.dart`;
+  };
+
+  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),
+  );
+  const actionReferenceChecks = (directive: AnyDirective): string[] => {
+    let specs: ReturnType<typeof introspectPayload>;
+    try {
+      specs = introspectPayload(directive.payloadSchema as z.ZodTypeAny, new Map());
+    } catch {
+      return [];
+    }
+    const recordInputIds = new Set(
+      dartBusinessRecordInputs(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 ?? '');`;
+        return spec.optional
+          ? `    if (facts.${member(spec.name)} != null) ${check}`
+          : `    ${check}`;
+      });
+  };
+
+  for (const aggregate of mod.aggregates) {
+    if ((aggregate as { businessBirthInternal?: unknown }).businessBirthInternal === true) continue;
+    if (isFrameworkAggregate(aggregate)) continue;
+    collectionLines.set(aggregate.id, []);
+    collectionMembers.set(aggregate.id, new Set());
+  }
+
+  // Conflicts are business decisions, so the application facade keeps the useful chain while the
+  // heterogeneous index, immutable proof snapshot and offer result remain implementation details.
+  if (resolverBindings.length > 0) {
+    const conflictsClass = `${cap(camel(domain))}Conflicts`;
+    const summaryClass = `${cap(camel(domain))}ConflictSummary`;
+    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]);
+    }
+    claimApplicationMember("conflicts", "the generated conflict policy");
+    appLines.push(`  final ${conflictsClass} conflicts;`);
+
+    conflictDeclarations.push(
+      `/// Pending business decisions across this application.`,
+      `final class ${summaryClass} {`,
+      `  final int total;`,
+      `  final int ready;`,
+      `  final int modelUpdatesRequired;`,
+      `  final Map<String, int> byAggregate;`,
+      `  const ${summaryClass}({required this.total, required this.ready, required this.modelUpdatesRequired, required this.byAggregate});`,
+      `}`,
+      ``,
+      `/// Summary -> aggregate -> typed conflict -> merge.`,
+      `final class ${conflictsClass} {`,
+      `  final ${client} _client;`,
+      `  const ${conflictsClass}._(this._client);`,
+      ``,
+      `  Future<${summaryClass}> summary() async {`,
+      `    final summary = await _client.bridge.pendingConflictSummary();`,
+      `    final byAggregate = (summary['byAggregate'] as Map? ?? const {}).map(`,
+      `        (key, value) => MapEntry(key.toString(), (value as num).toInt()));`,
+      `    return ${summaryClass}(`,
+      `      total: (summary['total'] as num? ?? 0).toInt(),`,
+      `      ready: (summary['ready'] as num? ?? 0).toInt(),`,
+      `      modelUpdatesRequired: (summary['evolutionRequired'] as num? ?? 0).toInt(),`,
+      `      byAggregate: Map.unmodifiable(byAggregate),`,
+      `    );`,
+      `  }`,
+      ...[...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}'`);
+      }
+      const runtimeAggregateType = isNamespacedAggregate(aggregate)
+        ? qualifyReadProjectionType(domain, aggregateId)
+        : aggregateId;
+      const aggregateName = cap(camel(concreteClassName(aggregateId)));
+      const pendingClass = `${aggregateName}PendingConflict`;
+      const aggregateClass = aggregateConflictsClassName(domain, aggregateId);
+      conflictDeclarations.push(
+        `sealed class ${pendingClass} {`,
+        `  const ${pendingClass}();`,
+        `  String get aggregateId;`,
+        `  String get field;`,
+        `}`,
+        ``,
+      );
+      for (const binding of bindings) {
+        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"
+            ? "int"
+            : fieldKind === "bool"
+              ? "bool"
+              : "Object?";
+        const typeName = `${aggregateName}${cap(camel(binding.field))}Conflict`;
+        const evolutionTypeName = `${typeName}ModelUpdateRequired`;
+        const helper = `_merge${aggregateName}${cap(camel(binding.field))}`;
+        conflictDeclarations.push(
+          `/// Merge every observed business version into one result.`,
+          `final class ${typeName} extends ${pendingClass} {`,
+          `  final ${rowClass} _details;`,
+          `  final ${client} _client;`,
+          `  const ${typeName}._(this._details, this._client);`,
+          `  @override String get aggregateId => _details.aggregateId;`,
+          `  @override String get field => _details.field;`,
+          `  List<SurfacedObservation<${mergedType}>> get versions => List.unmodifiable(`,
+          `      _details.observations.map((item) => SurfacedObservation<${mergedType}>(`,
+          `          value: item.value as ${mergedType}, occurredAt: item.occurredAt, author: item.author)));`,
+          `  Future<void> merge(`,
+          `      ${mergedType} Function(List<SurfacedObservation<${mergedType}>> versions) reconcile,`,
+          `      {Map<String, Object?> rest = const {}}) async {`,
+          `    await _client.${helper}(_details, reconcile(versions), rest: rest);`,
+          `  }`,
+          `}`,
+          ``,
+          `/// This disagreement remains pending because the business model cannot yet compare every`,
+          `/// retained version. Unrelated work continues; update the model's evolution policy to unlock it.`,
+          `final class ${evolutionTypeName} extends ${pendingClass} {`,
+          `  final ${rowClass} _details;`,
+          `  const ${evolutionTypeName}._(this._details);`,
+          `  @override String get aggregateId => _details.aggregateId;`,
+          `  @override String get field => _details.field;`,
+          `  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(
+        `final class ${aggregateClass} {`,
+        `  final ${client} _client;`,
+        `  const ${aggregateClass}._(this._client);`,
+        `  Future<List<${pendingClass}>> pending() async {`,
+        `    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`;
+          return [
+            `        case ${JSON.stringify(binding.field)}:`,
+            `          if (row.status == 'ready') {`,
+            `            decisions.add(${typeName}._(row, _client));`,
+            `          } else if (row.status == 'evolutionRequired') {`,
+            `            decisions.add(${typeName}ModelUpdateRequired._(row));`,
+            `          } else {`,
+            `            throw StateError('Nomos returned an unknown conflict status: \${row.status}');`,
+            `          }`,
+          ];
+        }),
+        `      }`,
+        `    }`,
+        `    return List.unmodifiable(decisions);`,
+        `  }`,
+        `}`,
+        ``,
+      );
+    }
+  }
+
+  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`);
+    }
+    names.add(name);
+    target.push(...memberLines);
+    return true;
+  };
+
+  const sourceTrustAction = (directive: AnyDirective): {
+    prelude: string[];
+    call: string;
+  } => {
+    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)},`);
+    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);`,
+        `    await _client._offer(`,
+        `      ${JSON.stringify(trust.viaDirectiveId)},`,
+        `      {`,
+        ...copied,
+        `        ${JSON.stringify(trust.genesisField)}: NmsInternalSourceTrust.genesis(sourceIdentity),`,
+        `        ${JSON.stringify(trust.keyHashesField)}: [NmsInternalSourceTrust.keyHash(sourceIdentity)],`,
+        `      },`,
+        `    );`,
+      ],
+      call: `_client.${method}(facts, attestations: [sourceEntry])`,
+    };
+  };
+
+  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) => [
+          `          NmsInternalInvitationPolicy(`,
+          `            domain: ${JSON.stringify(domain)},`,
+          `            domainHash: _client.domainHash,`,
+          `            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(),
+        `        ],`,
+        `      );`,
+        ``,
+    );
+    for (const [index, policy] of sharingPolicies.entries()) {
+      const pendingKey = policy.pending.key[0]!;
+      const pendingMethod = member(policy.pending.id);
+      const person = sharingOrderValue(policy, policy.person, "wire");
+      const role = sharingOrderValue(policy, policy.role, "wire");
+      const scope = sharingOrderValue(policy, policy.scope, "wire");
+      const delivered = policy.delivered.flatMap((receipt) => [
+        `      if (${sharingReceiptCondition(policy, receipt)}) {`,
+        `        await _client._offer(`,
+        `          ${JSON.stringify(receipt.records.id)},`,
+        `          <String, Object?>{`,
+        ...sharingReceiptPayload(policy, receipt, false),
+        `          },`,
+        `        );`,
+        `        continue;`,
+        `      }`,
+      ]);
+      const refused = policy.refused.flatMap((receipt) => [
+        `      if (${sharingReceiptCondition(policy, receipt)}) {`,
+        `        await _client._offer(`,
+        `          ${JSON.stringify(receipt.records.id)},`,
+        `          <String, Object?>{`,
+        ...sharingReceiptPayload(policy, receipt, true),
+        `          },`,
+        `        );`,
+        `        continue;`,
+        `      }`,
+      ]);
+      appLines.push(
+        `  Future<void>? _nmsWorkspaceSharingDrain${index};`,
+        `  StreamSubscription<Object?>? _nmsWorkspaceSharingSync${index};`,
+        `  bool _nmsWorkspaceSharingNeedsRetry${index} = false;`,
+        ``,
+        `  Future<void> _nmsStartWorkspaceSharing${index}() async {`,
+        `    await _nmsDrainWorkspaceSharing${index}();`,
+        `    _nmsWorkspaceSharingSync${index} ??= _client.bridge.syncStatus.map<Object?>((status) {`,
+        `      if (_nmsWorkspaceSharingDrain${index} == null &&`,
+        `          (status.phase == SyncPhase.offline || status.phase == SyncPhase.error || status.behind > 0)) {`,
+        `        _nmsWorkspaceSharingNeedsRetry${index} = true;`,
+        `      } else if (status.phase == SyncPhase.idle && _nmsWorkspaceSharingNeedsRetry${index}) {`,
+        `        _nmsWorkspaceSharingNeedsRetry${index} = false;`,
+        `        unawaited(_nmsDrainWorkspaceSharing${index}());`,
+        `      }`,
+        `      return status;`,
+        `    }).listen((_) {});`,
+        `  }`,
+        ``,
+        `  Future<void> _nmsDrainWorkspaceSharing${index}() {`,
+        `    final active = _nmsWorkspaceSharingDrain${index};`,
+        `    if (active != null) return active;`,
+        `    final started = _nmsDrainWorkspaceSharingOnce${index}();`,
+        `    _nmsWorkspaceSharingDrain${index} = started;`,
+        `    return started.whenComplete(() {`,
+        `      if (identical(_nmsWorkspaceSharingDrain${index}, started)) {`,
+        `        _nmsWorkspaceSharingDrain${index} = null;`,
+        `      }`,
+        `    });`,
+        `  }`,
+        ``,
+        `  Future<void> _nmsDrainWorkspaceSharingOnce${index}() async {`,
+        `    final orders = await _client.${pendingMethod}(`,
+        `      ${member(pendingKey)}: ${JSON.stringify(policy.pendingValue)},`,
+        `    );`,
+        `    for (final order in orders) {`,
+        `      late final ApplicationShareResult share;`,
+        `      try {`,
+        `        share = await NmsInternalApplicationHost.shareWith(`,
+        `          _client.bridge, person: ${person}, role: ${role}, scope: ${scope}, identity: _client.actor,`,
+        `        );`,
+        `      } catch (_) {`,
+        `        continue;`,
+        `      }`,
+        `      if (share.awaitingRecipient) continue;`,
+        `      if (share.delivered) {`,
+        ...delivered,
+        `        throw StateError('No delivered receipt matches ${policy.orders.id} \${NmsInternalNomosRefs.id(order.ref)}');`,
+        `      }`,
+        ...refused,
+        `      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}();`),
+      `  }`,
+      ``,
+      `  Future<void> _nmsDrainWorkspaceSharing() async {`,
+      ...sharingPolicies.map((_policy, index) => `    await _nmsDrainWorkspaceSharing${index}();`),
+      `  }`,
+      ``,
+    );
+  }
+
+  const sharingInitiatorIds = new Set(
+    sharingPolicies.flatMap((policy) => policy.initiatedBy.map((intent) => intent.id)),
+  );
+  const afterBusinessWrite = (directive: AnyDirective): string[] =>
+    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."
+      : "One business action; every consequence commits atomically.";
+  };
+
+  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;
+    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
+      // child so tenant code gets navigation/read helpers alongside the root
+      // intent, without reintroducing a collection-shaped write method.
+      if (!collectionLines.has(birth.aggregateId)) {
+        collectionLines.set(birth.aggregateId, []);
+        collectionMembers.set(birth.aggregateId, new Set());
+      }
+      const owner = packageDomains[birth.aggregateId];
+      const targetDomain = owner?.domain ?? domain;
+      const targetFile = owner?.name ?? mod.name;
+      const targetApplication = dartApplicationClassName(targetDomain);
+      const opener = `nomosInternalOpen${targetApplication}`;
+      if (targetFile !== mod.name) {
+        addSibling(`${targetFile}.application.dart`, targetApplication);
+        addSibling(`${targetFile}.application.dart`, opener);
+      }
+      const businessBirthIntent = isBusinessIntent(directive);
+      if (businessBirthIntent) {
+        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.`,
+          `  /// 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 {`,
+          `    final reference = await _client.${method}(facts);`,
+          `    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 {`,
+          `    final reference = await _client.birth(facts);`,
+          `    return ${opener}(_client.bridge, reference, _client.actor);`,
+          `  }`,
+          ``,
+        ]);
+      }
+      if (opts.supportImport === "package") {
+        usesWorkspaceName = true;
+        const rootAggregate = aggregates.get(birth.aggregateId);
+        const rootModel = rootAggregate === undefined
+          ? `${concreteClassName(birth.aggregateId)}ReadModel`
+          : readModelClassName(rootAggregate.id);
+        const rootType = concreteClassName(birth.aggregateId);
+        const rootCollection = member(plural(rootAggregate === undefined
+          ? birth.aggregateId
+          : concreteClassName(rootAggregate.id)));
+        addCollectionMember(birth.aggregateId, "open", [
+          `  /// Open the ${birth.aggregateId} whose ${birth.keyField} is [key].`,
+          `  Future<${targetApplication}> open(String key) => ${opener}(`,
+          `    _client.bridge,`,
+          `    NmsInternalNomosRefs.create<${rootType}>(`,
+          `      workspace: deriveWorkspaceName(${JSON.stringify(birth.namespace)}, key),`,
+          `      type: ${JSON.stringify(birth.aggregateId)},`,
+          `      id: ${JSON.stringify(birth.rootId)},`,
+          `    ),`,
+          `    _client.actor,`,
+          `  );`,
+          ``,
+        ]);
+        addCollectionMember(birth.aggregateId, "mine", [
+          `  /// The ${birth.aggregateId} lives founded by the signed-in person.`,
+          `  /// Nomos follows its private birth records and returns business records only.`,
+          `  Future<List<${rootModel}>> mine() async {`,
+          `    final principal = _client.actor;`,
+          `    if (principal == null || principal.trim().isEmpty) {`,
+          `      throw StateError('The signed-in person is not available.');`,
+          `    }`,
+          `    final births = await _client.bridge.query(`,
+          `      'birthRecordsByPrincipal',`,
+          `      {'principal': principal},`,
+          `    );`,
+          `    final records = <${rootModel}>[];`,
+          `    for (final row in births) {`,
+          `      final raw = row['data'];`,
+          `      if (raw is! Map) continue;`,
+          `      final child = (raw['child'] ?? '').toString();`,
+          `      if (!child.startsWith(${JSON.stringify(`${birth.namespace}-`)})) continue;`,
+          `      final application = await ${opener}(`,
+          `        _client.bridge,`,
+          `        NmsInternalNomosRefs.create<${rootType}>(workspace: child, type: ${JSON.stringify(birth.aggregateId)}, id: ${JSON.stringify(birth.rootId)}),`,
+          `        _client.actor,`,
+          `      );`,
+          `      final record = await application.${rootCollection}.find(`,
+          `        NmsInternalNomosRefs.create<${rootType}>(workspace: child, type: ${JSON.stringify(birth.aggregateId)}, id: ${JSON.stringify(birth.rootId)}),`,
+          `      );`,
+          `      if (record != null) records.add(record);`,
+          `    }`,
+          `    return records;`,
+          `  }`,
+          ``,
+          `  /// React when this person's set of ${birth.aggregateId} lives changes.`,
+          `  Stream<List<${rootModel}>> watchMine() {`,
+          `    final principal = _client.actor;`,
+          `    if (principal == null || principal.trim().isEmpty) {`,
+          `      throw StateError('The signed-in person is not available.');`,
+          `    }`,
+          `    return _client.bridge`,
+          `        .watch('birthRecordsByPrincipal', {'principal': principal})`,
+          `        .asyncMap((_) => mine());`,
+          `  }`,
+          ``,
+          `  /// Every ${birth.aggregateId} the signed-in person can use, whether founded or shared.`,
+          `  /// Nomos follows custody and authority records privately and returns business records only.`,
+          `  Future<List<${rootModel}>> available() async {`,
+          `    final records = <${rootModel}>[...await mine()];`,
+          `    final seen = <String>{};`,
+          `    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 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}-`)}) ||`,
+          `          object != 'workspace:self' ||`,
+          `          prunedAt.isNotEmpty ||`,
+          `          !seen.add(workspace)) continue;`,
+          `      final application = await ${opener}(`,
+          `        _client.bridge,`,
+          `        NmsInternalNomosRefs.create<${rootType}>(workspace: workspace, type: ${JSON.stringify(birth.aggregateId)}, id: ${JSON.stringify(birth.rootId)}),`,
+          `        _client.actor,`,
+          `      );`,
+          `      final record = await application.${rootCollection}.find(`,
+          `        NmsInternalNomosRefs.create<${rootType}>(workspace: workspace, type: ${JSON.stringify(birth.aggregateId)}, id: ${JSON.stringify(birth.rootId)}),`,
+          `      );`,
+          `      if (record != null) records.add(record);`,
+          `    }`,
+          `    return records;`,
+          `  }`,
+          ``,
+          `  /// 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());`,
+          ``,
+          `  /// Continue working in the business application that produced [record].`,
+          `  Future<${targetApplication}> applicationOf(${rootModel} record) {`,
+          `    final origin = NmsInternalRecordOrigins.require(record);`,
+          `    return ${opener}(`,
+          `      _client.bridge,`,
+          `      NmsInternalNomosRefs.create<${rootType}>(workspace: origin.workspace, type: ${JSON.stringify(birth.aggregateId)}, id: origin.id),`,
+          `      _client.actor,`,
+          `    );`,
+          `  }`,
+          ``,
+        ]);
+        birthCollectionsWithMine.add(birth.aggregateId);
+      }
+      continue;
+    }
+    // Lowered cross-workspace governance births are framework implementation, never tenant actions.
+    if ((directive as { birthsChild?: boolean }).birthsChild === true) continue;
+
+    const method = member(directive.id);
+    const payload = dartActionInputClassName(directive);
+    const referenceChecks = actionReferenceChecks(directive);
+    const outputs = dartActionOutputs(directive, mod.aggregates);
+    const resultClass = dartActionResultClassName(directive.id);
+    if (outputs.length > 0) {
+      usesAffectedReference = true;
+      usesAffectedReferences ||= outputs.some((output) => output.many);
+      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(", ")}});`,
+        `}`,
+        ``,
+      );
+    }
+    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(", ")})`;
+    if (isBusinessIntent(directive)) {
+      claimApplicationMember(method, `business intent '${directive.id}'`);
+      const sourceTrust = sourceTrustAction(directive);
+      if (resultExpression !== undefined) {
+        appLines.push(
+          `  /// ${cap(camel(directive.id))}. ${businessActionDoc(directive)}`,
+          `  /// Canonical write path: pass business facts here; never mirror this action in application state`,
+          `  /// or call a lower-level client.`,
+          `  Future<${resultClass}> ${method}(${payload} facts) async {`,
+          ...referenceChecks,
+          ...sourceTrust.prelude,
+          `    final change = await ${sourceTrust.call};`,
+          ...afterBusinessWrite(directive),
+          `    return ${resultExpression};`,
+          `  }`,
+          ``,
+        );
+      } else {
+        appLines.push(
+          `  /// ${cap(camel(directive.id))}. ${businessActionDoc(directive)}`,
+          `  /// Canonical write path: pass business facts here; never mirror this action in application state`,
+          `  /// or call a lower-level client.`,
+          `  Future<void> ${method}(${payload} facts) async {`,
+          ...referenceChecks,
+          ...sourceTrust.prelude,
+          `    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};`,
+          `  }`,
+          ``,
+        ],
+      );
+    } else {
+      addCollectionMember(directive.aggregateId, method, [
+        `  /// ${cap(camel(directive.id))}.`,
+        `  Future<void> ${method}(${payload} facts) async {`,
+        ...referenceChecks,
+        ...sourceTrust.prelude,
+        `    await ${sourceTrust.call};`,
+        `  }`,
+        ``,
+      ]);
+    }
+  }
+
+  const publicQueries = ((mod.queries ?? []) as QueryDecl[]).filter(
+    (candidate) =>
+      !isFrameworkQuery(candidate) &&
+      (candidate as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
+  );
+  const signedInSubjectKey = (query: QueryDecl): string | undefined => {
+    if (query.key.length !== 1) return undefined;
+    const key = query.key[0];
+    if (key === undefined) return undefined;
+    return key === "subject" || key.endsWith("Subject") ? key : undefined;
+  };
+  const mineQueriesByAggregate = new Map<string, number>();
+  for (const query of publicQueries) {
+    if (signedInSubjectKey(query) !== undefined) {
+      mineQueriesByAggregate.set(
+        query.returns,
+        (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 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});`,
+      ``,
+    ]);
+    const subjectKey = signedInSubjectKey(query);
+    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()}`;
+      addCollectionMember(query.returns, mineMethod, [
+        `  /// ${cap(camel(query.returns))} records ${relationship} the signed-in person.`,
+        `  Future<List<${model}>> ${mineMethod}() {`,
+        `    final subject = _client.actor;`,
+        `    if (subject == null || subject.trim().isEmpty) {`,
+        `      throw StateError('The signed-in person is not available.');`,
+        `    }`,
+        `    return _client.${method}(${subjectParam}: subject);`,
+        `  }`,
+        ``,
+        `  Stream<List<${model}>> ${watchMineMethod}() {`,
+        `    final subject = _client.actor;`,
+        `    if (subject == null || subject.trim().isEmpty) {`,
+        `      throw StateError('The signed-in person is not available.');`,
+        `    }`,
+        `    return _client.watch${cap(camel(query.id))}(${subjectParam}: subject);`,
+        `  }`,
+        ``,
+      ]);
+    }
+  }
+
+  // Reference traversal is business navigation. Same-domain, sibling-domain and
+  // cross-workspace references all resolve through the bound application; the
+  // private client/session/reader objects never become tenant parameters.
+  for (const aggregate of mod.aggregates.filter(
+    (candidate) =>
+      !isFrameworkAggregate(candidate) &&
+      (candidate as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
+  )) {
+    const sourceModel = readModelClassName(aggregate.id);
+    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;
+    });
+    for (const [fieldName, field] of Object.entries(aggregate.fields) as [string, Field][]) {
+      const foreign = field.foreignRef;
+      if (field.kind !== "ref") continue;
+      if (foreign === undefined) {
+        const targetAggregateId = field.refAggregateId;
+        if (targetAggregateId === undefined) continue;
+        const sourceFieldMember = member(fieldName);
+        const stem = sourceFieldMember.endsWith("Id")
+          ? sourceFieldMember.slice(0, -2)
+          : `${sourceFieldMember}Ref`;
+        const method = member(stem);
+        const memberNullable = field.isFromBirth !== true;
+        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`);
+          addCollectionMember(aggregate.id, method, [
+            `  /// Resolve [record]'s ${fieldName} inside this business application.`,
+            `  Future<${targetModel}?> ${method}(${sourceModel} record) async {`,
+            ...(memberNullable
+              ? [
+                  `    final id = record.${sourceFieldMember};`,
+                  `    if (id == null) return null;`,
+                  `    final rows = await _client.${targetById}(NmsInternalNomosRefs.id(id));`,
+                ]
+              : [`    final rows = await _client.${targetById}(NmsInternalNomosRefs.id(record.${sourceFieldMember}));`]),
+            `    return rows.isEmpty ? null : rows.first;`,
+            `  }`,
+            ``,
+          ]);
+          continue;
+        }
+
+        const owner = packageDomains[targetAggregateId];
+        if (owner === undefined) continue;
+        const targetModel = readModelClassName(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) {
+          explicitTypeImportUris.add(typeImportUriFor(owner.name));
+        }
+        addSibling(`${owner.name}.application.dart`, targetApplication);
+        addSibling(`${owner.name}.application.dart`, opener);
+        addCollectionMember(aggregate.id, method, [
+          `  /// Resolve [record]'s ${fieldName} through its sibling business application.`,
+          `  Future<${targetModel}?> ${method}(${sourceModel} record) async {`,
+          ...(memberNullable
+            ? [
+                `    final id = record.${sourceFieldMember};`,
+                `    if (id == null) return null;`,
+                `    final application = await ${opener}(`,
+                `      _client.bridge,`,
+                `      id,`,
+                `      _client.actor,`,
+                `    );`,
+                `    return application.${targetCollection}.find(`,
+                `      id,`,
+                `    );`,
+              ]
+            : [
+                `    final id = record.${sourceFieldMember};`,
+                `    final application = await ${opener}(`,
+                `      _client.bridge,`,
+                `      id,`,
+                `      _client.actor,`,
+                `    );`,
+                `    return application.${targetCollection}.find(`,
+                `      id,`,
+                `    );`,
+              ]),
+          `  }`,
+          ``,
+        ]);
+        const applicationMethod = member(`${stem}Application`);
+        addCollectionMember(aggregate.id, applicationMethod, [
+          `  /// Continue in the sibling business application containing [record]'s ${fieldName}.`,
+          `  Future<${targetApplication}?> ${applicationMethod}(${sourceModel} record) {`,
+          ...(memberNullable
+            ? [
+                `    final id = record.${sourceFieldMember};`,
+                `    if (id == null) return Future<${targetApplication}?>.value(null);`,
+                `    return ${opener}(`,
+                `      _client.bridge,`,
+                `      id,`,
+                `      _client.actor,`,
+                `    );`,
+              ]
+            : [
+                `    final id = record.${sourceFieldMember};`,
+                `    return ${opener}(`,
+                `      _client.bridge,`,
+                `      id,`,
+                `      _client.actor,`,
+                `    );`,
+              ]),
+          `  }`,
+          ``,
+        ]);
+        continue;
+      }
+      const target = foreign.targetIsContract === true
+        ? contractTypeName(foreign.targetAggregateId)
+        : concreteClassName(foreign.targetAggregateId);
+      const fieldMember = member(fieldName);
+      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.`,
+        `  Future<${target}?> ${method}(${sourceModel} record) async {`,
+        `    final reference = record.${fieldMember};`,
+        `    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));`,
+        `  }`,
+        ``,
+      ]);
+      const targetOwner = packageDomains[foreign.targetAggregateId] ??
+        (foreign.targetDomain === undefined
+          ? undefined
+          : Object.values(packageDomains).find(
+              (candidate) => candidate.domain === foreign.targetDomain,
+            ));
+      if (targetOwner !== undefined && targetOwner.domain !== domain) {
+        const targetApplication = dartApplicationClassName(targetOwner.domain);
+        const opener = `nomosInternalOpen${targetApplication}`;
+        const applicationMethod = member(`${stem}ApplicationOf`);
+        addSibling(`${targetOwner.name}.application.dart`, targetApplication);
+        addSibling(`${targetOwner.name}.application.dart`, opener);
+        addCollectionMember(aggregate.id, applicationMethod, [
+          `  /// Open the business application containing [record]'s ${fieldName}.`,
+          `  Future<${targetApplication}?> ${applicationMethod}(${sourceModel} record) {`,
+          `    final reference = record.${fieldMember};`,
+          `    if (reference == null) return Future<${targetApplication}?>.value(null);`,
+          `    return ${opener}(`,
+          `      _client.bridge,`,
+          `      reference.ref,`,
+          `      _client.actor,`,
+          `    );`,
+          `  }`,
+          ``,
+        ]);
+      }
+    }
+  }
+
+  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)});`]);
+  }
+  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)});`]);
+  }
+
+  for (const aggregate of mod.aggregates) {
+    if ((aggregate as { businessBirthInternal?: unknown }).businessBirthInternal === true) continue;
+    if (isFrameworkAggregate(aggregate)) continue;
+    const concrete = concreteClassName(aggregate.id);
+    const model = readModelClassName(aggregate.id);
+    const stem = lcFirst(camel(concrete));
+    const Cap = cap(camel(concrete));
+    const aggregateRefType = `NomosRef<${concrete}>`;
+    const clientList = safe(`list${Cap}s`);
+    addCollectionMember(aggregate.id, "fromAddress", [
+      `  /// Recover a typed ${concrete} reference from its stable public address.`,
+      `  ///`,
+      `  /// This creates an address, not authority. [find], [watchOne] and business actions`,
+      `  /// 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)}, '');`,
+      `    return reference;`,
+      `  }`,
+      ``,
+    ]);
+    addCollectionMember(aggregate.id, "find", [
+      `  Future<${model}?> find(${aggregateRefType} reference) async {`,
+      `    _nmsRequireReference(reference, ${JSON.stringify(aggregate.id)}, '');`,
+      `    final targetWorkspace = NmsInternalNomosRefs.workspace(reference);`,
+      `    final currentWorkspace = _client.session?.workspace ?? '';`,
+      `    if (currentWorkspace.isNotEmpty && targetWorkspace != currentWorkspace) {`,
+      `      final application = await nomosInternalOpen${application}(`,
+      `        _client.bridge, reference, _client.actor,`,
+      `      );`,
+      `      return application.${member(plural(concrete))}.find(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)}, '');`,
+      `    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),`,
+      `      );`,
+      `    }`,
+      `    return _client.watch${Cap}ById(NmsInternalNomosRefs.id(reference))`,
+      `        .map((matches) => matches.isEmpty ? null : matches.single);`,
+      `  }`,
+      ``,
+    ]);
+    addCollectionMember(aggregate.id, "all", [
+      `  Future<List<${model}>> all() => _client.${clientList}();`,
+      ``,
+    ]);
+    addCollectionMember(aggregate.id, "watchAll", [
+      `  Stream<List<${model}>> watchAll() => _client.watchAll${Cap}s();`,
+      ``,
+    ]);
+  }
+
+  const collections: string[] = [];
+  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 property = member(plural(concrete));
+    claimApplicationMember(property, `aggregate collection '${aggregateId}'`);
+    appLines.push(`  final ${collection} ${property};`);
+    initializers.push(`${property} = ${collection}._(client)`);
+    collections.push(
+      `/// The canonical generated surface for ${concrete} records and navigation.`,
+      `///`,
+      `/// Use these records, watches and references directly. Business actions that can change`,
+      `/// one or many records live on [${application}]; never wrap or mirror either surface in`,
+      `/// a repository or parallel application state.`,
+      `final class ${collection} {`,
+      `  final ${client} _client;`,
+      `  const ${collection}._(this._client);`,
+      ``,
+      ...members,
+      `}`,
+      ``,
+    );
+  }
+
+  const imports = [...siblingImports.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .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 applicationInitializers = [
+    "_client = client",
+    ...(tenantRoot ? ["currentUser = currentUser"] : []),
+    `activity = ${activity}._(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" : ""};`,
+    ...(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;`]
+            : []),
+          ...(opts.flutterHost === true && tenantRoot
+            ? [`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 '${typesImport}';`,
+    ...[...explicitTypeImportUris].sort().map((uri) => `import '${uri}';`),
+    `import '${mod.name}.client.dart' show ${client};`,
+    ...imports,
+    ``,
+    ...(tenantRoot
+      ? [
+          `/// The canonical stateful entry point for this business domain.`,
+        ]
+      : [
+          `/// A business domain handle owned by the generated package application.`,
+        ]),
+    `///`,
+    `/// Use its business actions, records, watches, status and decisions directly. Nomos owns`,
+    `/// persistence, synchronization, access delivery and recovery underneath this object;`,
+    `/// do not create a parallel repository, runtime host, session, or application-state copy.`,
+    ...(tenantRoot
+      ? [
+          `///`,
+          `/// Canonical bootstrap:`,
+          "/// ```dart",
+          `/// return ${application}.nomosWidget(`,
+          `///   cloud: cloud,`,
+          `///   application: '${domain}',`,
+          `///   signIn: signIn,`,
+          `///   builder: (context, application) => MyBusinessUi(application: application),`,
+          `/// );`,
+          "/// ```",
+          `/// Pass that same [${application}] down. It is the application state.`,
+        ]
+      : [
+          `///`,
+          `/// Reach this object through the generated package application. Do not mount,`,
+          `/// provide, cache or reconstruct it as an independent application root.`,
+        ]),
+    `final class ${application} {`,
+    `  final ${client} _client;`,
+    ...(tenantRoot ? [`  final User currentUser;`] : []),
+    `  final ${activity} activity;`,
+    ...appLines,
+    `  ${application}._(${client} client${tenantRoot ? ", User currentUser" : ""}) : ${applicationInitializers.join(", ")};`,
+    ...(opts.flutterHost === true && tenantRoot
+      ? [
+          ``,
+          `  /// Current durability and convergence in product language.`,
+          `  ApplicationStatus get currentStatus => NmsInternalApplicationHost.currentStatus(_client.bridge);`,
+          ``,
+          `  /// React whenever this application saves, receives work, goes offline or needs attention.`,
+          `  Stream<ApplicationStatus> watchStatus() => NmsInternalApplicationHost.watchStatus(_client.bridge);`,
+          ``,
+          `  /// Mount the one application at the UI boundary and pass [application] down.`,
+          `  ///`,
+          `  /// This is the only application bootstrap tenant code should own.`,
+          `  ///`,
+          `  /// The object supplied to [builder] is the application state. Keep it as the only`,
+          `  /// business-state dependency; do not recreate its records in providers, repositories or caches.`,
+          `  static Widget nomosWidget({`,
+          `    Key? key,`,
+          `    required String cloud,`,
+          `    required String application,`,
+          `    required ApplicationSignIn signIn,`,
+          `    required Widget Function(BuildContext context, ${application} application) builder,`,
+          `    Widget Function(BuildContext context)? loadingBuilder,`,
+          `    Widget Function(BuildContext context, Object error, VoidCallback retry)? errorBuilder,`,
+          `  }) => NmsInternalApplicationHost.home<${application}>(`,
+          `    key: key, cloud: cloud, application: application, signIn: signIn,`,
+          `    bind: nomosInternalBind${application}, builder: builder,`,
+          `    loadingBuilder: loadingBuilder, errorBuilder: errorBuilder,`,
+          `  );`,
+        ]
+      : []),
+    `}`,
+    ``,
+    `/// The verified business history 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);`,
+    ``,
+    `  Stream<List<ActivityEvent>> watchAll() => _client.watchActivity();`,
+    `}`,
+    ``,
+    ...actionResultDeclarations,
+    ...collections,
+    ...conflictDeclarations,
+    `bool _nmsReferenceTypeMatches(String actual, String expected) =>`,
+    `    actual == expected || actual.endsWith('.\$expected');`,
+    ``,
+    `void _nmsRequireReference<T>(NomosRef<T> reference, String expectedType, String workspace) {`,
+    `  if (!_nmsReferenceTypeMatches(NmsInternalNomosRefs.type(reference), expectedType)) {`,
+    `    throw ArgumentError.value(reference, 'reference', 'Expected a reference to \$expectedType');`,
+    `  }`,
+    `  if (NmsInternalNomosRefs.workspace(reference).isEmpty) {`,
+    `    throw ArgumentError.value(reference, 'reference', 'A business reference must carry its workspace');`,
+    `  }`,
+    `  if (workspace.isNotEmpty && NmsInternalNomosRefs.workspace(reference) != workspace) {`,
+    `    throw ArgumentError.value(reference, 'reference', 'This reference belongs to a different business workspace');`,
+    `  }`,
+    `}`,
+    ``,
+    ...(usesAffectedReference
+      ? [
+          `NomosRef<T> _nmsAffectedReference<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 one affected \$expectedType record, received \${matches.length}');`,
+          `  }`,
+          `  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) {`,
+                `  final matches = change.affected`,
+                `      .where((affected) => _nmsReferenceTypeMatches(affected.type, expectedType))`,
+                `      .toList(growable: false);`,
+                `  return matches.map((affected) {`,
+                `    final workspace = affected.workspace.isNotEmpty ? affected.workspace : change.workspace;`,
+                `    if (workspace.isEmpty) {`,
+                `      throw StateError('An affected record did not carry its business workspace');`,
+                `    }`,
+                `    return NmsInternalNomosRefs.create<T>(workspace: workspace, type: affected.type, id: affected.id);`,
+                `  }).toList(growable: false);`,
+                `}`,
+                ``,
+              ]
+            : []),
+        ]
+      : []),
+    ...(opts.flutterHost === true
+      ? [
+          `Future<${application}> nomosInternalBind${application}(`,
+          `    NomosSession session, NmsInternalApplicationUserBinding user) async {`,
+          `  final application = ${application}._(`,
+          `    await ${client}.bind(session, actor: user.nmsInternalActor)${tenantRoot ? "," : ""}`,
+          ...(tenantRoot
+            ? [`    NmsInternalUsers.create(identityId: user.nmsInternalIdentityId, identityAddress: user.nmsInternalIdentityAddress),`]
+            : []),
+          `  );`,
+        ]
+      : [
+          `Future<${application}> nomosInternalBind${application}(NomosSession session, String? actor) async {`,
+          `  final application = ${application}._(await ${client}.bind(session, actor: actor));`,
+        ]),
+    ...(sharingPolicies.length > 0 ? [`  await application._nmsStartWorkspaceSharing();`] : []),
+    `  return application;`,
+    `}`,
+    ``,
+    `Future<${application}> nomosInternalOpen${application}<TAggregate>(`,
+    `    NomosBridge bridge, NomosRef<TAggregate> reference, String? actor) async {`,
+    ...(tenantRoot
+      ? [
+          `  final signedIn = actor?.trim() ?? '';`,
+          `  if (signedIn.isEmpty) throw StateError('Nomos could not identify the signed-in application user.');`,
+          `  final application = ${application}._(`,
+          `    await ${client}.open(bridge, ref: reference, actor: signedIn),`,
+          `    NmsInternalUsers.create(`,
+          `      identityId: nmsInternalReceivingGroupNameOf(signedIn),`,
+          `      identityAddress: 'nomos-identity:\${Uri.encodeComponent(nmsInternalReceivingGroupNameOf(signedIn))}',`,
+          `    ),`,
+          `  );`,
+        ]
+      : [`  final application = ${application}._(await ${client}.open(bridge, ref: reference, actor: actor));`]),
+    ...(sharingPolicies.length > 0 ? [`  await application._nmsStartWorkspaceSharing();`] : []),
+    `  return application;`,
+    `}`,
+    ``,
+  ].join("\n");
+}