@githolon/dsl 0.103.4 → 0.103.6

package/src/codegen_dart_application.ts

@@ -7,7 +7,7 @@ import type { z } from "zod";
 
 import type { AggregateHandle } from "./aggregate.js";
 import type { Directive } from "./directive.js";
-import { isSha256DigestSchema, type Field } from "./fields.js";
+import { isGitObjectIdSchema, isSha256DigestSchema, type Field } from "./fields.js";
 import type { QueryDecl } from "./query.js";
 import type { DomainModule } from "./codegen_dart.js";
 import {
@@ -89,6 +89,7 @@ const TENANT_ROOT_MEMBERS = new Map<string, string>([
   ["currentUser", "the generated signed-in application participant"],
   ["currentStatus", "the generated application status"],
   ["watchStatus", "the generated application status watch"],
+  ["whenCurrent", "the generated application convergence awaitable"],
   ["recipient", "the generated typed recipient boundary"],
   ["createInvitation", "the generated invitation capability"],
   ["redeemInvitation", "the generated invitation redemption"],
@@ -129,6 +130,12 @@ function keyType(aggregate: AggregateHandle | undefined, key: string): string {
   ) {
     return "Sha256Digest";
   }
+  if (
+    field?.kind === "string" &&
+    isGitObjectIdSchema(field.zod as z.ZodTypeAny)
+  ) {
+    return "GitObjectId";
+  }
   return "String";
 }
 
@@ -537,6 +544,17 @@ export function generateDartApplication(
       if (uri.endsWith(`/${name}.dart`) || uri.endsWith(`${name}.dart`))
         return uri;
     }
+    // In layered output the domain types live in the generated TYPES package,
+    // never beside this application library.  A relative fallback here makes
+    // the client package unmountable as soon as a generated application needs
+    // a concrete sibling-domain type (for example a typed NomosRef carried by
+    // a parent access card).  Derive the same public package URI used by the
+    // compiler's explicit-barrel imports; flat output deliberately keeps the
+    // sibling-relative form below.
+    const layeredTypes = opts.typesImportUri?.match(/^package:([^/]+)\//);
+    if (layeredTypes?.[1] !== undefined) {
+      return `package:${layeredTypes[1]}/src/generated/${name}.dart`;
+    }
     return `${name}.dart`;
   };
 
@@ -573,7 +591,11 @@ export function generateDartApplication(
       )
     );
     return specs
-      .filter((spec) => spec.toJson === "ref" && !recordInputIds.has(spec.name))
+      .filter(
+        (spec) =>
+          (spec.toJson === "ref" || spec.toJson === "addressRef") &&
+          !recordInputIds.has(spec.name)
+      )
       .map((spec) => {
         const targetClass =
           spec.dartType.match(/^NomosRef<(.*)>$/)?.[1] ?? "Object?";
@@ -583,7 +605,8 @@ export function generateDartApplication(
             (aggregate) => concreteClassName(aggregate.id) === targetClass
           )?.id ??
           targetClass;
-        const expectedWorkspace = foreignReferenceIds.has(spec.name)
+        const expectedWorkspace =
+          spec.toJson === "addressRef" || foreignReferenceIds.has(spec.name)
           ? "''"
           : "_client.session?.workspace ?? ''";
         const value = `facts.${member(spec.name)}`;
@@ -800,6 +823,31 @@ export function generateDartApplication(
       path
         .split(".")
         .reduce((expr, part) => `${expr}.${member(part)}`, "facts");
+    const foreignInputs = dartForeignReferenceInputs(
+      directive,
+      mod.aggregates
+    );
+    // A generated input collapses a foreign `(workspace, id)` pair into one
+    // NomosRef. Source-trust orchestration must follow that public shape too:
+    // deriving the locator from the typed reference, rather than reaching for
+    // the deliberately removed raw workspace/id fields.
+    const factValue = (path: string): string => {
+      if (!path.includes(".")) {
+        const workspaceOwner = foreignInputs.find(
+          (input) => input.workspaceField === path
+        );
+        if (workspaceOwner !== undefined) {
+          return `NmsInternalNomosRefs.workspace(facts.${member(
+            workspaceOwner.idField
+          )})`;
+        }
+        const reference = foreignInputs.find((input) => input.idField === path);
+        if (reference !== undefined) {
+          return `NmsInternalNomosRefs.id(facts.${member(reference.idField)})`;
+        }
+      }
+      return factPath(path);
+    };
     const trust = directive.businessSourceTrust;
     const method = member(directive.id);
     if (trust === undefined) {
@@ -809,11 +857,11 @@ export function generateDartApplication(
       .sort(([a], [b]) => a.localeCompare(b))
       .map(
         ([target, field]) =>
-          `      ${JSON.stringify(target)}: ${factPath(field)},`
+          `      ${JSON.stringify(target)}: ${factValue(field)},`
       );
     return {
       prelude: [
-        `    final sourceGenesis = await _client.bridge.nomosWorkspaceGenesis(${factPath(
+        `    final sourceGenesis = await _client.bridge.nomosWorkspaceGenesis(${factValue(
           trust.fromPayload
         )});`,
         `    await _client._offer(`,
@@ -1108,6 +1156,13 @@ export function generateDartApplication(
           `    return opened;`,
           `  }`,
           ``,
+          `  /// Open the workspace named by a typed ${rootType} custody reference.`,
+          `  /// The reference supplies identity and routing only; normal authority checks still apply.`,
+          `  Future<${targetApplication}> openReference(NomosRef<${rootType}> reference) {`,
+          `    _nmsRequireReference(reference, ${JSON.stringify(birth.aggregateId)}, '');`,
+          `    return _nmsOpenReference(reference);`,
+          `  }`,
+          ``,
           `  /// Open the ${birth.aggregateId} whose ${birth.keyField} is [key].`,
           `  Future<${targetApplication}> open(String key) => _nmsOpenReference(`,
           `    NmsInternalNomosRefs.create<${rootType}>(`,
@@ -1277,6 +1332,7 @@ export function generateDartApplication(
       actionResultDeclarations.push(
         `/// Every business record affected by ${cap(camel(directive.id))}.`,
         `final class ${resultClass} {`,
+        `  final NomosOperationReceipt receipt;`,
         ...outputs.map((output) =>
           output.many
             ? `  final List<NomosRef<${output.dartType}>> ${output.field};`
@@ -1284,7 +1340,7 @@ export function generateDartApplication(
             ? `  final NomosRef<${output.dartType}>? ${output.field};`
             : `  final NomosRef<${output.dartType}> ${output.field};`
         ),
-        `  const ${resultClass}({${outputs
+        `  const ${resultClass}({required this.receipt, ${outputs
           .map((output) => `required this.${output.field}`)
           .join(", ")}});`,
         `}`,
@@ -1294,7 +1350,7 @@ export function generateDartApplication(
     const resultExpression =
       outputs.length === 0
         ? undefined
-        : `${resultClass}(${outputs
+        : `${resultClass}(receipt: change.receipt, ${outputs
             .map((output) =>
               output.many
                 ? `${output.field}: _nmsAffectedReferences<${
@@ -1331,11 +1387,12 @@ export function generateDartApplication(
           `  /// ${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 {`,
+          `  Future<NomosOperationReceipt> ${method}(${payload} facts) async {`,
           ...referenceChecks,
           ...sourceTrust.prelude,
-          `    await ${sourceTrust.call};`,
+          `    final change = await ${sourceTrust.call};`,
           ...afterBusinessWrite(directive),
+          `    return change.receipt;`,
           `  }`,
           ``
         );
@@ -1359,10 +1416,11 @@ export function generateDartApplication(
     } else {
       addCollectionMember(directive.aggregateId, method, [
         `  /// ${cap(camel(directive.id))}.`,
-        `  Future<void> ${method}(${payload} facts) async {`,
+        `  Future<NomosOperationReceipt> ${method}(${payload} facts) async {`,
         ...referenceChecks,
         ...sourceTrust.prelude,
-        `    await ${sourceTrust.call};`,
+        `    final change = await ${sourceTrust.call};`,
+        `    return change.receipt;`,
         `  }`,
         ``,
       ]);
@@ -1834,10 +1892,16 @@ export function generateDartApplication(
       ``,
     ]);
     addCollectionMember(aggregate.id, "all", [
+      `  @Deprecated(${JSON.stringify(
+        `Reads every ${concrete} in the workspace. Prefer find(reference) or a declared keyed query; use all() only for an intentional whole-workspace operation.`
+      )})`,
       `  Future<List<${model}>> all() => _client.${clientList}();`,
       ``,
     ]);
     addCollectionMember(aggregate.id, "watchAll", [
+      `  @Deprecated(${JSON.stringify(
+        `Watches every ${concrete} in the workspace. Prefer watchOne(reference) or a declared keyed watch; use watchAll() only for an intentional whole-workspace operation.`
+      )})`,
       `  Stream<List<${model}>> watchAll() => _client.watchAll${Cap}s();`,
       ``,
     ]);
@@ -1901,7 +1965,7 @@ export function generateDartApplication(
     ...(sharingPolicies.length > 0
       ? [`import 'dart:async' show StreamSubscription, unawaited;`]
       : []),
-    `import '${runtimeImport}' show NmsInternalForeignRefs, NmsInternalNomosRefs, NmsInternalRecordOrigins, NomosBridge, NomosOfferOutcome, NomosRef, NomosSession${
+    `import '${runtimeImport}' show NmsInternalForeignRefs, NmsInternalNomosRefs, NmsInternalRecordOrigins, NomosBridge, NomosOfferOutcome, NomosOperationReceipt, NomosRef, NomosSession${
       usesWorkspaceName ? ", deriveWorkspaceName" : ""
     }${
       sharingPolicies.length > 0
@@ -1918,15 +1982,17 @@ export function generateDartApplication(
                 `import 'package:nomos_flutter/src/application_share.dart' show ApplicationShareResult;`,
               ]
             : []),
-          ...(opts.flutterHost === true && tenantRoot
+          ...(opts.flutterHost === true
             ? [
-                `import 'package:nomos_flutter/src/application_status.dart' show ApplicationSignIn, ApplicationStatus;`,
+                `import 'package:nomos_flutter/src/application_status.dart' show ${
+                  tenantRoot ? "ApplicationSignIn, " : ""
+                }ApplicationStatus;`,
               ]
             : []),
           `import 'package:nomos_flutter/src/generated_application_host.dart' show ${
-            tenantRoot ? "NomosApplicationStartupState, " : ""
+            tenantRoot ? "ApplicationModelChange, NomosApplicationStartupState, " : ""
           }NmsInternalApplicationUserBinding${
-            tenantRoot || sharingPolicies.length > 0
+            opts.flutterHost === true || sharingPolicies.length > 0
               ? ", NmsInternalApplicationHost"
               : ""
           }${
@@ -1978,14 +2044,25 @@ export function generateDartApplication(
     ``,
     `  /// Prove, adopt or restore the law this application was generated against.`,
     `  NomosModel get model => _client.model;`,
-    ...(opts.flutterHost === true && tenantRoot
+    ...(opts.flutterHost === true
       ? [
           ``,
-          `  /// Current durability and convergence in product language.`,
+          `  /// Current durability and convergence for this workspace in product language.`,
           `  ApplicationStatus get currentStatus => NmsInternalApplicationHost.currentStatus(_client.bridge);`,
           ``,
-          `  /// React whenever this application saves, receives work, goes offline or needs attention.`,
+          `  /// React whenever this workspace saves, receives work, goes offline or needs attention.`,
           `  Stream<ApplicationStatus> watchStatus() => NmsInternalApplicationHost.watchStatus(_client.bridge);`,
+          ``,
+          `  /// Wait until accepted local work is in shared custody and this workspace has caught up.`,
+          `  Future<void> whenCurrent({Duration timeout = const Duration(minutes: 2)}) =>`,
+          `      NmsInternalApplicationHost.whenCurrent(_client.bridge, timeout: timeout);`,
+          ``,
+          `  /// The parent operation which created this workspace during this application run, if any.`,
+          `  NomosOperationReceipt? get creationReceipt => NmsInternalApplicationHost.creationReceipt(_client.bridge);`,
+        ]
+      : []),
+    ...(opts.flutterHost === true && tenantRoot
+      ? [
           ``,
           `  /// Mount the one application at the UI boundary and pass [application] down.`,
           `  ///`,
@@ -2001,12 +2078,16 @@ export function generateDartApplication(
           `    required Widget Function(BuildContext context, ${application} application) builder,`,
           `    Widget Function(BuildContext context)? loadingBuilder,`,
           `    Widget Function(BuildContext context, Object error, VoidCallback retry)? errorBuilder,`,
+          `    ApplicationModelChange? onModelChange,`,
           `    ValueChanged<NomosApplicationStartupState>? onStartupStateChanged,`,
+          `    Duration startupTimeout = const Duration(seconds: 45),`,
           `  }) => NmsInternalApplicationHost.home<${application}>(`,
           `    key: key, cloud: cloud, application: application, signIn: signIn,`,
           `    bind: nomosInternalBind${application}, builder: builder,`,
           `    loadingBuilder: loadingBuilder, errorBuilder: errorBuilder,`,
+          `    onModelChange: onModelChange,`,
           `    onStartupStateChanged: onStartupStateChanged,`,
+          `    startupTimeout: startupTimeout,`,
           `  );`,
         ]
       : []),
@@ -2132,6 +2213,13 @@ export function generateDartApplication(
     ``,
     `Future<${application}> nomosInternalOpen${application}<TAggregate>(`,
     `    NomosBridge bridge, NomosRef<TAggregate> reference, String? actor) async {`,
+    ...(opts.flutterHost === true
+      ? [
+          `  return NmsInternalApplicationHost.nmsInternalOpenReferencedApplication<${application}>(`,
+          `    parent: bridge,`,
+          `    open: () async {`,
+        ]
+      : []),
     ...(tenantRoot
       ? [
           `  final signedIn = actor?.trim() ?? '';`,
@@ -2151,6 +2239,13 @@ export function generateDartApplication(
       ? [`  await application._nmsStartWorkspaceSharing();`]
       : []),
     `  return application;`,
+    ...(opts.flutterHost === true
+      ? [
+          `    },`,
+          `    bridgeOf: (application) => application._client.bridge,`,
+          `  );`,
+        ]
+      : []),
     `}`,
     ``,
   ].join("\n");

package/src/codegen_dart_client.ts

@@ -35,7 +35,7 @@ import {
   OWNED_PREMINTED_RECORDS_PAYLOAD_FIELD,
   type AggregateHandle,
 } from "./aggregate.js";
-import { isSha256DigestSchema, type Field } from "./fields.js";
+import { isGitObjectIdSchema, isSha256DigestSchema, type Field } from "./fields.js";
 import type { Directive } from "./directive.js";
 import type { QueryDecl } from "./query.js";
 import type { DomainModule } from "./codegen_dart.js";
@@ -165,6 +165,9 @@ function dartKeyType(agg: AggregateHandle | undefined, key: string): string {
   if (f?.kind === "string" && isSha256DigestSchema(f.zod as z.ZodTypeAny)) {
     return "Sha256Digest";
   }
+  if (f?.kind === "string" && isGitObjectIdSchema(f.zod as z.ZodTypeAny)) {
+    return "GitObjectId";
+  }
   return "String";
 }
 
@@ -178,6 +181,12 @@ function dartKeyExpr(agg: AggregateHandle | undefined, key: string): string {
   ) {
     return `${param}.value`;
   }
+  if (
+    field?.kind === "string" &&
+    isGitObjectIdSchema(field.zod as z.ZodTypeAny)
+  ) {
+    return `${param}.value`;
+  }
   if (field?.kind !== "ref") return param;
   return field.foreignRef !== undefined
     ? `NmsInternalNomosRefs.id(${param}.ref)`
@@ -210,6 +219,10 @@ function rowToModel(model: string, rowVar: string, workspace = "_ws"): string {
 export interface DartBridgeClientOptions {
   /** Content identity of the built typed USDA closure (`.law.usdz`). */
   readonly domainHash: string;
+  /** Flutter asset key for the compiler-authored USDZ transport. Generated
+   * child openers use it to inherit an accepted parent model through the
+   * child's ordinary author gate. Omit for pure-Dart/vendored clients. */
+  readonly lawAssetKey?: string;
   /** This domain's STRUCTURAL INTERFACE (#72) — directives (payload shapes) + aggregates
    *  (read shapes, sid-keyed). Baked in as JSON so the app can negotiate shape-compatibility
    *  against the workspace's installed offer, NOT by law hash. */
@@ -1602,6 +1615,19 @@ export function generateDartBridgeClient(
       `      differences.add(NomosModelDifference(kind: kind, area: area, action: action, summary: summary));`,
       `    }`,
       `    final evolve = (report?['evolve'] as Map?)?.cast<String, Object?>();`,
+      `    for (final raw in ((evolve?['violations'] as List?) ?? const [])) {`,
+      `      if (raw is! Map) continue;`,
+      `      final violation = raw.cast<String, Object?>();`,
+      `      final rawDomain = violation['domain']?.toString().trim();`,
+      `      final rawDetail = violation['detail']?.toString().trim();`,
+      `      differences.add(NomosModelDifference(`,
+      `        kind: NomosModelDifferenceKind.rules,`,
+      `        area: rawDomain == null || rawDomain.isEmpty ? null : rawDomain,`,
+      `        summary: rawDetail == null || rawDetail.isEmpty`,
+      `            ? 'This model does not declare how to interpret an existing value.'`,
+      `            : rawDetail,`,
+      `      ));`,
+      `    }`,
       `    if (report != null && evolve?['ok'] != true && !differences.any((d) => d.kind == NomosModelDifferenceKind.rules)) {`,
       `      differences.add(const NomosModelDifference(kind: NomosModelDifferenceKind.rules, summary: 'This model does not yet explain how to interpret every existing value.'));`,
       `    }`,
@@ -1629,13 +1655,30 @@ export function generateDartBridgeClient(
       `      return NomosModelAdoption.adopted(`,
       `        summary: 'Nomos proved this model against current history and made it active.', review: review);`,
       `    }`,
+      ...(opts.lawAssetKey === undefined
+        ? []
+        : [
+            `    if (stage == 'staging-required') {`,
+            `      return NomosModelAdoption.needsStaging(`,
+            `        summary: 'This workspace is running an older model. Stage this generated USDA candidate through the signed workspace gate before reviewing it.',`,
+            `        review: review,`,
+            `        stage: () async {`,
+            `          await _stageGeneratedModel();`,
+            `          return _adoptGeneratedModel();`,
+            `        },`,
+            `      );`,
+            `    }`,
+          ]),
       `    if (stage == 'acceptance') {`,
       `      return NomosModelAdoption.needsDecision(`,
       `        summary: 'This model would change prior business outcomes. Review the differences and record why that is intended.',`,
       `        review: review, accept: (reason) => _adoptGeneratedModel(reason));`,
       `    }`,
       `    final evolve = (report?['evolve'] as Map?)?.cast<String, Object?>();`,
-      `    final summary = stage == 'identity'`,
+      `    final rawError = raw['error']?.toString().trim();`,
+      `    final summary = rawError != null && rawError.isNotEmpty`,
+      `        ? rawError`,
+      `        : stage == 'identity'`,
       `        ? 'Sign in before adopting this model so the decision is accountable.'`,
       `        : report != null && report['sourceVerified'] != true`,
       `            ? 'The current history could not be verified. Nothing changed and the current model remains active.'`,
@@ -1647,6 +1690,20 @@ export function generateDartBridgeClient(
       `    return NomosModelAdoption.blocked(summary: summary, review: review);`,
       `  }`,
       ``,
+      ...(opts.lawAssetKey === undefined
+        ? []
+        : [
+            `  Future<void> _stageGeneratedModel() async {`,
+            `    final archive = await rootBundle.load(${dartStr(opts.lawAssetKey)});`,
+            `    await bridge.nomosInternalStageGeneratedModel(`,
+            `      domain: ${dartStr(domain)},`,
+            `      candidateHash: domainHash,`,
+            `      lawUsdz: archive.buffer.asUint8List(`,
+            `        archive.offsetInBytes, archive.lengthInBytes),`,
+            `    );`,
+            `  }`,
+            ``,
+          ]),
       `  Future<NomosModelRestoration> _restorePreviousGeneratedModel([String? because]) async {`,
       `    final raw = await bridge.nomosFrameworkRestorePreviousGeneratedModel(`,
       `      domain: ${dartStr(
@@ -2159,6 +2216,9 @@ export function generateDartBridgeClient(
       ? [`import 'dart:convert';`, ``]
       : []),
     `import '${supportImport}';`,
+    ...(opts.lawAssetKey !== undefined
+      ? [`import 'package:flutter/services.dart' show rootBundle;`]
+      : []),
     // Layered-packages mode: the sibling types live in their OWN package — one barrel import
     // replaces both the relative types import and the relative framework import.
     ...(opts.typesImportUri !== undefined
@@ -2299,6 +2359,66 @@ export function generateDartBridgeClient(
     `  static Future<${className}> bind(NomosSession session, {String? actor${
       manualEncryptionPresent ? ", NomosKeyStore? keyStore" : ""
     }}) async {`,
+    `    final candidate = ${className}(session, actor: actor${
+      manualEncryptionPresent ? ", keyStore: keyStore" : ""
+    });`,
+    `    Future<void> adoptGeneratedModel() async {`,
+    `      final adoption = await candidate._adoptGeneratedModel();`,
+    `      if (adoption.status == NomosModelAdoptionStatus.adopted) return;`,
+    `      throw DomainClientModelAdoptionRequired(`,
+    `        expectedDomainKey: interface.domain,`,
+    `        expectedDomainHash: interface.expectedDomainHash,`,
+    `        status: adoption.status.name,`,
+    `        summary: adoption.summary,`,
+    `        review: DomainModelReview(`,
+    `          checkedActions: adoption.review.checkedActions,`,
+    `          candidateActions: adoption.review.candidateActions,`,
+    `          sameOutcome: adoption.review.sameOutcome,`,
+    `          differences: [`,
+    `            for (final difference in adoption.review.differences)`,
+    `              DomainModelDifference(`,
+    `                kind: switch (difference.kind) {`,
+    `                  NomosModelDifferenceKind.rules => DomainModelDifferenceKind.rules,`,
+    `                  NomosModelDifferenceKind.outcome => DomainModelDifferenceKind.outcome,`,
+    `                  NomosModelDifferenceKind.evidence => DomainModelDifferenceKind.evidence,`,
+    `                },`,
+    `                area: difference.area,`,
+    `                action: difference.action,`,
+    `                summary: difference.summary,`,
+    `              ),`,
+    `          ],`,
+    `        ),`,
+    ...(opts.lawAssetKey === undefined
+      ? [`        stage: null,`]
+      : [
+          `        stage: adoption.status == NomosModelAdoptionStatus.needsStaging`,
+          `            ? () => candidate._stageGeneratedModel()`,
+          `            : null,`,
+        ]),
+    `        accept: adoption.status == NomosModelAdoptionStatus.needsDecision`,
+    `            ? (reason) async {`,
+    `                final accepted = await adoption.accept(reason);`,
+    `                if (accepted.status != NomosModelAdoptionStatus.adopted) {`,
+    `                  throw StateError(accepted.summary);`,
+    `                }`,
+    `              }`,
+    `            : null,`,
+    `      );`,
+    `    }`,
+    `    try {`,
+    `      await session.assertCompatible(interface);`,
+    `    } on DomainClientSessionMismatch catch (mismatch) {`,
+    `      // A deployed successor is deliberately invisible until the generated candidate proves it`,
+    `      // against this workspace's exact history. Do that before rejecting the candidate for`,
+    `      // expecting its own newer interface; all other bind failures retain their precise cause.`,
+    `      if (!mismatch.canAttemptGeneratedModelAdoption) rethrow;`,
+    `      await adoptGeneratedModel();`,
+    `    }`,
+    `    // Shape compatibility governs readable structure; exact package identity governs`,
+    `    // which plans may author. A plan-only successor must therefore enter the same`,
+    `    // proof-gated lifecycle even when every generated read type remains compatible.`,
+    `    final law = await session.lawStatus(interface.expectedDomainHash);`,
+    `    if (law['drifted'] == true) await adoptGeneratedModel();`,
     `    await session.assertCompatible(interface);`,
     `    // RELEASE COHERENCE: the cloud's kernel must support what this law needs (e.g. a compound-key query`,
     `    // needs 'compoundKeys'). Throws a typed KernelCoherenceError on a stale/mismatched cloud kernel,`,
@@ -2311,9 +2431,7 @@ export function generateDartBridgeClient(
             ownedScope
           )}, domain: ${dartStr(domain)}, domainHash: ${hashConst});`,
         ]),
-    `    return ${className}(session, actor: actor${
-      manualEncryptionPresent ? ", keyStore: keyStore" : ""
-    }).._preflighted = true${
+    `    return candidate.._preflighted = true${
       ownedScope === undefined ? "" : ".._ownedIdentityReady = true"
     };`,
     `  }`,
@@ -2332,9 +2450,34 @@ export function generateDartBridgeClient(
     `      throw ArgumentError('${className}.open: pass a workspace: or ref: — the workspace to open and bind');`,
     `    }`,
     `    final session = await bridge.acquireSession(ws);`,
-    `    return bind(session, actor: actor${
+    ...(opts.lawAssetKey === undefined
+      ? []
+      : [
+          `    final law = await session.lawStatus(${hashConst});`,
+          `    if (law['drifted'] == true) {`,
+          `      if (bridge is! NomosSession) {`,
+          `        throw StateError('Generated child model inheritance needs a bound parent session.');`,
+          `      }`,
+          `      final archive = await rootBundle.load(${dartStr(opts.lawAssetKey)});`,
+          `      await bridge.nomosInternalEnsureGeneratedModelInChild(`,
+          `        childWorkspace: ws,`,
+          `        domain: interface.domain,`,
+          `        candidateHash: ${hashConst},`,
+          `        lawUsdz: archive.buffer.asUint8List(`,
+          `          archive.offsetInBytes, archive.lengthInBytes),`,
+          `      );`,
+          `    }`,
+        ]),
+    `    for (var modelStep = 0; modelStep < 4; modelStep += 1) {`,
+    `      try {`,
+    `        return await bind(session, actor: actor${
       manualEncryptionPresent ? ", keyStore: keyStore" : ""
     });`,
+    `      } on DomainClientModelAdoptionRequired catch (change) {`,
+    `        await session.nomosInternalHandleModelChange(change);`,
+    `      }`,
+    `    }`,
+    `    throw StateError('Generated model lifecycle did not settle after four governed steps.');`,
     `  }`,
     ``,
     `  /// The session workspace this client is bound to (from the [NomosSession] handle, when constructed with`,

package/src/codegen_proof.ts

@@ -326,7 +326,7 @@ function sampleOfZod(
 export function synthesizePayload(
   schema: z.ZodTypeAny,
   where: string,
-  opts?: { voIncludeOptional?: boolean; example?: unknown },
+  opts?: { voIncludeOptional?: boolean; includeOptionalTopLevel?: boolean; example?: unknown },
 ): SynthesizedPayload {
   if (zodKind(schema) !== "object") {
     throw new Error(`codegen-proof: ${where} payload is not a zod object — the proof can only synthesize object payloads`);
@@ -348,8 +348,9 @@ export function synthesizePayload(
   for (const [name, raw] of Object.entries(zodObjectShape(schema))) {
     const f = raw as z.ZodTypeAny;
     const k = zodKind(f);
-    if (k === "optional" || k === "default") continue; // optional → omit
     if (stamped.has(name)) continue; // `…At` → omit; the client stamps it
+    if (k === "default") continue; // defaulted fields exercise their declared default
+    if (k === "optional" && opts?.includeOptionalTopLevel !== true) continue;
     value[name] = sampleOfZod(f, name, where, opts?.voIncludeOptional === true); // path root = the payload field name
   }
   return { value, autoStamped };
@@ -361,11 +362,11 @@ export function synthesizePayload(
 export function synthesizeDirectivePayload(
   directive: Directive<any>,
   where: string,
-  opts?: { voIncludeOptional?: boolean },
+  opts?: { voIncludeOptional?: boolean; includeOptionalTopLevel?: boolean; useDirectiveExample?: boolean },
 ): SynthesizedPayload {
   return synthesizePayload(directive.payloadSchema as z.ZodTypeAny, where, {
     ...opts,
-    ...(directive.payloadExample === undefined
+    ...(directive.payloadExample === undefined || opts?.useDirectiveExample === false
       ? {}
       : { example: directive.payloadExample }),
   });
@@ -701,10 +702,11 @@ function probePlanOpsWithPayload(
 export function probePlanOps(
   dir: Directive<unknown>,
   where: string,
+  opts?: { includeOptionalTopLevel?: boolean; useDirectiveExample?: boolean },
 ): { ops: FieldOp[]; synth: SynthesizedPayload; probePayload: Record<string, unknown> } | undefined {
   let synth: SynthesizedPayload;
   try {
-    synth = synthesizeDirectivePayload(dir, where);
+    synth = synthesizeDirectivePayload(dir, where, opts);
   } catch {
     return undefined;
   }
@@ -3235,9 +3237,14 @@ function generateSealedApplicationProof(
       : { applicationMaxChildWorkspacesPerUser: opts.applicationMaxChildWorkspacesPerUser }),
   });
   const standalone = orderedStandaloneCreates(mod)[0];
-  const businessBirth = primaryLegs.childBirth?.businessAggregateId !== undefined
-    ? primaryLegs.childBirth
-    : undefined;
+  // A home/application domain normally carries an internal receiving-group self-birth before its public
+  // business births. `childBirth` preserves that first leg for backwards-compatible proof metadata, but the
+  // live generated application journey must exercise the first PUBLIC birth from the complete set. Looking
+  // only at `childBirth` made a CO2 proof describe birthEstateWorkspace in its marker while executing an
+  // unrelated AccessibleEstate write, so a broken estate genesis reached AppSim instead of failing compile.
+  const businessBirth = (primaryLegs.childBirths ??
+    (primaryLegs.childBirth === undefined ? [] : [primaryLegs.childBirth]))
+    .find((birth) => birth.businessAggregateId !== undefined);
   const selectedBirthDirective = businessBirth === undefined
     ? undefined
     : (mod.applicationIntents ?? mod.directives).find(
@@ -3351,7 +3358,7 @@ function generateSealedApplicationProof(
 
   if (businessBirth !== undefined) {
     const businessPayload = Object.fromEntries(
-      Object.entries(businessBirth.birthPayload).filter(([field]) => !["principal", "bornAt", "ownerKeyHash", "birthCert"].includes(field)),
+      Object.entries(businessBirth.birthPayload).filter(([field]) => !["principal", "bornAt"].includes(field)),
     );
     out.push(
       `const facts = ${JSON.stringify(businessPayload)};`,

package/src/codegen_provider_dart.ts

@@ -202,6 +202,11 @@ function obligationFromJsonExpr(s: PayloadFieldSpec): string {
         `NmsInternalNomosRefs.create<${target}>(workspace: '', type: '${wireType}', id: ${v} as String)`;
       return s.optional ? `${raw} == null ? null : ${wrap(raw)}` : wrap(raw);
     }
+    case "addressRef": {
+      const target = s.dartType.replace(/^NomosRef<(.*)>$/, "$1");
+      const wrap = (v: string) => `NmsInternalNomosRefs.fromJson<${target}>(${v})`;
+      return s.optional ? `${raw} == null ? null : ${wrap(raw)}` : wrap(raw);
+    }
     case "versionedRef": {
       const target = s.versionedRefTarget as string;
       const series = s.versionedRefSeries as string;