@githolon/dsl 0.102.1 → 0.102.3

package/dart/pubspec.yaml

@@ -8,7 +8,7 @@ description: >-
   Nomos 2 Dart frontend types — the hand-written kernel wire types plus the
   code-generated per-domain aggregate + directive-payload types. (De)serializes
   the EXACT serde JSON the Rust kernel + projection produce/consume.
-version: 0.64.0
+version: 0.64.1
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.102.1",
+  "version": "0.102.3",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/runtime/generated-application-host.js

@@ -1834,12 +1834,20 @@ function parseBulkReadForbidden(status, bodyText) {
 // ../cloud/web-client/src/kernel_provider_wasm.ts
 var enc2 = new TextEncoder();
 var dec2 = new TextDecoder();
-var snapB64 = (bytes) => {
+var nmsInternalSnapshotToBase64 = (bytes) => {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
+  }
   let s = "";
-  for (let i = 0; i < bytes.length; i += 32768) s += String.fromCharCode.apply(null, bytes.subarray(i, i + 32768));
+  for (let i = 0; i < bytes.length; i += 32768) {
+    s += String.fromCharCode.apply(null, bytes.subarray(i, i + 32768));
+  }
   return btoa(s);
 };
-var snapUnb64 = (s) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
+var nmsInternalSnapshotFromBase64 = (s) => {
+  if (typeof Buffer !== "undefined") return Buffer.from(s, "base64");
+  return Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
+};
 var unpack = (p) => {
   const v = typeof p === "bigint" ? p : BigInt(p);
   return { ptr: Number(v >> 32n), len: Number(v & 0xffffffffn) };
@@ -1884,7 +1892,7 @@ function wasmModuleFor(base, fetchImpl) {
 function parseSnapshot(bytes) {
   try {
     const o = JSON.parse(dec2.decode(bytes));
-    if (o && o.v === 2 && typeof o.tree === "string") return { treeBytes: snapUnb64(o.tree), ckpt: o.ckpt ?? null, frontier: o.frontier ?? null, syncedBase: o.syncedBase ?? null };
+    if (o && o.v === 2 && typeof o.tree === "string") return { treeBytes: nmsInternalSnapshotFromBase64(o.tree), ckpt: o.ckpt ?? null, frontier: o.frontier ?? null, syncedBase: o.syncedBase ?? null };
   } catch {
   }
   return { treeBytes: bytes, ckpt: null, frontier: null, syncedBase: null };
@@ -1893,7 +1901,7 @@ function buildSnapshot(treeBytes, ckpt, syncedBase) {
   if ((!ckpt || !ckpt.blob && !ckpt.frontier) && !syncedBase) return treeBytes;
   return enc2.encode(JSON.stringify({
     v: 2,
-    tree: snapB64(treeBytes),
+    tree: nmsInternalSnapshotToBase64(treeBytes),
     ckpt: ckpt && ckpt.blob ? ckpt.blob : null,
     frontier: ckpt ? ckpt.frontier ?? null : null,
     cursor: ckpt ? ckpt.cursor ?? null : null,
@@ -2133,7 +2141,7 @@ function createWasmEnginePlane({ span } = {}) {
           }
           const buf = new Uint8Array(await r.arrayBuffer());
           if (!buf.length) return { applied: false };
-          view.applyPack(snapB64(buf));
+          view.applyPack(nmsInternalSnapshotToBase64(buf));
           return { applied: true };
         } finally {
           if (end) end();

package/src/application_composition.ts

@@ -1,6 +1,7 @@
 // NOMOS — OpenUSD is the application/package IR. JavaScript config is authoring input only.
 
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 
@@ -40,6 +41,25 @@ export interface PackageRootPart {
   readonly kind: Exclude<PartKind, "group">;
 }
 
+export type ApplicationPackagePlacement = "reference" | "payload";
+
+export interface ApplicationDeploymentPackage {
+  /** The authored application part that gives this package its placement semantics. */
+  readonly part: string;
+  /** Reference packages serve on the application workspace; payload packages are retained for child birth. */
+  readonly placement: ApplicationPackagePlacement;
+  readonly packageName: string;
+  readonly sourceIdentity: string;
+  readonly assetPath: string;
+  readonly deployPath: string;
+}
+
+export interface ApplicationDeploymentPlan {
+  readonly application: string;
+  readonly stagePath: string;
+  readonly packages: readonly ApplicationDeploymentPackage[];
+}
+
 const safeUsdName = (value: string, what: string): void => {
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
     throw new Error(`${what} '${value}' is not a USD identifier (letters, digits and '_' only; cannot start with a digit)`);
@@ -203,7 +223,12 @@ export function compileApplicationComposition(
   config: ApplicationCompositionConfig,
   configPath: string,
   options: { readonly requireUsdcat?: boolean } = {},
-): { readonly outputPath: string; readonly usda: string; readonly referencedAssets: readonly string[] } {
+): {
+  readonly outputPath: string;
+  readonly usda: string;
+  readonly referencedAssets: readonly string[];
+  readonly deploymentPackages: readonly ApplicationDeploymentPackage[];
+} {
   const configDir = path.dirname(configPath);
   const outDir = path.resolve(configDir, config.outDir ?? "build");
   mkdirSync(outDir, { recursive: true });
@@ -259,7 +284,8 @@ export function compileApplicationComposition(
     rmSync(candidatePath, { force: true });
     throw error;
   }
-  return { outputPath, usda, referencedAssets: [...referencedAssets].sort() };
+  const deploymentPackages = applicationDeploymentPlan(outputPath).packages;
+  return { outputPath, usda, referencedAssets: [...referencedAssets].sort(), deploymentPackages };
 }
 
 export function isApplicationCompositionConfig(value: unknown): value is ApplicationCompositionConfig {
@@ -280,3 +306,92 @@ export function packageRootOfUsda(assetPath: string): { readonly name: string; r
   if (identifier === undefined) throw new Error(`package asset '${assetPath}' root '${name}' has no content identifier`);
   return { name, kind, identifier };
 }
+
+/**
+ * Resolve the operational package set directly from the compiled application USDA.
+ *
+ * This is deliberately a projection, not a second configuration format: deployment reads the same
+ * reference/payload arcs that OpenUSD composes. Package assets bind those arcs to their compiler-emitted
+ * deploy bodies using the package's content identity, so a stale or hand-matched sidecar refuses loudly.
+ */
+export function applicationDeploymentPlan(stagePath: string): ApplicationDeploymentPlan {
+  if (!existsSync(stagePath)) throw new Error(`application stage not found: ${stagePath}`);
+  const stage = readFileSync(stagePath, "utf8");
+  const application = /custom\s+string\s+nomos:application\s*=\s*"([^"]+)"/.exec(stage)?.[1];
+  if (application === undefined) {
+    throw new Error(`'${stagePath}' is not a compiled Nomos application stage (nomos:application is absent)`);
+  }
+
+  type Use = { part: string; placement: ApplicationPackagePlacement; assetPath: string };
+  const uses: Use[] = [];
+  const scope = /def\s+Scope\s+"([A-Za-z_][A-Za-z0-9_]*)"\s*\(([\s\S]*?)\n\s*\)\s*\{/g;
+  for (const match of stage.matchAll(scope)) {
+    const part = match[1]!;
+    const metadata = match[2]!;
+    const reference = /prepend\s+references\s*=\s*@([^@]+)@<([^>]+)>/.exec(metadata);
+    if (reference === null) continue;
+    const payload = /prepend\s+payload\s*=\s*@([^@]+)@<([^>]+)>/.exec(metadata);
+    const asset = reference[1]!;
+    if (isResolverAsset(asset)) {
+      throw new Error(`application deployment cannot resolve '${asset}' without an installed asset resolver`);
+    }
+    const assetPath = path.resolve(path.dirname(stagePath), asset);
+    uses.push({ part, placement: payload === null ? "reference" : "payload", assetPath });
+  }
+  if (uses.length === 0) throw new Error(`application '${application}' contains no deployable package references`);
+
+  const byAsset = new Map<string, Use>();
+  for (const use of uses) {
+    const prior = byAsset.get(use.assetPath);
+    if (prior !== undefined && prior.placement !== use.placement) {
+      throw new Error(
+        `package asset '${use.assetPath}' is both a serving reference ('${prior.part}') and a deferred payload ` +
+          `('${use.part}'); split those responsibilities into separate packages`,
+      );
+    }
+    byAsset.set(use.assetPath, prior ?? use);
+  }
+
+  const packages = [...byAsset.values()].map((use): ApplicationDeploymentPackage => {
+    if (!existsSync(use.assetPath)) throw new Error(`application package asset not found: ${use.assetPath}`);
+    const exported = packageRootOfUsda(use.assetPath);
+    const identity = /^nomos:package:([^:]+):([0-9a-f]{64})$/.exec(exported.identifier);
+    if (identity === null) {
+      throw new Error(`application asset '${use.assetPath}' has invalid Nomos package identity '${exported.identifier}'`);
+    }
+    const packageName = identity[1]!;
+    const sourceIdentity = identity[2]!;
+    const deployPath = path.join(path.dirname(use.assetPath), `${packageName}.deploy.json`);
+    if (!existsSync(deployPath)) {
+      throw new Error(`package '${packageName}' has no sibling deploy body: ${deployPath} (compile the package first)`);
+    }
+    let body: {
+      summary?: { package?: unknown; sourceIdentity?: unknown; domainHash?: unknown };
+      packageUsda?: unknown;
+    };
+    try {
+      body = JSON.parse(readFileSync(deployPath, "utf8")) as typeof body;
+    } catch (error) {
+      throw new Error(`package '${packageName}' deploy body is not valid JSON: ${(error as Error).message}`);
+    }
+    if (body.summary?.package !== packageName) {
+      throw new Error(`package asset '${use.assetPath}' names '${packageName}', but '${deployPath}' does not`);
+    }
+    if (body.summary?.sourceIdentity !== sourceIdentity) {
+      throw new Error(
+        `package '${packageName}' asset/deploy skew: source identity ${sourceIdentity.slice(0, 12)}… does not match ` +
+          `${String(body.summary?.sourceIdentity ?? "missing").slice(0, 12)}…; recompile the package and application together`,
+      );
+    }
+    if (typeof body.packageUsda !== "string" || body.packageUsda.length === 0) {
+      throw new Error(`package '${packageName}' deploy body has no packageUsda`);
+    }
+    const lawHash = createHash("sha256").update(Buffer.from(body.packageUsda, "utf8")).digest("hex");
+    if (body.summary?.domainHash !== lawHash) {
+      throw new Error(`package '${packageName}' deploy body is internally stale (packageUsda hash does not match its summary)`);
+    }
+    return { ...use, packageName, sourceIdentity, deployPath };
+  });
+  packages.sort((a, b) => Number(a.placement === "payload") - Number(b.placement === "payload"));
+  return { application, stagePath, packages };
+}

package/src/business_birth.ts

@@ -166,15 +166,17 @@ function lowerOne<P extends Record<string, unknown>, F extends Record<string, Fi
           grantedBy: founder,
           grantedAt,
         }),
-        ...(decl.aggregate.audience?.kind === "owned"
-          ? writeTuple({
-              object: "workspace:self",
-              relation: OWNED_READ_RELATION,
-              subject: founder,
-              grantedBy: founder,
-              grantedAt,
-            })
-          : []),
+        // The workspace contains framework-private identity/key records even when its root BUSINESS
+        // aggregate is public. Bulk custody cannot selectively clone Git history, so every business-born
+        // workspace must seat its founder on the framework transport relation from genesis. Per-record
+        // visibility remains governed independently; this grant only makes the sovereign replica reopenable.
+        ...writeTuple({
+          object: "workspace:self",
+          relation: OWNED_READ_RELATION,
+          subject: founder,
+          grantedBy: founder,
+          grantedAt,
+        }),
         // Business ownership remains explicit policy. The tenant names roles; Nomos owns subjects,
         // provenance, tuple mechanics and the atomic genesis ordering underneath them.
         ...decl.founderRoles.flatMap((relation) =>

package/src/codegen_dart_application.ts

@@ -31,6 +31,7 @@ import {
 } from "./framework/framework_aggregates.js";
 import { isBusinessIntent } from "./intent.js";
 import { contractTypeName } from "./contract.js";
+import { admitsNull } from "./null_meta.js";
 import type {
   WorkspaceSharingPolicy,
   WorkspaceSharingReceipt,
@@ -590,28 +591,28 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
       const person = sharingOrderValue(policy, policy.person, "wire");
       const role = sharingOrderValue(policy, policy.role, "wire");
       const scope = sharingOrderValue(policy, policy.scope, "wire");
-      const 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;`,
-        `      }`,
-      ]);
+      const receiptLines = (receipt: WorkspaceSharingReceipt, refused: boolean): string[] => {
+        const condition = sharingReceiptCondition(policy, receipt);
+        const body = [
+          `        await _client._offer(`,
+          `          ${JSON.stringify(receipt.records.id)},`,
+          `          <String, Object?>{`,
+          ...sharingReceiptPayload(policy, receipt, refused),
+          `          },`,
+          `        );`,
+          `        continue;`,
+        ];
+        // A receipt with no `when` is the policy's exhaustive fallback. Emitting `if (true)` makes both
+        // the following fallback error and any later receipt dead Dart code, turning generated code into an
+        // analyzer warning. Keep the same semantics but emit the exhaustive body directly.
+        return condition === "true"
+          ? body
+          : [`      if (${condition}) {`, ...body, `      }`];
+      };
+      const delivered = policy.delivered.flatMap((receipt) => receiptLines(receipt, false));
+      const refused = policy.refused.flatMap((receipt) => receiptLines(receipt, true));
+      const deliveredExhaustive = policy.delivered.some((receipt) => sharingReceiptCondition(policy, receipt) === "true");
+      const refusedExhaustive = policy.refused.some((receipt) => sharingReceiptCondition(policy, receipt) === "true");
       appLines.push(
         `  Future<void>? _nmsWorkspaceSharingDrain${index};`,
         `  StreamSubscription<Object?>? _nmsWorkspaceSharingSync${index};`,
@@ -659,10 +660,14 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         `      if (share.awaitingRecipient) continue;`,
         `      if (share.delivered) {`,
         ...delivered,
-        `        throw StateError('No delivered receipt matches ${policy.orders.id} \${NmsInternalNomosRefs.id(order.ref)}');`,
+        ...(deliveredExhaustive
+          ? []
+          : [`        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)}');`,
+        ...(refusedExhaustive
+          ? []
+          : [`      throw StateError('No refused receipt matches ${policy.orders.id} \${NmsInternalNomosRefs.id(order.ref)}');`]),
         `    }`,
         `  }`,
         ``,
@@ -1047,7 +1052,10 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           ? sourceFieldMember.slice(0, -2)
           : `${sourceFieldMember}Ref`;
         const method = member(stem);
-        const memberNullable = field.isFromBirth !== true;
+        const memberNullable = admitsNull(field) || field.isFromBirth !== true;
+        const sourceFieldValue = admitsNull(field)
+          ? `record.${sourceFieldMember}.valueOrNull`
+          : `record.${sourceFieldMember}`;
         const isSameDomain = sameDomainRefs.some(([name]) => name === fieldName);
         const isCrossDomain = crossDomainRefs.some(([name]) => name === fieldName);
         if (!isSameDomain && !isCrossDomain) continue;
@@ -1060,7 +1068,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
             `  Future<${targetModel}?> ${method}(${sourceModel} record) async {`,
             ...(memberNullable
               ? [
-                  `    final id = record.${sourceFieldMember};`,
+                  `    final id = ${sourceFieldValue};`,
                   `    if (id == null) return null;`,
                   `    final rows = await _client.${targetById}(NmsInternalNomosRefs.id(id));`,
                 ]
@@ -1091,7 +1099,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `  Future<${targetModel}?> ${method}(${sourceModel} record) async {`,
           ...(memberNullable
             ? [
-                `    final id = record.${sourceFieldMember};`,
+                `    final id = ${sourceFieldValue};`,
                 `    if (id == null) return null;`,
                 `    final application = await ${opener}(`,
                 `      _client.bridge,`,
@@ -1103,7 +1111,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
                 `    );`,
               ]
             : [
-                `    final id = record.${sourceFieldMember};`,
+                `    final id = ${sourceFieldValue};`,
                 `    final application = await ${opener}(`,
                 `      _client.bridge,`,
                 `      id,`,
@@ -1122,7 +1130,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `  Future<${targetApplication}?> ${applicationMethod}(${sourceModel} record) {`,
           ...(memberNullable
             ? [
-                `    final id = record.${sourceFieldMember};`,
+                `    final id = ${sourceFieldValue};`,
                 `    if (id == null) return Future<${targetApplication}?>.value(null);`,
                 `    return ${opener}(`,
                 `      _client.bridge,`,
@@ -1147,12 +1155,15 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         ? contractTypeName(foreign.targetAggregateId)
         : concreteClassName(foreign.targetAggregateId);
       const fieldMember = member(fieldName);
+      const fieldValue = admitsNull(field)
+        ? `record.${fieldMember}.valueOrNull`
+        : `record.${fieldMember}`;
       const stem = fieldMember.endsWith("Id") ? fieldMember.slice(0, -2) : fieldMember;
       const 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};`,
+        `    final reference = ${fieldValue};`,
         `    if (reference == null) return null;`,
         `    final target = await NmsInternalForeignRefs.resolve(reference, _client.bridge.foreignReader());`,
         `    if (target == null) return null;`,
@@ -1175,7 +1186,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         addCollectionMember(aggregate.id, applicationMethod, [
           `  /// Open the business application containing [record]'s ${fieldName}.`,
           `  Future<${targetApplication}?> ${applicationMethod}(${sourceModel} record) {`,
-          `    final reference = record.${fieldMember};`,
+          `    final reference = ${fieldValue};`,
           `    if (reference == null) return Future<${targetApplication}?>.value(null);`,
           `    return ${opener}(`,
           `      _client.bridge,`,

package/src/codegen_dart_client.ts

@@ -62,6 +62,7 @@ import { buildNomosDescribeModel, type NomosDescribeModel } from "./describe_mod
 import { assertModelClientMemberAvailable } from "./generated_client_names.js";
 import { ownedRecordActionDirectiveId } from "./framework/owned_custody.js";
 import { contractTypeName } from "./contract.js";
+import { admitsNull } from "./null_meta.js";
 
 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);
@@ -1268,14 +1269,15 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       // the DSL schema's `.optional()` — a partial fold decodes every scalar `null` when absent
       // (`emitReadModel`'s own doc: "PARTIAL folds"), so the member is nullable UNLESS the field is
       // `.fromBirth()` (birth-presence law — the ONE case the projection types non-null).
-      const memberNullable = f.isFromBirth !== true;
+      const memberNullable = admitsNull(f) || f.isFromBirth !== true;
+      const memberValue = admitsNull(f) ? `${member}.valueOrNull` : member;
       lines.push(
         `  /// Resolve \`${fieldName}\` (${agg.id}.${fieldName} -> ${targetType}) by dispatching to`,
         `  /// [${className}.${byIdMethod}] — the existing by-id read lane, never a second one.`,
         `  Future<${targetModel}?> ${method}(${className} client) async {`,
         ...(memberNullable
           ? [
-              `    final id = ${member};`,
+              `    final id = ${memberValue};`,
               `    if (id == null) return null;`,
               `    final rows = await client.${byIdMethod}(NmsInternalNomosRefs.id(id));`,
             ]
@@ -1301,7 +1303,8 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       const member = dartMemberName(fieldName);
       const methodStem = member.length > 2 && member.endsWith("Id") ? member.slice(0, -2) : `${member}Ref`;
       const method = safeMethod(methodStem);
-      const memberNullable = f.isFromBirth !== true;
+      const memberNullable = admitsNull(f) || f.isFromBirth !== true;
+      const memberValue = admitsNull(f) ? `${member}.valueOrNull` : member;
       lines.push(
         `  /// Resolve \`${fieldName}\` (${agg.id}.${fieldName} -> ${targetType}, a CROSS-DOMAIN ref) by`,
         `  /// dispatching to [${targetClient}.${byIdMethod}] on the target domain's client — same by-id`,
@@ -1310,7 +1313,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
         `  Future<${targetModel}?> ${method}(${targetClient} client) async {`,
         ...(memberNullable
           ? [
-              `    final id = ${member};`,
+              `    final id = ${memberValue};`,
               `    if (id == null) return null;`,
               `    final rows = await client.${byIdMethod}(NmsInternalNomosRefs.id(id));`,
             ]
@@ -1341,6 +1344,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       }
       const targetConcrete = concreteClassName(targetType);
       const member = dartMemberName(fieldName);
+      const memberValue = admitsNull(f) ? `${member}.valueOrNull` : member;
       // The stored locator member is a typed `ForeignRef<Target>?` getter, so the resolver takes a
       // `remote…` name to avoid colliding with it (and to read as "the far side of the reference").
       const method = safeMethod(`remote${cap(camel(member))}`);
@@ -1350,7 +1354,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
         `  /// implementation opens the foreign workspace on demand; tenant code sees only this business method.`,
         `  /// Null locator (absent / empty id or workspace) ⇒ null.`,
         `  Future<${targetConcrete}?> ${method}(NomosEngine engine, {String? cloud}) {`,
-        `    final ref = ${member};`,
+        `    final ref = ${memberValue};`,
         `    if (ref == null) return Future<${targetConcrete}?>.value(null);`,
         `    return NmsInternalForeignRefs.resolve(ref, engine.foreignReader(cloud: cloud));`,
         `  }`,

package/src/codegen_dart_scenario.ts

@@ -192,9 +192,9 @@ export function generateDartScenario(
     `    void Function(Future<void> Function())? registerTearDown,`,
     `  }) async {`,
     `    final person = signedInAs ?? ${testPerson}.named('test');`,
-    `    final packageFile = await _applicationPackage();`,
+    `    final packageFiles = await _applicationPackages();`,
     `    final environment = await NomosTestHarness.ephemeral(`,
-    `      deployJsonPaths: [packageFile.path],`,
+    `      deployJsonPaths: packageFiles.map((file) => file.path).toList(growable: false),`,
     `      ownerSubject: person._principal,`,
     `      workspace: nmsInternalReceivingGroupNameOf(person._principal),`,
     `      nodeEntry: Platform.environment['NOMOS_NODE_ENTRY'],`,
@@ -204,7 +204,7 @@ export function generateDartScenario(
     `    final application = await ${bind}(`,
     `      environment.session(environment.workspace), NmsInternalApplicationUserBinding.fromActor(person._principal),`,
     `    );`,
-    `    final scenario = ${scenario}._(environment, person._principal, packageFile, application);`,
+    `    final scenario = ${scenario}._(environment, person._principal, packageFiles.last, application);`,
     `    registerTearDown?.call(scenario.close);`,
     `    return scenario;`,
     `  }`,
@@ -220,24 +220,27 @@ export function generateDartScenario(
     `      throw StateError('Connected scenarios require the Nomos test cloud. Run this test through githolon test.');`,
     `    }`,
     `    final applicationName = 'test-application-\${DateTime.now().microsecondsSinceEpoch}';`,
-    `    final packageFile = await _applicationPackage();`,
+    `    final packageFiles = await _applicationPackages();`,
     `    final cloud = await NomosTestCloud.start(`,
-    `      serverEntry: serverEntry, platform: applicationName, deployJsonPath: packageFile.path,`,
+    `      serverEntry: serverEntry, platform: applicationName,`,
+    `      deployJsonPaths: packageFiles.map((file) => file.path).toList(growable: false),`,
+    `      onDiagnostic: Platform.environment['NOMOS_TEST_DIAGNOSTICS'] == '1' ? stderr.writeln : null,`,
     `    );`,
     `    late final NomosTestHarness environment;`,
     `    try {`,
     `      environment = await NomosTestHarness.cloudBound(`,
-    `        cloud: cloud, deployJsonPaths: [packageFile.path],`,
+    `        cloud: cloud, deployJsonPaths: packageFiles.map((file) => file.path).toList(growable: false),`,
     `        platformWorkspace: applicationName, subject: person._principal,`,
     `        nodeEntry: Platform.environment['NOMOS_NODE_ENTRY'],`,
     `        phaseTimeout: const Duration(minutes: 2),`,
+    `        onDiagnostic: Platform.environment['NOMOS_TEST_DIAGNOSTICS'] == '1' ? stderr.writeln : null,`,
     `      );`,
     `    } catch (_) {`,
     `      await cloud.stop();`,
     `      rethrow;`,
     `    }`,
     `    final application = await ${bind}(environment.homeSession, NmsInternalApplicationUserBinding.fromActor(person._principal));`,
-    `    final scenario = ${scenario}._(environment, person._principal, packageFile, application);`,
+    `    final scenario = ${scenario}._(environment, person._principal, packageFiles.last, application);`,
     `    registerTearDown?.call(scenario.close);`,
     `    return scenario;`,
     `  }`,
@@ -273,8 +276,64 @@ export function generateDartScenario(
     `    try { await _packageFile.parent.delete(recursive: true); } catch (_) {}`,
     `  }`,
     ``,
-    `  static Future<File> _applicationPackage() async {`,
+    `  /// Resolve the whole application from its compiled OpenUSD stage. Reference-only packages are`,
+    `  /// installed on the test platform first; payload packages follow and become the child law. A`,
+    `  /// one-package project has no application stage and keeps the package-only shorthand.`,
+    `  static Future<List<File>> _applicationPackages() async {`,
     `    WidgetsFlutterBinding.ensureInitialized();`,
+    `    Directory? cursor = Directory.current.absolute;`,
+    `    File? applicationStage;`,
+    `    for (var depth = 0; depth < 10; depth++) {`,
+    `      final build = Directory('\${cursor!.path}\${Platform.pathSeparator}build');`,
+    `      if (build.existsSync()) {`,
+    `        final stages = build`,
+    `            .listSync()`,
+    `            .whereType<File>()`,
+    `            .where((file) => file.path.endsWith('.application.usda'))`,
+    `            .toList(growable: false);`,
+    `        if (stages.length > 1) {`,
+    `          throw StateError('More than one Nomos application stage is visible in \${build.path}; set one application boundary.');`,
+    `        }`,
+    `        if (stages.length == 1) { applicationStage = stages.single; break; }`,
+    `      }`,
+    `      final parent = cursor.parent;`,
+    `      if (parent.path == cursor.path) break;`,
+    `      cursor = parent;`,
+    `    }`,
+    `    if (applicationStage != null) {`,
+    `      final stage = await applicationStage.readAsString();`,
+    `      final placements = <String, bool>{};`,
+    `      final scopes = RegExp(r'def\\s+Scope\\s+"[A-Za-z_][A-Za-z0-9_]*"\\s*\\(([\\s\\S]*?)\\n\\s*\\)\\s*\\{').allMatches(stage);`,
+    `      for (final scope in scopes) {`,
+    `        final metadata = scope.group(1)!;`,
+    `        final reference = RegExp(r'prepend\\s+references\\s*=\\s*@([^@]+)@<[^>]+>').firstMatch(metadata);`,
+    `        if (reference == null) continue;`,
+    `        final payload = RegExp(r'prepend\\s+payload\\s*=\\s*@([^@]+)@<[^>]+>').hasMatch(metadata);`,
+    `        final asset = File(Uri.file(applicationStage.path).resolve(reference.group(1)!).toFilePath());`,
+    `        if (!asset.existsSync()) throw StateError('Application package asset is missing: \${asset.path}');`,
+    `        final packageAsset = await asset.readAsString();`,
+    `        final identity = RegExp(r'asset\\s+identifier\\s*=\\s*@nomos:package:([^:]+):[0-9a-f]{64}@').firstMatch(packageAsset);`,
+    `        if (identity == null) throw StateError('Application reference is not a compiled Nomos package: \${asset.path}');`,
+    `        final deploy = File('\${asset.parent.path}\${Platform.pathSeparator}\${identity.group(1)!}.deploy.json');`,
+    `        if (!deploy.existsSync()) throw StateError('Application package has no deploy body: \${deploy.path}');`,
+    `        final prior = placements[deploy.path];`,
+    `        if (prior != null && prior != payload) {`,
+    `          throw StateError('The same package is both a serving reference and deferred payload: \${deploy.path}');`,
+    `        }`,
+    `        placements[deploy.path] = payload;`,
+    `      }`,
+    `      if (placements.isEmpty) throw StateError('The application stage contains no deployable Nomos packages.');`,
+    `      final ordered = placements.entries.toList()`,
+    `        ..sort((a, b) => (a.value ? 1 : 0).compareTo(b.value ? 1 : 0));`,
+    `      final dir = await Directory.systemTemp.createTemp('nms-application-packages-');`,
+    `      final files = <File>[];`,
+    `      for (final entry in ordered) {`,
+    `        final source = File(entry.key);`,
+    `        final name = source.uri.pathSegments.last;`,
+    `        files.add(await source.copy('\${dir.path}\${Platform.pathSeparator}\$name'));`,
+    `      }`,
+    `      return files;`,
+    `    }`,
     `    final assetKeys = [`,
     `      'packages/${testPackage}/lib/src/generated/${deployFile}',`,
     `      'lib/src/generated/${deployFile}',`,
@@ -286,7 +345,7 @@ export function generateDartScenario(
     `        final dir = await Directory.systemTemp.createTemp('nms-application-package-');`,
     `        final file = File('\${dir.path}\${Platform.pathSeparator}${deployFile}');`,
     `        await file.writeAsBytes(data.buffer.asUint8List(data.offsetInBytes, data.lengthInBytes), flush: true);`,
-    `        return file;`,
+    `        return [file];`,
     `      } catch (error) {`,
     `        lastError = error;`,
     `      }`,