@githolon/dsl 0.102.1 → 0.102.2

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.2",
   "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

@@ -590,28 +590,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 +659,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)}');`]),
         `    }`,
         `  }`,
         ``,

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;`,
     `      }`,