@githolon/dsl 0.103.12 → 0.103.13

package/src/codegen_dart_application.ts

@@ -19,6 +19,8 @@ import {
   introspectPayload,
   readModelClassName,
   registerDartNames,
+  collectDartEnums,
+  dartEnumTypeForField,
 } from "./codegen_dart.js";
 import { dartClientClassName } from "./codegen_dart_client.js";
 import { finishCount } from "./count.js";
@@ -109,7 +111,11 @@ function keyParam(key: string): string {
   return safe(/^[0-9]/.test(cleaned) ? `v${cleaned}` : cleaned);
 }
 
-function keyType(aggregate: AggregateHandle | undefined, key: string): string {
+function keyType(
+  aggregate: AggregateHandle | undefined,
+  key: string,
+  enumDartTypes: ReadonlyMap<string, 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";
@@ -124,6 +130,8 @@ function keyType(aggregate: AggregateHandle | undefined, key: string): string {
     if (field.refAggregateId !== undefined)
       return `NomosRef<${concreteClassName(field.refAggregateId)}>`;
   }
+  const enumType = dartEnumTypeForField(field, enumDartTypes);
+  if (enumType !== undefined) return enumType;
   if (
     field?.kind === "string" &&
     isSha256DigestSchema(field.zod as z.ZodTypeAny)
@@ -392,6 +400,13 @@ export function generateDartApplication(
 ): string {
   registerDartNames(mod.aggregates);
   const domain = mod.domain ?? mod.name;
+  const enumDartTypes = collectDartEnums(
+    mod.aggregates,
+    mod.directives,
+    domain,
+    mod.valueObjects ?? [],
+    mod.deriveds ?? [],
+  ).dartTypes;
   const application = dartApplicationClassName(domain);
   const activity = dartApplicationActivityClassName(domain);
   const client = dartClientClassName(domain);
@@ -434,15 +449,15 @@ export function generateDartApplication(
   );
   if (hasVersionedRefs) {
     claimApplicationMember(
-      "freshness",
+      "versionStatus",
       "the generated versioned-reference boundary"
     );
     appLines.push(
       `  /// Check whether [reference]'s immutable publication is still current. This reads the`,
       `  /// stable series' one compiled pointer; it never reconstructs publication history.`,
-      `  Future<ReferenceFreshness<TVersion>> freshness<TVersion, TSeries>(`,
+      `  Future<ReferenceVersionStatus<TVersion>> versionStatus<TVersion, TSeries>(`,
       `      VersionedNomosRef<TVersion, TSeries> reference) =>`,
-      `      _client.referenceFreshness(reference);`,
+      `      _client.referenceVersionStatus(reference);`,
       ``
     );
   }
@@ -590,10 +605,21 @@ export function generateDartApplication(
         (input) => input.idField
       )
     );
-    return specs
+    const targetBinding = directive.targetBinding;
+    const targetChecks = targetBinding === undefined
+      ? []
+      : [
+          `    _nmsRequireReference(target, ${JSON.stringify(
+            targetBinding.aggregateId
+          )}, _client.session?.workspace ?? '');`,
+        ];
+    return [
+      ...targetChecks,
+      ...specs
       .filter(
         (spec) =>
           (spec.toJson === "ref" || spec.toJson === "addressRef") &&
+          spec.name !== targetBinding?.field &&
           !recordInputIds.has(spec.name)
       )
       .map((spec) => {
@@ -618,7 +644,8 @@ export function generateDartApplication(
               targetWire
             )}, ${expectedWorkspace}));`
           : `    ${check}`;
-      });
+      }),
+    ];
   };
 
   for (const aggregate of mod.aggregates) {
@@ -832,6 +859,9 @@ export function generateDartApplication(
     // 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 === directive.targetBinding?.field) {
+        return "NmsInternalNomosRefs.id(target)";
+      }
       if (!path.includes(".")) {
         const workspaceOwner = foreignInputs.find(
           (input) => input.workspaceField === path
@@ -850,8 +880,11 @@ export function generateDartApplication(
     };
     const trust = directive.businessSourceTrust;
     const method = member(directive.id);
+    const call = directive.targetBinding === undefined
+      ? `_client.${method}(facts)`
+      : `_client.${method}(target, facts)`;
     if (trust === undefined) {
-      return { prelude: [], call: `_client.${method}(facts)` };
+      return { prelude: [], call };
     }
     const copied = Object.entries(trust.copy)
       .sort(([a], [b]) => a.localeCompare(b))
@@ -875,7 +908,7 @@ export function generateDartApplication(
         `      },`,
         `    );`,
       ],
-      call: `_client.${method}(facts)`,
+      call,
     };
   };
 
@@ -923,6 +956,18 @@ export function generateDartApplication(
     for (const [index, policy] of sharingPolicies.entries()) {
       const pendingKey = policy.pending.key[0]!;
       const pendingMethod = member(policy.pending.id);
+      const pendingAggregate = aggregates.get(policy.pending.returns);
+      const pendingField = pendingAggregate?.fields[pendingKey] as
+        | Field
+        | undefined;
+      const pendingValue =
+        pendingField?.kind === "enum"
+          ? `${keyType(
+              pendingAggregate,
+              pendingKey,
+              enumDartTypes,
+            )}.fromWire(${JSON.stringify(policy.pendingValue)})`
+          : JSON.stringify(policy.pendingValue);
       const person = sharingOrderValue(policy, policy.person, "wire");
       const role = sharingOrderValue(policy, policy.role, "wire");
       const scope = sharingOrderValue(policy, policy.scope, "wire");
@@ -992,7 +1037,7 @@ export function generateDartApplication(
         ``,
         `  Future<void> _nmsDrainWorkspaceSharingOnce${index}() async {`,
         `    final orders = await _client.${pendingMethod}(`,
-        `      ${member(pendingKey)}: ${JSON.stringify(policy.pendingValue)},`,
+        `      ${member(pendingKey)}: ${pendingValue},`,
         `    );`,
         `    for (final order in orders) {`,
         `      late final ApplicationShareResult share;`,
@@ -1328,6 +1373,19 @@ export function generateDartApplication(
 
     const method = member(directive.id);
     const payload = dartActionInputClassName(directive);
+    const targetOnly = directive.targetBinding !== undefined &&
+      introspectPayload(directive.payloadSchema as z.ZodTypeAny, new Map()).every(
+        (spec) =>
+          spec.name === directive.targetBinding?.field ||
+          spec.name === directive.businessPrincipalField,
+      ) &&
+      (directive.businessRecordInputs?.length ?? 0) === 0;
+    const targetParameter = directive.targetBinding === undefined
+      ? `${payload} facts`
+      : targetOnly
+      ? `NomosRef<${concreteClassName(directive.targetBinding.aggregateId)}> target`
+      : `NomosRef<${concreteClassName(directive.targetBinding.aggregateId)}> target, ${payload} facts`;
+    const factsPrelude = targetOnly ? [`    const facts = ${payload}();`] : [];
     const referenceChecks = actionReferenceChecks(directive);
     const outputs = dartActionOutputs(directive, mod.aggregates);
     const resultClass = dartActionResultClassName(directive.id);
@@ -1379,7 +1437,8 @@ 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<${resultClass}> ${method}(${payload} facts) async {`,
+          `  Future<${resultClass}> ${method}(${targetParameter}) async {`,
+          ...factsPrelude,
           ...referenceChecks,
           ...sourceTrust.prelude,
           `    final change = await ${sourceTrust.call};`,
@@ -1393,7 +1452,8 @@ 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<NomosOperationReceipt> ${method}(${payload} facts) async {`,
+          `  Future<NomosOperationReceipt> ${method}(${targetParameter}) async {`,
+          ...factsPrelude,
           ...referenceChecks,
           ...sourceTrust.prelude,
           `    final change = await ${sourceTrust.call};`,
@@ -1411,7 +1471,8 @@ export function generateDartApplication(
         `  /// ${cap(
           camel(directive.id)
         )}. Returns every affected typed business record reference.`,
-        `  Future<${resultClass}> ${method}(${payload} facts) async {`,
+        `  Future<${resultClass}> ${method}(${targetParameter}) async {`,
+        ...factsPrelude,
         ...referenceChecks,
         ...sourceTrust.prelude,
         `    final change = await ${sourceTrust.call};`,
@@ -1422,7 +1483,8 @@ export function generateDartApplication(
     } else {
       addCollectionMember(directive.aggregateId, method, [
         `  /// ${cap(camel(directive.id))}.`,
-        `  Future<NomosOperationReceipt> ${method}(${payload} facts) async {`,
+        `  Future<NomosOperationReceipt> ${method}(${targetParameter}) async {`,
+        ...factsPrelude,
         ...referenceChecks,
         ...sourceTrust.prelude,
         `    final change = await ${sourceTrust.call};`,
@@ -1458,7 +1520,7 @@ export function generateDartApplication(
     const model = readModelClassName(query.returns);
     const aggregate = aggregates.get(query.returns);
     const params = query.key
-      .map((key) => `required ${keyType(aggregate, key)} ${keyParam(key)}`)
+      .map((key) => `required ${keyType(aggregate, key, enumDartTypes)} ${keyParam(key)}`)
       .join(", ");
     const args = query.key
       .map((key) => `${keyParam(key)}: ${keyParam(key)}`)
@@ -1786,7 +1848,9 @@ export function generateDartApplication(
   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);
+      count.by == null
+        ? ""
+        : keyType(aggregates.get(count.of), count.by, enumDartTypes);
     addCollectionMember(count.of, method, [
       count.by == null
         ? `  Future<int> ${method}() => _client.${method}();`
@@ -1798,7 +1862,9 @@ export function generateDartApplication(
   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);
+      sum.by == null
+        ? ""
+        : keyType(aggregates.get(sum.of), sum.by, enumDartTypes);
     addCollectionMember(sum.of, method, [
       sum.by == null
         ? `  Future<int> ${method}() => _client.${method}();`

package/src/codegen_dart_client.ts

@@ -49,6 +49,8 @@ import {
   dartBusinessRecordInputs,
   dartActionInputClassName,
   dartMemberName,
+  collectDartEnums,
+  dartEnumTypeForField,
 } from "./codegen_dart.js";
 import { finishCount } from "./count.js";
 import { finishSum } from "./sum.js";
@@ -147,7 +149,11 @@ const dartStr = (s: string) =>
   `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
 
 /** The Dart param type for a query index key. Aggregate relations keep their canonical typed ref. */
-function dartKeyType(agg: AggregateHandle | undefined, key: string): string {
+function dartKeyType(
+  agg: AggregateHandle | undefined,
+  key: string,
+  enumDartTypes: ReadonlyMap<string, string>,
+): string {
   const lead = key.includes(".") ? key.split(".")[0]! : key;
   const f = agg?.fields[lead] as Field | undefined;
   if (f && (f.kind === "int" || f.kind === "counter")) return "int";
@@ -162,6 +168,8 @@ function dartKeyType(agg: AggregateHandle | undefined, key: string): string {
     if (f.refAggregateId !== undefined)
       return `NomosRef<${concreteClassName(f.refAggregateId)}>`;
   }
+  const enumType = dartEnumTypeForField(f, enumDartTypes);
+  if (enumType !== undefined) return enumType;
   if (f?.kind === "string" && isSha256DigestSchema(f.zod as z.ZodTypeAny)) {
     return "Sha256Digest";
   }
@@ -181,6 +189,7 @@ function dartKeyExpr(agg: AggregateHandle | undefined, key: string): string {
   ) {
     return `${param}.value`;
   }
+  if (field?.kind === "enum") return `${param}.wire`;
   if (
     field?.kind === "string" &&
     isGitObjectIdSchema(field.zod as z.ZodTypeAny)
@@ -325,6 +334,13 @@ export function generateDartBridgeClient(
   };
   registerDartNames(mod.aggregates); // `.dartName` overrides for read-model class names in the client.
   const domain = mod.domain ?? mod.name;
+  const enumDartTypes = collectDartEnums(
+    mod.aggregates,
+    mod.directives,
+    domain,
+    mod.valueObjects ?? [],
+    mod.deriveds ?? [],
+  ).dartTypes;
   assertModelClientMemberAvailable(mod);
   const describeModel =
     opts.describeModel ?? buildNomosDescribeModel([mod], domain);
@@ -457,9 +473,9 @@ export function generateDartBridgeClient(
     methods.push(
       `  /// Check only whether an immutable publication pin is still the stable series' current`,
       `  /// publication. The kernel reads one compiled current pointer; it does not resolve history.`,
-      `  Future<ReferenceFreshness<TVersion>> referenceFreshness<TVersion, TSeries>(`,
+      `  Future<ReferenceVersionStatus<TVersion>> referenceVersionStatus<TVersion, TSeries>(`,
       `      VersionedNomosRef<TVersion, TSeries> reference) =>`,
-      `      bridge.checkReferenceFreshness(reference);`,
+      `      bridge.checkReferenceVersion(reference);`,
       ``
     );
   }
@@ -578,6 +594,13 @@ export function generateDartBridgeClient(
   }
   for (const d of dirs) {
     const payloadClass = dartActionInputClassName(d);
+    const targetBinding = isBusinessIntent(d) ? d.targetBinding : undefined;
+    const targetType = targetBinding === undefined
+      ? undefined
+      : `NomosRef<${concreteClassName(targetBinding.aggregateId)}>`;
+    const actionParameters = targetBinding === undefined
+      ? `${payloadClass} payload`
+      : `${targetType} target, ${payloadClass} payload`;
     const stamps = autoStampFields(
       (d as unknown as { payloadSchema: z.ZodTypeAny }).payloadSchema
     );
@@ -628,6 +651,9 @@ export function generateDartBridgeClient(
             `    }`,
           ];
     const payloadJsonArgs = [
+      ...(targetBinding === undefined
+        ? []
+        : ["nmsInternalTarget: target"]),
       ...(principalField === undefined
         ? []
         : ["nmsInternalPrincipal: nmsInternalPrincipal"]),
@@ -702,7 +728,7 @@ export function generateDartBridgeClient(
             : "Encrypted field(s) are SEALED via the bound [keyStore] before dispatch (pass `seal: false` to skip)."
         }${stampsDoc}`,
         ...(gateDoc ? [gateDoc] : []),
-        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload${
+        `  Future<NomosOfferOutcome> ${method}(${actionParameters}${
           ownedSeal ? "" : ", {bool seal = true}"
         }) async {`,
         ...(gateGuard ? [gateGuard] : []),
@@ -734,7 +760,7 @@ export function generateDartBridgeClient(
       methods.push(
         `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}${stampsDoc}`,
         ...(gateDoc ? [gateDoc] : []),
-        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload) {`,
+        `  Future<NomosOfferOutcome> ${method}(${actionParameters}) {`,
         ...(gateGuard ? [gateGuard] : []),
         ...principalPrelude,
         `    final data = ${payloadJson};`,
@@ -750,7 +776,7 @@ export function generateDartBridgeClient(
       methods.push(
         `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}`,
         gateDoc,
-        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload) {`,
+        `  Future<NomosOfferOutcome> ${method}(${actionParameters}) {`,
         ...(gateGuard ? [gateGuard] : []),
         ...principalPrelude,
         `    return _offer(${dartStr(d.id)}, ${payloadJson});`,
@@ -761,7 +787,7 @@ export function generateDartBridgeClient(
       methods.push(
         `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}`,
         ...(gateDoc ? [gateDoc] : []),
-        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload) =>`,
+        `  Future<NomosOfferOutcome> ${method}(${actionParameters}) =>`,
         `      _offer(${dartStr(d.id)}, ${payloadJson});`,
         ``
       );
@@ -993,7 +1019,7 @@ export function generateDartBridgeClient(
     const model = readModelClassName(q.returns);
     const agg = aggById.get(q.returns);
     const params = q.key
-      .map((k) => `required ${dartKeyType(agg, k)} ${dartKeyParam(k)}`)
+      .map((k) => `required ${dartKeyType(agg, k, enumDartTypes)} ${dartKeyParam(k)}`)
       .join(", ");
     const argMap = `{${q.key
       .map((k) => `${dartStr(k)}: ${dartKeyExpr(agg, k)}`)
@@ -1119,7 +1145,8 @@ export function generateDartBridgeClient(
   for (const c of (mod.counts ?? []).map((raw) => finishCount(raw))) {
     const m = safeMethod(lcFirst(camel(c.id)));
     const aggregate = aggById.get(c.of);
-    const groupType = c.by == null ? "" : dartKeyType(aggregate, c.by);
+    const groupType =
+      c.by == null ? "" : dartKeyType(aggregate, c.by, enumDartTypes);
     const groupValue = c.by == null ? "" : dartKeyExpr(aggregate, c.by);
     methods.push(
       c.by != null
@@ -1155,7 +1182,8 @@ export function generateDartBridgeClient(
   for (const s of (mod.sums ?? []).map((raw) => finishSum(raw))) {
     const m = safeMethod(lcFirst(camel(s.id)));
     const aggregate = aggById.get(s.of);
-    const groupType = s.by == null ? "" : dartKeyType(aggregate, s.by);
+    const groupType =
+      s.by == null ? "" : dartKeyType(aggregate, s.by, enumDartTypes);
     const groupValue = s.by == null ? "" : dartKeyExpr(aggregate, s.by);
     methods.push(
       s.by != null

package/src/codegen_dot.ts

@@ -39,7 +39,7 @@ import type { AggregateHandle } from "./aggregate.js";
 import type { Field, FieldKind } from "./fields.js";
 import type { Directive } from "./directive.js";
 import type { RelationDecl } from "./relation.js";
-import type { DerivedDecl } from "./derived.js";
+import type { AnyDerivedDecl } from "./derived.js";
 import type { CombinedDecl } from "./combined.js";
 import type { DomainModule } from "./codegen_dart.js";
 
@@ -224,7 +224,7 @@ function contextOf(
 function aggregateLabel(
   agg: AggregateHandle,
   border: string,
-  deriveds: readonly DerivedDecl[],
+  deriveds: readonly AnyDerivedDecl[],
   combineds: readonly CombinedDecl[],
   showInvariant: boolean,
 ): string {
@@ -299,7 +299,7 @@ export function emitDomainDot(mod: DomainModule, opts: DotOptions = {}): string
   const knownIds = new Set(aggregates.map((a) => a.id));
 
   // derived/combined read fields grouped by owner aggregate type.
-  const derivedsByType = new Map<string, DerivedDecl[]>();
+  const derivedsByType = new Map<string, AnyDerivedDecl[]>();
   for (const d of mod.deriveds ?? []) {
     const list = derivedsByType.get(d.of) ?? [];
     list.push(d);

package/src/codegen_proof.ts

@@ -3343,9 +3343,9 @@ function generateSealedApplicationProof(
     `  ? (sample: { readonly operation: string; readonly name: string; readonly durationMs: number; readonly domain?: string; readonly directive?: string }) =>`,
     `      console.error("[nomos-application-performance] " + JSON.stringify(sample))`,
     `  : undefined;`,
-    `const coldOpenStarted = performance.now();`,
+    `const commissionStarted = performance.now();`,
     `const application = await ${opener}({ cloud, application: applicationName, signIn, onPerformance: reportPerformance });`,
-    `if (reportPerformance) reportPerformance({ operation: "open", name: "generated application ready (cold)", durationMs: performance.now() - coldOpenStarted });`,
+    `if (reportPerformance) reportPerformance({ operation: "open", name: "first application commissioning", durationMs: performance.now() - commissionStarted });`,
     `ok("opened the generated ${applicationName}; identity, custody, recovery and sync stay inside Nomos");`,
     `const waitUntilSaved = async (): Promise<void> => {`,
     `  const current = await application.currentStatus();`,
@@ -3369,8 +3369,17 @@ function generateSealedApplicationProof(
     );
     out.push(
       `const facts = ${JSON.stringify(businessPayload)};`,
+      `const businessBirthStarted = performance.now();`,
       `const born = await application.${applicationBirthMethod!}(facts);`,
+      `reportPerformance?.({ operation: "birth", name: "generated workspace birth e2e", durationMs: performance.now() - businessBirthStarted, domain: ${JSON.stringify(domain)}, directive: ${JSON.stringify(businessBirth.birthDirectiveId)} });`,
       `if (born === undefined) fail("business birth returned no child application");`,
+      `const generatedReadStarted = performance.now();`,
+      `const bornRoots = await born.${generatedAggregateCollectionName(businessBirth.businessAggregateId!)}.all();`,
+      `reportPerformance?.({ operation: "read", name: "generated business read e2e", durationMs: performance.now() - generatedReadStarted, domain: ${JSON.stringify(businessBirth.childDomain)} });`,
+      `if (bornRoots.length === 0) fail("the born application could not read its generated root record");`,
+      `const convergenceStarted = performance.now();`,
+      `await born.creationReceipt;`,
+      `reportPerformance?.({ operation: "sync", name: "generated workspace convergence receipt", durationMs: performance.now() - convergenceStarted, domain: ${JSON.stringify(businessBirth.childDomain)} });`,
       `await waitUntilSaved();`,
       `ok(${JSON.stringify(`birth(${businessBirth.businessAggregateId}) saved through the generated application`)});`,
     );
@@ -3449,7 +3458,9 @@ function generateSealedApplicationProof(
       `if (cleared${proofTypeIdent(field)}?.[${JSON.stringify(field)}] !== null) fail(${JSON.stringify(`CLEAR-LANE PROOF — ${aggregate.id}.${field} did not read back as explicit null`)});`,
     ]);
     out.push(
+      `const businessOfferStarted = performance.now();`,
       `const result = await application.${action.id}(${payloadLiteral});`,
+      `reportPerformance?.({ operation: "offer", name: "generated ordinary offer e2e", durationMs: performance.now() - businessOfferStarted, domain: ${JSON.stringify(domain)}, directive: ${JSON.stringify(action.id)} });`,
       `const created = result.${proofResultMember(aggregate.id)};`,
       `${proofRefSlot(aggregate.id)} = created;`,
       `ok(${JSON.stringify(`${domain}/${action.id} accepted business facts and returned a typed reference`)});`,
@@ -3458,7 +3469,9 @@ function generateSealedApplicationProof(
       `await waitUntilSaved();`,
       ...clearReadLines,
       `const reopened = await ${opener}({ cloud, application: applicationName, signIn });`,
+      `const generatedReadStarted = performance.now();`,
       `const rows = await reopened.${generatedAggregateCollectionName(aggregate.id)}.all();`,
+      `reportPerformance?.({ operation: "read", name: "generated business read e2e", durationMs: performance.now() - generatedReadStarted, domain: ${JSON.stringify(domain)} });`,
       `if (!rows.some((row) => sameRecord(row.ref, created))) fail("a fresh generated application could not read " + created.address + "; restored addresses: " + (rows.map((row) => row.ref.address).join(", ") || "(none)"));`,
       `ok("a fresh generated application read the saved record after synchronization");`,
     );
@@ -3475,6 +3488,15 @@ function generateSealedApplicationProof(
     `const _proofDispose = _proofDisposable[Symbol.asyncDispose];`,
     `if (_proofDispose) await Promise.race([_proofDispose(), new Promise<void>((resolve) => setTimeout(resolve, 1_000))]);`,
     `if (performanceEnabled) {`,
+    `  process.env.NOMOS_FORCE_COLD_APPLICATION_PLANE = "1";`,
+    `  const coldOpenStarted = performance.now();`,
+    `  const coldApplication = await ${opener}({ cloud, application: applicationName, signIn, onPerformance: reportPerformance });`,
+    `  reportPerformance?.({ operation: "open", name: "generated application ready (cold restore)", durationMs: performance.now() - coldOpenStarted });`,
+    `  delete process.env.NOMOS_FORCE_COLD_APPLICATION_PLANE;`,
+    `  const coldStatus = await coldApplication.currentStatus();`,
+    `  if (coldStatus.phase === "attention") fail(coldStatus.message ?? "the cold-restored application needs attention");`,
+    `  const coldDisposable = coldApplication as unknown as { [Symbol.asyncDispose]?: () => Promise<void> };`,
+    `  if (coldDisposable[Symbol.asyncDispose]) await Promise.race([coldDisposable[Symbol.asyncDispose]!(), new Promise<void>((resolve) => setTimeout(resolve, 1_000))]);`,
     `  const warmOpenStarted = performance.now();`,
     `  const warmApplication = await ${opener}({ cloud, application: applicationName, signIn, onPerformance: reportPerformance });`,
     `  reportPerformance?.({ operation: "open", name: "generated application ready (warm)", durationMs: performance.now() - warmOpenStarted });`,

package/src/codegen_ts.ts

@@ -55,7 +55,7 @@ import { voMetaOf, collectPayloadValueObjectDescriptors, idOfMetaOf, idOfTargetK
 import { recursiveTypeBaseName, zodUnwrapLazy } from "./zod_lazy.js";
 import { finishCount } from "./count.js";
 import { finishSum } from "./sum.js";
-import type { DerivedDecl } from "./derived.js";
+import type { AnyDerivedDecl } from "./derived.js";
 import type { CombinedDecl } from "./combined.js";
 import { resolveWorkspaceTypes, type ResolvedWorkspaceType, type WorkspaceTypeDecl } from "./workspace_type.js";
 import {
@@ -733,7 +733,11 @@ function tsTypeOfReturns(returns: unknown): string {
 function aggregatesOf(mod: Record<string, unknown>): AggregateHandle[] {
   const out: AggregateHandle[] = [];
   for (const v of Object.values(mod)) {
-    if (v && typeof v === "object" && (v as { __isAggregateHandle?: boolean }).__isAggregateHandle === true) {
+    if (
+      v && typeof v === "object" &&
+      (v as { __isAggregateHandle?: boolean }).__isAggregateHandle === true &&
+      (v as { __isForwardRef?: boolean }).__isForwardRef !== true
+    ) {
       out.push(v as AggregateHandle);
     }
   }
@@ -1634,27 +1638,27 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `}`,
     ...(hasVersionedRefs
       ? [
-          `export type ReferenceFreshness<TVersion> =`,
+          `export type ReferenceVersionStatus<TVersion> =`,
           `  | { readonly status: "current"; readonly latest: NomosRef<TVersion> }`,
-          `  | { readonly status: "stale"; readonly latest: NomosRef<TVersion> }`,
+          `  | { readonly status: "outdated"; readonly latest: NomosRef<TVersion> }`,
           `  | { readonly status: "unavailable"; readonly reason: string };`,
           `/** An immutable publication pin plus the stable series which declares its current publication.`,
-          ` *  freshness() is O(current state): it never reconstructs the pinned record or walks history. */`,
+          ` *  versionStatus() is O(current state): it never reconstructs the pinned record or walks history. */`,
           `export interface VersionedNomosRef<TVersion, TSeries> {`,
           `  readonly pinned: NomosRef<TVersion>;`,
           `  readonly series: NomosRef<TSeries>;`,
-          `  freshness(): Promise<ReferenceFreshness<TVersion>>;`,
+          `  versionStatus(): Promise<ReferenceVersionStatus<TVersion>>;`,
           `}`,
           `type _NomosRawAddress = { workspace: string; type: string; id: string };`,
           `function _versionedNomosRef<TVersion, TSeries>(nomos: NomosHolon, raw: { pinned: _NomosRawAddress; series: _NomosRawAddress }, currentField: string): VersionedNomosRef<TVersion, TSeries> {`,
           `  const pinned = _nmsRef<TVersion>(raw.pinned.workspace, raw.pinned.type, raw.pinned.id);`,
           `  const series = _nmsRef<TSeries>(raw.series.workspace, raw.series.type, raw.series.id);`,
-          `  return { pinned, series, async freshness() {`,
-          `    if (nomos.checkRefFreshness === undefined) return { status: "unavailable", reason: "installed Nomos runtime does not support reference freshness" };`,
-          `    const result = await nomos.checkRefFreshness([{ pinned: raw.pinned, series: raw.series, currentField }]);`,
+          `  return { pinned, series, async versionStatus() {`,
+          `    if (nomos.checkReferenceVersions === undefined) return { status: "unavailable", reason: "installed Nomos runtime does not support reference version checks" };`,
+          `    const result = await nomos.checkReferenceVersions([{ pinned: raw.pinned, series: raw.series, currentField }]);`,
           `    const outcome = result.unique[0]?.outcome;`,
           `    if (outcome?.status === "current") return { status: "current", latest: pinned };`,
-          `    if (outcome?.status === "stale" && outcome.latest !== undefined) return { status: "stale", latest: _nmsRef<TVersion>(outcome.latest.workspace, outcome.latest.type, outcome.latest.id) };`,
+          `    if (outcome?.status === "outdated" && outcome.latest !== undefined) return { status: "outdated", latest: _nmsRef<TVersion>(outcome.latest.workspace, outcome.latest.type, outcome.latest.id) };`,
           `    return { status: "unavailable", reason: String(outcome?.status ?? "unknown") };`,
           `  } };`,
           `}`,
@@ -1794,7 +1798,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     ...(hasVersionedRefs
       ? [
           `  /** Framework-private O(current-state) version check used by generated VersionedNomosRef. */`,
-          `  checkRefFreshness?(refs: readonly { pinned: _NomosRawAddress; series: _NomosRawAddress; currentField: string }[]): Promise<{ unique: { outcome: { status: string; latest?: _NomosRawAddress } }[]; order: number[] }>;`,
+          `  checkReferenceVersions?(refs: readonly { pinned: _NomosRawAddress; series: _NomosRawAddress; currentField: string }[]): Promise<{ unique: { outcome: { status: string; latest?: _NomosRawAddress } }[]; order: number[] }>;`,
         ]
       : []),
     `  /** FRAMEWORK-INTERNAL exact-history adoption seam. Generated clients expose only`,
@@ -2416,9 +2420,11 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   // ── read models: one interface per aggregate wire type (deduped), deriveds/combineds merged ──
   const extrasByType = new Map<string, string[]>();
   for (const mod of modules) {
-    for (const d of (mod.deriveds ?? []) as DerivedDecl[]) {
+    for (const d of (mod.deriveds ?? []) as AnyDerivedDecl[]) {
       (extrasByType.get(d.of) ?? extrasByType.set(d.of, []).get(d.of)!).push(
-        `  /** derived read field (engine-projected) */\n  ${d.id}?: ${tsTypeOfReturns(d.returns)};`,
+        "kind" in d && d.kind === "temporalEnum"
+          ? `  /** native temporal enum read field (captured-clock projection) */\n  ${d.id}: ${tsTypeOfReturns(d.returns)};`
+          : `  /** derived read field (engine-projected) */\n  ${d.id}?: ${tsTypeOfReturns(d.returns)};`,
       );
     }
     for (const c of (mod.combineds ?? []) as CombinedDecl[]) {
@@ -2820,6 +2826,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   const usedResultNames = new Set<string>();
   const applicationBirths: Array<{
     sourceDomain: string;
+    directiveId: string;
     method: string;
     payloadName: string;
     aggregateId: string;
@@ -3186,6 +3193,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         const applicationMethod = isBusinessIntent(d) ? d.id : "birth";
         applicationBirths.push({
           sourceDomain: domain,
+          directiveId: d.id,
           method: applicationMethod,
           payloadName,
           aggregateId: businessBirth.aggregateId,
@@ -3206,9 +3214,6 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           ...(ownedBirthDescriptor !== undefined
             ? [`      if (born.workspace !== _ownedBirthKey.workspace) throw new Error("birth() returned a workspace different from the deterministic owned-custody address");`]
             : []),
-          `      await holon.sync?.();`,
-          `      if (!holon.settleBirth) throw new Error("birth() requires the current @githolon/client to complete durable recovery");`,
-          `      await holon.settleBirth(born.workspace);`,
           `      return _nmsRef<${businessBirth.aggregateId}>(born.workspace, ${JSON.stringify(businessBirth.aggregateId)}, ${JSON.stringify(businessBirth.rootId)});`,
           `    },`,
         );
@@ -3916,7 +3921,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         `type ${tsDomainApplicationType(domain)} = _NomosPublicDomain<ReturnType<typeof ${tsClientFactoryName(domain)}>>;`
       ),
       ...childApplicationTypes.map((birth) =>
-        `export type ${birth.applicationType} = _NomosPublicDomain<ReturnType<typeof ${tsClientFactoryName(birth.targetDomain)}>>;`
+        `export type ${birth.applicationType} = _NomosPublicDomain<ReturnType<typeof ${tsClientFactoryName(birth.targetDomain)}>> & { readonly creationReceipt: Promise<void> };`
       ),
       `type _${applicationName}Business = ${applicationType};`,
       `export type ${applicationName}Status = _NomosApplicationStatus;`,
@@ -3996,11 +4001,19 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         `  application[${JSON.stringify(birth.method)}] = async (input: ${birth.payloadName}): Promise<${birth.applicationType}> => {`,
         `    const root = await _nmsRoot${rootIndex}[${JSON.stringify(birth.method)}](input);`,
         `    const address = _nmsReferenceData(root);`,
-        `    return nomosInternalOpenGeneratedChildApplication(`,
+        `    const child = await nomosInternalOpenGeneratedChildApplication(`,
         `      holon,`,
         `      address.workspace,`,
         `      (child) => _nomosPublicDomain(${tsClientFactoryName(birth.targetDomain)}(child as NomosHolon)),`,
         `    );`,
+        `    const creationReceipt = (async (): Promise<void> => {`,
+        `      await holon.sync?.();`,
+        `      if (!holon.settleBirth) throw new Error("birth() requires the current @githolon/client to prove remote custody convergence");`,
+        `      await holon.settleBirth(address.workspace);`,
+        `    })();`,
+        `    void creationReceipt.catch(() => {});`,
+        `    Object.defineProperty(child, "creationReceipt", { value: creationReceipt, enumerable: true, configurable: false, writable: false });`,
+        `    return child as ${birth.applicationType};`,
         `  };`,
         ];
       }),
@@ -4061,7 +4074,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       ` *  or parallel cache around it. Nomos owns offline custody and synchronization. */`,
       `export function ${applicationOpener}(options: ${applicationName}OpenOptions): Promise<${applicationName}> {`,
       `  return nomosInternalOpenGeneratedApplication(`,
-      `    { cloud: options.cloud, application: options.application, signIn: options.signIn, onPerformance: options.onPerformance, lawHash: ${hashConst} },`,
+      `    { cloud: options.cloud, application: options.application, signIn: options.signIn, onPerformance: options.onPerformance, lawHash: ${hashConst}, readyCommands: [${rootBirths.map((birth) => `{ domain: ${JSON.stringify(birth.sourceDomain)}, packageHash: ${hashConst}, directiveId: ${JSON.stringify(birth.directiveId)} }`).join(", ")}] },`,
       `    (holon, user) => _nomosBind${applicationName}(holon as NomosHolon, user),`,
       `  );`,
       `}`,