@githolon/dsl 0.107.4 → 0.108.1

package/src/compile_package_main.ts

@@ -66,7 +66,9 @@ import type { ContractHandle } from "./contract.js";
 import { bindEnumTypeExports } from "./enum_type.js";
 import { discoverEvolutionModulePaths, isEvolutionModulePath } from "./evolution_files.js";
 import { assertEvolutionModuleExports } from "./evolution.js";
+import { readHistoricalIdentityFrontier } from "./identity_frontier.js";
 import { generateDartBridgeClient } from "./codegen_dart_client.js";
+import { generateDartApplicationFrameworkCalls } from "./codegen_dart_framework_calls.js";
 import {
   dartApplicationClassName,
   dartApplicationPublicClassNames,
@@ -88,7 +90,10 @@ import {
 } from "./framework/framework_aggregates.js";
 import { RelationTuple, relationTuplesByObject } from "./framework/relations.js";
 import { isNamespacedAggregate } from "./read_projection_namespace.js";
-import { collectPayloadValueObjectDescriptors } from "./value_object.js";
+import {
+  collectPayloadValueObjectDescriptors,
+  collectValueObjectDescriptors,
+} from "./value_object.js";
 import { finishCount, type AnyCount } from "./count.js";
 import type { QueryDecl } from "./query.js";
 import type { SpatialDecl } from "./spatial.js";
@@ -112,6 +117,7 @@ import {
   expandBusinessBirthExports,
 } from "./business_birth.js";
 import { withOwnedCustodyExports } from "./framework/owned_custody.js";
+import { OwnedCustodyValue, OwnedDeviceRequestValue } from "./framework/owned_custody_value.js";
 import { expandRoleExports, rolesOf } from "./role.js";
 import { collectEngineRouting } from "./engine_entry.js";
 import {
@@ -158,9 +164,9 @@ import {
 import { reconcileStableIdsWithIdentity } from "./stable_id_identity_bridge.js";
 import { LAW_FRAMEWORK_PARENT } from "./law_identity.js";
 import { discoverLawGraph, type LawGraph } from "./law_graph.js";
-import { emitFrameworkLawUsda, emitSparseLawGraphUsda } from "./law_graph_usda.js";
+import { compileSparseLawGraphUsda, emitFrameworkLawUsda } from "./law_graph_usda.js";
 import { assertNoDartBarrelCollisions, type BarrelExportedFile } from "./dart_barrel_guard.js";
-import { generateTsClient, tsApplicationName, tsClientFactoryName, recursiveLazyTypes } from "./codegen_ts.js";
+import { generateTsClient, generateTsLifecycleOperator, tsApplicationName, tsClientFactoryName, recursiveLazyTypes } from "./codegen_ts.js";
 import { generateOpenApiFragment, mergeOpenApiFragments } from "./codegen_openapi.js";
 import { domainInterface, type DomainInterface } from "./shape_compat.js";
 import { generateTsProof, proofLegsIndex } from "./codegen_proof.js";
@@ -174,6 +180,7 @@ import { applicationHomePolicyLaw } from "./framework/application_home.js";
 import { isApplicationHomeGenesis } from "./application_home_genesis.js";
 import { resolveApplicationTopology } from "./application_topology.js";
 import { isBusinessIntent } from "./intent.js";
+import { emitTsCallUsdaEncoder, TS_CALL_USDA_PRELUDE } from "./codegen_call_usda.js";
 import {
   compileApplicationComposition,
   isApplicationCompositionConfig,
@@ -861,11 +868,19 @@ const DART_SUPPORT_RUNTIME_SRC = [
   "webview_bridge.dart",
   "session_bound.dart",
   "record_origin.dart",
+  // Canonical USDA application-call/result syntax. Generated clients refer to
+  // these through the support barrel; omitting them from a vendored package
+  // silently resurrected the old map bridge at integration time.
+  "generated_call.dart",
+  "result_usda.dart",
 ] as const;
 const DART_SUPPORT_SRC = [...DART_SUPPORT_CORE_SRC, ...DART_SUPPORT_RUNTIME_SRC] as const;
 /** The local shim replacing `package:nomos_types/nomos_types.dart` inside vendored runtime files. */
 const VENDORED_TYPES_SHIM = "nomos_types.dart";
+const VENDORED_KERNEL_PROTOCOL_SHIM = "nomos_kernel_protocol.dart";
 const VENDORED_META_DEP = "^1.12.0";
+const VENDORED_PROTOBUF_DEP = "^5.0.0";
+const VENDORED_FIXNUM_DEP = "^1.1.1";
 const VENDORED_DART_SDK_FLOOR = "3.3.0";
 
 /**
@@ -909,21 +924,12 @@ function ensureVendoredPackageRequirements(dartOut: string): void {
       `${sdkLine[1]}\">=${VENDORED_DART_SDK_FLOOR} <4.0.0\"${sdkLine[3] ?? ""}`,
     );
   }
-  if (/^  meta:\s*/m.test(next)) {
-    if (next !== source) writeFileSync(pubspec, next, "utf8");
-    return;
-  }
-  if (!/^dependencies:\s*$/m.test(next)) {
-    fail("generated Dart vendored support needs a dependencies: block in " + pubspec);
-  }
-  writeFileSync(
-    pubspec,
-    next.replace(
-      /^dependencies:\s*$/m,
-      "dependencies:\n  meta: " + VENDORED_META_DEP,
-    ),
-    "utf8",
-  );
+  if (next !== source) writeFileSync(pubspec, next, "utf8");
+  reconcilePubspec(dir, "", {
+    meta: VENDORED_META_DEP,
+    protobuf: VENDORED_PROTOBUF_DEP,
+    fixnum: VENDORED_FIXNUM_DEP,
+  });
 }
 
 /** The generated-owned subdirectory, relative to `dartOut` (the pub package's `lib/`). WIPED and
@@ -1121,6 +1127,7 @@ function dartValueObjectsForModule(
   const byName = new Map<string, NonNullable<DomainModule["valueObjects"]>[number]>();
   for (const descriptor of [
     ...(mod.valueObjects ?? []),
+    ...collectValueObjectDescriptors(mod.aggregates),
     ...collectPayloadValueObjectDescriptors(codegenDirectives),
   ]) {
     const prior = byName.get(descriptor.name);
@@ -1180,9 +1187,23 @@ function collectDartSharedSymbols(
       }
     }
   }
+  const frameworkVoByName = new Map(
+    collectValueObjectDescriptors(frameworkAggs).map((descriptor) => [descriptor.name, descriptor]),
+  );
+  for (const [name, descriptor] of frameworkVoByName) {
+    const prior = voDescriptorByName.get(name);
+    if (prior !== undefined && JSON.stringify(prior) !== JSON.stringify(descriptor)) {
+      throw new Error(
+        `value object '${name}' has DIVERGENT framework/domain shapes — one name, one shape`,
+      );
+    }
+    voDescriptorByName.set(name, descriptor);
+  }
+  const frameworkVoNames = new Set(frameworkVoByName.keys());
   const sharedVoNames: ReadonlySet<string> = new Set([
     ...[...voDomainsByName.entries()].filter(([, n]) => n > 1).map(([name]) => name),
     ...contractVoNames,
+    ...frameworkVoNames,
   ]);
   const sharedVos = [...sharedVoNames].sort().map((name) => voDescriptorByName.get(name)!);
   const hasFrameworkSymbols =
@@ -1323,6 +1344,8 @@ function emitDart(
   modules: readonly DomainModule[],
   dartOut: string,
   domainHash: string,
+  lawGraphs: ReadonlyMap<string, LawGraph>,
+  lawPaths: ReadonlyMap<string, ReadonlyMap<string, string>>,
   packageInterface: Record<string, DomainInterface> = {},
   supportImport: DartSupportImport = "vendored",
   barrelName = "nomos_domains",
@@ -1357,9 +1380,46 @@ function emitDart(
         .replace(
           /import 'package:nomos_types\/src\/(?:nomos_ref|foreign_ref|versioned_nomos_ref)\.dart'/g,
           `import '${VENDORED_TYPES_SHIM}'`,
+        )
+        .replace(
+          /import 'package:nomos_types\/nomos_kernel_protocol\.dart'/g,
+          `import '${VENDORED_KERNEL_PROTOCOL_SHIM}'`,
         );
       writeFileSync(path.join(genDir, "src", f), src, "utf8");
     }
+    // Protobuf is the sole kernel/host message schema. Flat vendored packages receive a generated
+    // projection of that schema, never a handwritten certificate mirror. The compiler copies only the
+    // generated kernel files this runtime uses; `generate:kernel-proto-dart` remains their source.
+    const generatedKernelProto = path.join(DSL_DIR, "dart_types", "lib", "src", "proto", "nomos", "kernel", "v1");
+    const vendoredKernelProto = path.join(genDir, "src", "proto", "nomos", "kernel", "v1");
+    mkdirSync(vendoredKernelProto, { recursive: true });
+    for (const f of [
+      "kernel.pb.dart",
+      "kernel.pbenum.dart",
+      "progress.pb.dart",
+      "progress.pbenum.dart",
+    ]) {
+      copyFileSync(path.join(generatedKernelProto, f), path.join(vendoredKernelProto, f));
+    }
+    const generatedRuntimeProto = path.join(DSL_DIR, "dart_types", "lib", "src", "proto", "nomos", "runtime", "v2");
+    const vendoredRuntimeProto = path.join(genDir, "src", "proto", "nomos", "runtime", "v2");
+    mkdirSync(vendoredRuntimeProto, { recursive: true });
+    for (const f of ["runtime.pb.dart", "runtime.pbenum.dart"]) {
+      copyFileSync(path.join(generatedRuntimeProto, f), path.join(vendoredRuntimeProto, f));
+    }
+    writeFileSync(
+      path.join(genDir, "src", VENDORED_KERNEL_PROTOCOL_SHIM),
+      [
+        "// GENERATED from proto/nomos/kernel/v1/kernel.proto by nomos-compile. DO NOT EDIT.",
+        "library;",
+        "",
+        "export 'proto/nomos/kernel/v1/kernel.pb.dart';",
+        "export 'proto/nomos/kernel/v1/progress.pb.dart';",
+        "export 'proto/nomos/runtime/v2/runtime.pb.dart';",
+        "",
+      ].join("\n"),
+      "utf8",
+    );
     // The local shim the rewritten runtime imports resolve through (the vendored twin of the
     // nomos_types barrel — core files only).
     writeFileSync(
@@ -1427,10 +1487,51 @@ function emitDart(
     return p;
   };
 
+  // Compiler-owned framework ceremonies (birth policy, signer seating, genesis, invitation
+  // redemption) need the same generated USDA call types in flat/vendored output as in layered pub
+  // packages. Keeping this file private to `src/generated` gives tests and generated application
+  // infrastructure a typed setup lane without reintroducing raw payload maps.
+  const applicationFrameworkCallsSource = generateDartApplicationFrameworkCalls(
+    modules.flatMap((module) => {
+      const graph = lawGraphs.get(module.name);
+      const paths = lawPaths.get(module.name);
+      return graph === undefined || paths === undefined ? [] : [{ module, graph, paths }];
+    }),
+  );
+  if (applicationFrameworkCallsSource !== undefined) {
+    const source = supportImport === "vendored"
+      ? applicationFrameworkCallsSource
+        .replace(
+          "import 'package:nomos_types/nomos_kernel_protocol.dart' show BirthCertificate;",
+          `import 'src/${VENDORED_KERNEL_PROTOCOL_SHIM}' show BirthCertificate;`,
+        )
+        .replace(
+          "import 'package:nomos_types/nomos_types.dart' show NomosSlot, Sha256Digest;",
+          `import 'src/${VENDORED_TYPES_SHIM}' show NomosSlot, Sha256Digest;`,
+        )
+        .replace(
+          "import 'package:nomos_client/src/application_framework_calls.dart';",
+          "import 'src/application_framework_calls.dart';",
+        )
+        .replace(
+          "import 'package:nomos_client/src/generated_call.dart';",
+          "import 'src/generated_call.dart';",
+        )
+      : applicationFrameworkCallsSource;
+    const applicationFrameworkCallsPath = path.join(genDir, "application.framework_calls.dart");
+    writeFileSync(applicationFrameworkCallsPath, source, "utf8");
+    written.push(applicationFrameworkCallsPath);
+  }
+
   // 2a. the shared framework file — the framework aggregates + directives + queries, ONCE. Its own
   //     surface is emitted in full (no skip). Imported by every domain that folds any framework symbol.
   if (shared.frameworkMod !== undefined) {
-    writeGenerated(FRAMEWORK_FILE, generateDartDomain(shared.frameworkMod));
+    writeGenerated(
+      FRAMEWORK_FILE,
+      generateDartDomain(shared.frameworkMod, {
+        additionalValueObjects: shared.frameworkMod.valueObjects ?? [],
+      }),
+    );
   }
   // 2a-bis. the shared DOMAIN CONTRACTS file (`contracts.dart`) — every public DTO class, ONCE. Pure
   //         (nomos_types + VOs). A foreignRef targeting a contract imports THIS, never the concrete domain.
@@ -1523,6 +1624,10 @@ function emitDart(
 
     const clientSrc = generateDartBridgeClient(modForDart, {
       domainHash,
+      callUsda: {
+        graph: lawGraphs.get(mod.name)!,
+        paths: lawPaths.get(mod.name)!,
+      },
       interface: packageInterface[modForDart.domain ?? modForDart.name],
       ...(compat !== undefined ? { compat } : {}),
       supportImport,
@@ -1542,6 +1647,7 @@ function emitDart(
       applicationSrc,
       clientFile,
       applicationFile,
+      new Set(dartApplicationPublicClassNames(modForDart)),
     );
     const cp = path.join(genDir, clientFile);
     writeFileSync(cp, encapsulated.clientPart, "utf8");
@@ -1660,12 +1766,12 @@ const dartTypesImportFor = (generatedSource: string): string => {
  *  just the floor generated code needs — a lagging pin forces tenants into dependency_overrides. */
 // 0.3.0: SurfacedValue<T>/SurfacedObservation/PendingConflictRow — generated Surfaced-field typing +
 //        the pendingConflicts read rows.
-const NOMOS_TYPES_DEP = "^0.8.8";
+const NOMOS_TYPES_DEP = "^0.10.0";
 // 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
-const NOMOS_CLIENT_DEP = "^0.64.46";
-const NOMOS_FLUTTER_DEP = "^0.63.76";
+const NOMOS_CLIENT_DEP = "^0.65.1";
+const NOMOS_FLUTTER_DEP = "^0.64.1";
 // DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in dsl/dart/pubspec.yaml
 // and dsl/dart_types/pubspec.yaml — a Dart release without this bump fails the suite, so tenants never
 // land back in dependency_overrides (the exact co2 report this closes, third occurrence).
@@ -1728,6 +1834,7 @@ function encapsulateDartClient(
   applicationSrc: string,
   clientFile: string,
   applicationFile: string,
+  publicClientNames: ReadonlySet<string>,
 ): { readonly clientPart: string; readonly applicationLibrary: string } {
   const directive = /^(import|export)\s+'([^']+)'(?:\s+[^;]+)?;\s*$/;
   const clientImportUri = clientFile.replace(/\.dart$/, "");
@@ -1802,17 +1909,20 @@ function encapsulateDartClient(
       "// ignore_for_file: unused_element, unused_element_parameter",
       `part of '${applicationFile}';`,
       "",
-      privatize(client.body.join("\n")).trimStart(),
+      privatize(client.body.join("\n"), publicClientNames).trimStart(),
       "",
     ].join("\n"),
     applicationLibrary: [
       "// AUTO-GENERATED by nomos-compile — the sole importable application library.",
-      "// ignore_for_file: unused_import, unused_field, invalid_use_of_internal_member",
+      "// ignore_for_file: unused_import, unnecessary_import, unused_field, invalid_use_of_internal_member",
       ...imports.values(),
       ...exports.values(),
       `part '${clientFile}';`,
       "",
-      privatize(application.body.join("\n"), applicationNames).trimStart(),
+      privatize(
+        application.body.join("\n"),
+        new Set([...applicationNames, ...publicClientNames]),
+      ).trimStart(),
       "",
     ].join("\n"),
   };
@@ -1844,6 +1954,7 @@ function generatedPackageApplication(
   }[],
   homeDomain: string,
   rootDomains: readonly string[],
+  hasApplicationFrameworkCalls: boolean,
 ): string {
   const application = dartApplicationClassName(packageName);
   const root = domains.find(({ domain }) => domain === homeDomain);
@@ -1903,6 +2014,9 @@ function generatedPackageApplication(
     `import 'package:nomos_flutter/src/application_status.dart' show ApplicationSignIn, ApplicationStatus;`,
     `import 'package:nomos_client/src/nms_generated_runtime.dart' show NmsInternalUsers, NomosSession, User${hasInvitations ? ", Invitation, Recipient" : ""};`,
     `import 'package:nomos_flutter/src/generated_application_host.dart' show ApplicationModelChange, NomosApplicationStartupState, NmsInternalApplicationHost, NmsInternalApplicationUserBinding${hasInvitations ? ", NmsInternalInvitationPolicy" : ""};`,
+    ...(hasApplicationFrameworkCalls
+      ? [`import 'application.framework_calls.dart' show nomosInternalApplicationFrameworkCalls;`]
+      : []),
     ...members.map(({ file, prefix }) =>
       `import '${file}.application.dart' as ${prefix};`),
     ``,
@@ -1967,6 +2081,7 @@ function generatedPackageApplication(
           `  /// Redeem a transported invitation as [currentUser].`,
           `  Future<void> redeemInvitation(String link) => NmsInternalApplicationHost.redeemInvitation<User>(`,
           `        _nmsSession,`,
+          `        frameworkCalls: nomosInternalApplicationFrameworkCalls,`,
           `        link: link,`,
           `        identity: _nmsUser.nmsInternalActor,`,
           `        policies: [`,
@@ -2005,6 +2120,9 @@ function generatedPackageApplication(
     `    Duration startupTimeout = const Duration(minutes: 3),`,
     `  }) => NmsInternalApplicationHost.home<${application}>(`,
     `    key: key, cloud: cloud, application: application, signIn: signIn,`,
+    ...(hasApplicationFrameworkCalls
+      ? [`    frameworkCalls: nomosInternalApplicationFrameworkCalls,`]
+      : []),
     `    bind: nomosInternalBind${application}, builder: builder,`,
     `    loadingBuilder: loadingBuilder, errorBuilder: errorBuilder,`,
     `    onModelChange: onModelChange,`,
@@ -2194,6 +2312,8 @@ function emitDartPackages(
   modules: readonly DomainModule[],
   dartOut: string,
   domainHash: string,
+  lawGraphs: ReadonlyMap<string, LawGraph>,
+  lawPaths: ReadonlyMap<string, ReadonlyMap<string, string>>,
   packageInterface: Record<string, DomainInterface>,
   packages: { readonly types: string; readonly client: string; readonly test?: string; readonly compat?: string; readonly barrelExports?: "all" | "explicit" },
   names: Readonly<Record<string, string>> | undefined,
@@ -2201,6 +2321,7 @@ function emitDartPackages(
   describePackageName = packages.client,
   lawUsdzPath?: string,
   applicationMaxChildWorkspacesPerUser?: number,
+  frameworkModules: readonly DomainModule[] = modules,
 ): { written: string[]; cursed: string[] } {
   for (const [role, name] of Object.entries(packages)) {
     if (typeof name !== "string" || !isPubPackageName(name)) {
@@ -2273,7 +2394,14 @@ function emitDartPackages(
     written.push(p);
   };
 
-  if (shared.frameworkMod !== undefined) writeTypes(FRAMEWORK_FILE, generateDartDomain(shared.frameworkMod));
+  if (shared.frameworkMod !== undefined) {
+    writeTypes(
+      FRAMEWORK_FILE,
+      generateDartDomain(shared.frameworkMod, {
+        additionalValueObjects: shared.frameworkMod.valueObjects ?? [],
+      }),
+    );
+  }
   // DOMAIN CONTRACTS (layered): the shared `contracts.dart` DTO file in the TYPES package (pure —
   // nomos_types + VOs). A contract-target foreignRef imports THIS sibling, never the concrete domain.
   const contractsImportUri = packageContracts.length > 0 ? `${CONTRACTS_FILE}.dart` : undefined;
@@ -2474,6 +2602,22 @@ function emitDartPackages(
 
   // ── the CLIENT package — effectful runtime, depends on types + nomos_client ──
   const clientGen = freshGenDir(packages.client);
+  const applicationFrameworkCallsFile = "application.framework_calls";
+  const applicationFrameworkCallsSource = generateDartApplicationFrameworkCalls(
+    frameworkModules.flatMap((module) => {
+      const graph = lawGraphs.get(module.name);
+      const paths = lawPaths.get(module.name);
+      return graph === undefined || paths === undefined ? [] : [{ module, graph, paths }];
+    }),
+  );
+  if (applicationFrameworkCallsSource !== undefined) {
+    const applicationFrameworkCallsPath = path.join(
+      clientGen,
+      `${applicationFrameworkCallsFile}.dart`,
+    );
+    writeFileSync(applicationFrameworkCallsPath, applicationFrameworkCallsSource, "utf8");
+    written.push(applicationFrameworkCallsPath);
+  }
   const embeddedLawName = `${describePackageName}.law.usdz`;
   const applicationLawPath = lawUsdzPath === undefined
     ? undefined
@@ -2494,10 +2638,18 @@ function emitDartPackages(
     : undefined;
   const frameworkTypeNames = frameworkImplementationImport === undefined
     ? []
-    : [...declaredDartTypeNames(typesSources.get(FRAMEWORK_FILE) ?? "")];
+    : [...declaredDartTypeNames(typesSources.get(FRAMEWORK_FILE) ?? "")]
+      // These private framework values are supplied by nomos_client itself. A
+      // tenant implementation mentioning them must not manufacture an import of
+      // the package-local framework file's duplicate private projection helper.
+      .filter((name) => name !== OwnedCustodyValue.name && name !== OwnedDeviceRequestValue.name);
   for (const { mod, dd } of perDomain) {
     const makeClient = (imports: readonly string[]) => generateDartBridgeClient(dd.modForDart, {
       domainHash,
+      callUsda: {
+        graph: lawGraphs.get(mod.name)!,
+        paths: lawPaths.get(mod.name)!,
+      },
       ...(applicationLawAssetKey !== undefined
         ? { lawAssetKey: applicationLawAssetKey }
         : {}),
@@ -2522,6 +2674,9 @@ function emitDartPackages(
       packageAggregateDomains: buildPackageAggregateDomains(modules),
       flutterHost: true,
       tenantRoot: perDomain.length === 1,
+      ...(applicationFrameworkCallsSource === undefined
+        ? {}
+        : { applicationFrameworkCallsImportUri: `${applicationFrameworkCallsFile}.dart` }),
       ...(imports.length > 0
         ? { explicitTypeImports: imports }
         : {}),
@@ -2547,6 +2702,7 @@ function emitDartPackages(
       applicationSrc,
       clientFile,
       applicationFile,
+      new Set(dartApplicationPublicClassNames(dd.modForDart)),
     );
     const cp = path.join(clientGen, clientFile);
     writeFileSync(cp, encapsulated.clientPart, "utf8");
@@ -2577,6 +2733,7 @@ function emitDartPackages(
         })),
         topology.homeDomain,
         topology.rootDomains,
+        applicationFrameworkCallsSource !== undefined,
       ),
       "utf8",
     );
@@ -2708,6 +2865,9 @@ function emitDartPackages(
             surfaceName,
             applicationFile,
             applicationModules: perDomain.map(({ dd: candidate }) => candidate.modForDart),
+            ...(applicationFrameworkCallsSource === undefined
+              ? {}
+              : { applicationFrameworkCallsFile }),
             ...(applicationMaxChildWorkspacesPerUser === undefined
               ? {}
               : { applicationMaxChildWorkspacesPerUser }),
@@ -3074,6 +3234,13 @@ async function main(): Promise<void> {
   const nativeWorkspaceInvariantReadIds = new Set<string>();
   const routingInput: Record<string, Mod[]> = {};
   const domainModules: DomainModule[] = [];
+  const directiveExportSources: Array<{
+    readonly directive: object;
+    readonly domainKey: string;
+    readonly graphName: string;
+    readonly modulePath: string;
+    readonly exportName: string;
+  }> = [];
   // THE SELF-DESCRIBE DECLS (G1): per domain key, the FINISHED plain read/maintenance decls the
   // lump's `globalThis.describe` needs that it cannot rediscover by shape alone (mins/maxes are
   // config-named; sharding sums are framework-appended). Plain JSON (finishCount/Sum/Extremum
@@ -3171,6 +3338,13 @@ async function main(): Promise<void> {
           typeof (value as { plan?: unknown }).plan === "function" &&
           typeof (value as { aggregateId?: unknown }).aggregateId === "string"
         ) {
+          directiveExportSources.push({
+            directive: value,
+            domainKey: d.key,
+            graphName: d.name ?? d.key,
+            modulePath: abs,
+            exportName,
+          });
           directOfferExports.set((value as { id: string }).id, {
             modulePath: abs,
             exportName,
@@ -3776,6 +3950,10 @@ async function main(): Promise<void> {
   const priorLock: CompilerIdentityModel | undefined = existsSync(lockPath)
     ? parseIdentityUsda(readFileSync(lockPath, "utf8"))
     : undefined;
+  const historicalFrontier = readHistoricalIdentityFrontier(lockPath);
+  const historicalLock: CompilerIdentityModel | undefined = historicalFrontier === undefined
+    ? undefined
+    : parseIdentityUsda(historicalFrontier.source);
   const inferredRenames: { domain: string; renames: InferredRename[] }[] = [];
   let nextIdentity = identityRegistryFromModel(priorLock);
   const typedLawGraphs = new Map<string, LawGraph>();
@@ -3831,6 +4009,7 @@ async function main(): Promise<void> {
       currentAggs,
       prior,
       priorSchemas,
+      mod.retirements,
     );
     const reconciled = reconcileStableIdsWithIdentity(
       nextIdentity,
@@ -3924,9 +4103,9 @@ async function main(): Promise<void> {
   // The identity file is project-wide while a package may own only some of its domains. Scope the
   // prior side to the modules in this compile so compiling one sibling never reads another sibling's
   // absence as a domain retirement.
-  if (priorLock !== undefined) {
+  if (historicalLock !== undefined) {
     const priorDomainsForPackage: CompilerIdentityModel["domains"] = {};
-    const priorIdentity = identityRegistryFromModel(priorLock);
+    const priorIdentity = identityRegistryFromModel(historicalLock);
     const frameworkAggregateSids = new Set(
       Object.values(priorIdentity.entities)
         .filter((entity) => entity.kind === "aggregate" && entity.parent === LAW_FRAMEWORK_PARENT)
@@ -3934,7 +4113,7 @@ async function main(): Promise<void> {
     );
     for (const mod of domainModules) {
       const domainKey = mod.domain ?? mod.name;
-      const locked = priorLock.domains[mod.name] ?? priorLock.domains[domainKey];
+      const locked = historicalLock.domains[mod.name] ?? historicalLock.domains[domainKey];
       if (locked !== undefined) {
         const currentImplementationDetailAggregateIds = new Set(
           mod.aggregates
@@ -3972,7 +4151,7 @@ async function main(): Promise<void> {
     const priorLaw = evolveLawFromLockfile({
       v: 1,
       domains: priorDomainsForPackage,
-      ...(priorLock.identity === undefined ? {} : { identity: priorLock.identity }),
+      ...(historicalLock.identity === undefined ? {} : { identity: historicalLock.identity }),
     });
     const candidateLaw = currentEvolveLaw(domainModules, nextLock);
     const evolutionFindings = evolveDiff(priorLaw, candidateLaw).findings;
@@ -4062,10 +4241,12 @@ async function main(): Promise<void> {
   const v3Closure = [...typedLawGraphs.values()];
   const v3DomainAssets: EmittedLawClosureAsset[] = [];
   const typedDomainIdentityByName = new Map<string, string>();
+  const typedLawPathsByName = new Map<string, ReadonlyMap<string, string>>();
   for (const [domain, graph] of typedLawGraphs) {
     const safeDomain = domain.replace(/[^A-Za-z0-9._-]/g, "_");
     const logicalPath = `domains/${safeDomain}.usda`;
-    const layerText = emitSparseLawGraphUsda(graph, logicalPath, v3Closure);
+    const compiledLayer = compileSparseLawGraphUsda(graph, logicalPath, v3Closure);
+    const layerText = compiledLayer.text;
     const sha256 = sha256HexUtf8(layerText);
     v3DomainAssets.push({
       logicalPath,
@@ -4073,6 +4254,66 @@ async function main(): Promise<void> {
       utf8: layerText,
     });
     typedDomainIdentityByName.set(domain, sha256);
+    typedLawPathsByName.set(domain, compiledLayer.paths);
+  }
+
+  // Cross-workspace effects retain the exact target Directive object in the typed application
+  // language. Resolve that object back to its configured export once, then generate its nominal
+  // USDA encoder from the target's own canonical graph. Runtime law receives no schema descriptor,
+  // operation string or host mapping: only one generated function per exact target declaration.
+  const workspaceEffectRuntimeBindings: Array<{
+    readonly sourceDomain: string;
+    readonly sourceModulePath: string;
+    readonly sourceExportName: string;
+    readonly targetModulePath: string;
+    readonly targetExportName: string;
+    readonly encoderName: string;
+    readonly encoderSource: readonly string[];
+  }> = [];
+  for (const module of domainModules) {
+    const sourceDomain = module.domain ?? module.name;
+    for (const directive of module.directives ?? []) {
+      if (!isBusinessIntent(directive)) continue;
+      for (const effect of directive.workspaceEffects) {
+        const sourceMatches = directiveExportSources.filter((candidate) => candidate.directive === directive);
+        if (sourceMatches.length !== 1) {
+          fail(
+            `workspace effect source '${sourceDomain}/${directive.id}' is exported by ` +
+              `${sourceMatches.length} configured law modules; export it once`,
+          );
+        }
+        const source = sourceMatches[0]!;
+        const matches = directiveExportSources.filter((candidate) => candidate.directive === effect.target);
+        if (matches.length !== 1) {
+          fail(
+            `workspace effect '${sourceDomain}/${directive.id}' targets '${effect.target.id}', but that exact ` +
+              `Directive object is exported by ${matches.length} configured law modules; export it once`,
+          );
+        }
+        const target = matches[0]!;
+        const graph = typedLawGraphs.get(target.graphName);
+        const paths = typedLawPathsByName.get(target.graphName);
+        if (graph === undefined || paths === undefined) {
+          fail(`workspace effect target '${target.graphName}/${effect.target.id}' has no canonical law graph`);
+        }
+        const generated = emitTsCallUsdaEncoder(
+          graph,
+          paths,
+          target.domainKey,
+          effect.target.id,
+          "any",
+        );
+        workspaceEffectRuntimeBindings.push({
+          sourceDomain,
+          sourceModulePath: source.modulePath,
+          sourceExportName: source.exportName,
+          targetModulePath: target.modulePath,
+          targetExportName: target.exportName,
+          encoderName: generated.functionName,
+          encoderSource: generated.source,
+        });
+      }
+    }
   }
 
   // ── reports ──
@@ -4152,11 +4393,13 @@ async function main(): Promise<void> {
     }
   }
 
-  // Resolve esbuild through Node's resolver (caller's copy first, else the DSL's
-  // own dependency) — NOT node_modules/.bin paths, which hoisted/workspace
-  // installs relocate. The pinned dependency keeps the engine-lump bytes (and so
-  // the content-addressed domainHash) reproducible across machines.
-  const esbuildPkgJson = [cfgDir, DSL_DIR]
+  // Resolve the compiler's pinned esbuild before any application-local copy.
+  // Application dependencies are authoring inputs, not part of the compiler
+  // toolchain: allowing a stray nested node_modules to win makes identical law
+  // source emit a different content-addressed runtime than a clean checkout.
+  // Node's resolver still handles hoisted/workspace installs without relying on
+  // node_modules/.bin paths.
+  const esbuildPkgJson = [DSL_DIR, cfgDir]
     .map((dir) => {
       try {
         return createRequire(pathToFileURL(path.join(dir, "noop.js"))).resolve("esbuild/package.json");
@@ -4168,7 +4411,9 @@ async function main(): Promise<void> {
   if (!esbuildPkgJson) fail(`esbuild not found — reinstall @githolon/dsl (esbuild is one of its dependencies)`);
   const esbuildMod = (await import(pathToFileURL(path.join(path.dirname(esbuildPkgJson), "lib", "main.js")).href)) as typeof import("esbuild");
 
-  const compact = compactFlag || cfg.compact === true;
+  const compact = process.env.NOMOS_READABLE === "1"
+    ? false
+    : compactFlag || cfg.compact === true;
   const runtimeZodPath = path.join(DSL_DIR, "src", "runtime_zod.ts");
   const runtimeZodPackage = createRequire(import.meta.url).resolve("zod/package.json");
   const runtimeZodV4Path = path.join(path.dirname(runtimeZodPackage), "v4", "index.js");
@@ -4255,6 +4500,41 @@ async function main(): Promise<void> {
       ),
     };
   };
+  const workspaceEffectRuntimeFor = (
+    domainKeys: readonly string[],
+    sourceSlice?: readonly PlanSourceSliceTarget[],
+  ) => {
+    const wanted = new Set(domainKeys);
+    const slicedSources = sourceSlice === undefined
+      ? undefined
+      : new Set(sourceSlice.map((target) => `${target.modulePath}\0${target.exportName}`));
+    const selected = workspaceEffectRuntimeBindings.filter((binding) =>
+      wanted.has(binding.sourceDomain) &&
+      (slicedSources === undefined ||
+        slicedSources.has(`${binding.sourceModulePath}\0${binding.sourceExportName}`))
+    );
+    const unique = [...new Map(selected.map((binding) => [
+      `${binding.targetModulePath}\0${binding.targetExportName}`,
+      binding,
+    ])).values()];
+    return {
+      selected: unique,
+      declarations: unique.length === 0
+        ? []
+        : [...TS_CALL_USDA_PRELUDE, ...unique.flatMap((binding) => binding.encoderSource), ""],
+      config: unique.length === 0
+        ? []
+        : [
+            `  workspaceEffectTargets: [`,
+            ...unique.map((binding) =>
+              `    { target: require(${JSON.stringify(binding.targetModulePath)})` +
+              `[${JSON.stringify(binding.targetExportName)}] as any, encode: (payload: unknown, workspace: string) => ` +
+              `${binding.encoderName}(payload as any, workspace).canonicalUsda },`
+            ),
+            `  ],`,
+          ],
+    };
+  };
   const planEntrySource = (
     domainKeys: readonly string[],
     includeReports: boolean,
@@ -4265,13 +4545,16 @@ async function main(): Promise<void> {
     routedDomainFallback?: string,
     includeMintInstalls = true,
     sharedRuntime = false,
+    sourceSlice?: readonly PlanSourceSliceTarget[],
   ): string => {
+    const workspaceEffects = workspaceEffectRuntimeFor(domainKeys, sourceSlice);
     return [
       `// AUTO-GENERATED Nomos plan asset from ${path.basename(configPath)} — do not edit.`,
       `declare function require(id: string): Record<string, unknown>;`,
       ...(sharedRuntime ? [] : zodSeedImports),
       `import { registerEngine } from "@githolon/dsl/engine-entry";`,
       ``,
+      ...workspaceEffects.declarations,
       `registerEngine({`,
       `  domains: {`,
       ...domainKeys.map((key) => {
@@ -4295,6 +4578,7 @@ async function main(): Promise<void> {
       ...(!sharedRuntime && zodSeedNames.length > 0 ? [`  seeds: [${zodSeedNames.join(", ")}],`] : []),
       ...(includeDescribe ? [`  openapiDocument: ${JSON.stringify(runtimeOpenApiDocument)},`] : []),
       ...(includeDescribe ? [`  packageTitle: ${JSON.stringify(`${cfg.name} (nomos package)`)},`] : []),
+      ...workspaceEffects.config,
       `});`,
       ...(includeMintInstalls
         ? domainKeys.flatMap((key) => {
@@ -4426,11 +4710,21 @@ async function main(): Promise<void> {
     } = {},
   ): Promise<UsdPlanAsset> => {
     const ordered = orderedDomainKeys.filter((key) => domainKeys.includes(key));
+    const selectedWorkspaceEffects = workspaceEffectRuntimeFor(ordered, options.sliceTargets);
+    const effectiveSliceTargets = options.sliceTargets === undefined
+      ? undefined
+      : [...new Map([
+          ...options.sliceTargets,
+          ...selectedWorkspaceEffects.selected.map((binding) => ({
+            modulePath: binding.targetModulePath,
+            exportName: binding.targetExportName,
+          })),
+        ].map((target) => [`${target.modulePath}\0${target.exportName}`, target] as const)).values()];
     const signature = JSON.stringify({
       domains: ordered,
       reports: includeReports,
       describe: includeDescribe,
-      slice: options.sliceTargets?.map((target) => [target.modulePath, target.exportName]) ?? null,
+      slice: effectiveSliceTargets?.map((target) => [target.modulePath, target.exportName]) ?? null,
       cacheKey: options.cacheKey ?? null,
     });
     const hit = planBySignature.get(signature);
@@ -4446,6 +4740,7 @@ async function main(): Promise<void> {
         options.routedDomainFallback,
         options.includeMintInstalls ?? true,
         true,
+        options.sliceTargets,
       ));
     let planProfile: readonly { readonly module: string; readonly bytesInOutput: number }[] | undefined;
     const profilePlan = process.env.NOMOS_PROFILE_PLANS === "1";
@@ -4486,9 +4781,9 @@ async function main(): Promise<void> {
         external: [...sharedRuntimeModuleIds],
         metafile: true,
         logLevel: "silent",
-        ...(options.sliceTargets === undefined
+        ...(effectiveSliceTargets === undefined
           ? {}
-          : { plugins: [planSourceSlicer.plugin(options.sliceTargets)] }),
+          : { plugins: [planSourceSlicer.plugin(effectiveSliceTargets)] }),
       });
       rmSync(sourcePath, { force: true });
       const output = result.outputFiles?.[0];
@@ -4940,7 +5235,7 @@ async function main(): Promise<void> {
         `    for (const [domain, directiveId] of workerData.checks) {`,
         `      let found;`,
         `      try { found = globalThis.__nomosHasDirective(domain, directiveId); }`,
-        `      catch (e) { parentPort.postMessage({ domain, error: String((e && e.message) || e) }); return; }`,
+        `      catch (e) { parentPort.postMessage({ domain, error: String((e && (e.stack || e.message)) || e) }); return; }`,
         `      if (directiveId !== "" && found !== true) {`,
         `        parentPort.postMessage({ domain, error: "routed offer '" + directiveId + "' is absent from its selected plan registry" });`,
         `        return;`,
@@ -4948,7 +5243,7 @@ async function main(): Promise<void> {
         `    }`,
         `    parentPort.postMessage({ ok: true });`,
         `  } catch (e) {`,
-        `    parentPort.postMessage({ domain: workerData.checks[0]?.[0] || "?", error: String((e && e.message) || e) });`,
+        `    parentPort.postMessage({ domain: workerData.checks[0]?.[0] || "?", error: String((e && (e.stack || e.message)) || e) });`,
         `  }`,
         `} else {`,
         `  const jobs = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));`,
@@ -5349,6 +5644,8 @@ async function main(): Promise<void> {
   const clientDeclarationPath = path.join(outDir, `${cfg.name}.client.d.mts`);
   const headlessClientPath = path.join(outDir, `${cfg.name}.headless.mjs`);
   const headlessClientDeclarationPath = path.join(outDir, `${cfg.name}.headless.d.mts`);
+  const operatorPath = path.join(outDir, `${cfg.name}.operator.mjs`);
+  const operatorDeclarationPath = path.join(outDir, `${cfg.name}.operator.d.mts`);
   const clientOptions = {
     packageName: cfg.name,
     domainHash,
@@ -5356,12 +5653,18 @@ async function main(): Promise<void> {
     interface: packageInterface,
     compat: nomosCompat,
     homeDomain: resolveApplicationTopology(presentationDomainModules).homeDomain,
+    callUsda: [...typedLawGraphs].map(([name, graph]) => {
+      const paths = typedLawPathsByName.get(name);
+      if (paths === undefined) throw new Error(`domain '${name}' has no rendered USDA path index`);
+      return { graph, paths };
+    }),
   } as const;
   const clientSource = generateTsClient(presentationDomainModules, clientOptions);
   const headlessClientSource = generateTsClient(presentationDomainModules, {
     ...clientOptions,
     exportHolonFactory: true,
   });
+  const operatorSource = generateTsLifecycleOperator(clientOptions.callUsda);
   const runtimePath = path.join(DSL_DIR, "runtime", "generated-application-host.js");
   if (!existsSync(runtimePath)) {
     fail("the compiler-private generated application runtime is missing — reinstall @githolon/dsl");
@@ -5378,7 +5681,7 @@ async function main(): Promise<void> {
   const temporaryHeadlessDeclarationPath = temporaryHeadlessClientPath.replace(/\.ts$/, ".d.ts");
   const runtimeTypesSource = [
     `export declare function nomosInternalOpenGeneratedApplication<T extends object>(`,
-    `  options: { cloud: string; application: string; signIn: (request?: { readonly deviceChallenge?: string }) => Promise<string>; onPerformance?: (sample: { readonly operation: "open" | "offer" | "birth" | "read" | "sync" | "maintenance"; readonly name: string; readonly durationMs: number; readonly domain?: string; readonly directive?: string }) => void; approveModel?: (decision: { readonly summary: string; readonly review: { checkedActions: number; candidateActions: number; sameOutcome: boolean | null; differences: { kind: "rules" | "outcome" | "evidence"; area?: string; action?: string; summary: string }[] } }) => Promise<{ readonly because: string }>; lawHash: string; readyCommands?: readonly { readonly domain: string; readonly packageHash: string; readonly directiveId: string }[] },`,
+    `  options: { cloud: string; application: string; signIn: (request?: { readonly deviceChallenge?: string }) => Promise<string>; onPerformance?: (sample: { readonly operation: "open" | "offer" | "birth" | "read" | "sync" | "maintenance"; readonly name: string; readonly durationMs: number; readonly domain?: string; readonly directive?: string }) => void; approveModel?: (decision: { readonly summary: string; readonly review: { checkedActions: number; candidateActions: number; sameOutcome: boolean | null; differences: { kind: "rules" | "outcome" | "evidence"; area?: string; action?: string; summary: string }[] } }) => Promise<{ readonly because: string }>; lawHash: string; readyCommands?: readonly { readonly domain: string; readonly packageHash: string; readonly directiveId: string }[]; frameworkCalls: unknown },`,
     `  bind: (holon: unknown, user: { readonly identityId: string; readonly identityAddress: string }) => T,`,
     `): Promise<T & {`,
     `  currentStatus(): Promise<any>;`,
@@ -5396,6 +5699,7 @@ async function main(): Promise<void> {
     `  holon: unknown,`,
     `  link: string,`,
     `  policies: readonly { readonly domain: string; readonly domainHash: string; readonly query: string; readonly redeem: string; readonly personField: string; readonly roleField: string; readonly scopeField: string }[],`,
+    `  frameworkCalls: unknown,`,
     `): Promise<void>;`,
     ``,
   ].join("\n");
@@ -5705,6 +6009,47 @@ async function main(): Promise<void> {
     if (!new RegExp(`export\\s*\\{[^}]*${tsClientFactoryName(resolveApplicationTopology(presentationDomainModules).homeDomain)}`, "s").test(headlessBundled)) {
       fail("generated headless application omitted its structural holon factory");
     }
+    if (operatorSource !== undefined) {
+    const operatorDeclaration = ts.transpileDeclaration(operatorSource, {
+      fileName: `${cfg.name}.operator.ts`,
+      compilerOptions: {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.ESNext,
+        strict: true,
+      },
+      reportDiagnostics: true,
+    });
+    const operatorErrors = (operatorDeclaration.diagnostics ?? []).filter(
+      (diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error,
+    );
+    if (operatorErrors.length > 0) {
+      fail(`generated TypeScript lifecycle operator declarations are invalid — this is a Nomos codegen bug:\n${operatorErrors.map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n")).join("\n")}`);
+    }
+    writeFileSync(operatorDeclarationPath, operatorDeclaration.outputText, "utf8");
+    await esbuildMod.build({
+      stdin: {
+        contents: operatorSource,
+        loader: "ts",
+        resolveDir: outDir,
+        sourcefile: `${cfg.name}.operator.ts`,
+      },
+      outfile: operatorPath,
+      bundle: true,
+      platform: "neutral",
+      format: "esm",
+      target: "es2022",
+      legalComments: "none",
+      logLevel: "silent",
+    });
+    writeFileSync(
+      operatorPath,
+      canonicalizeGeneratedClientJavascript(readFileSync(operatorPath, "utf8")),
+      "utf8",
+    );
+    } else {
+      rmSync(operatorPath, { force: true });
+      rmSync(operatorDeclarationPath, { force: true });
+    }
   } catch (e) {
     fail(`generated TypeScript application could not be sealed — this is a Nomos codegen bug: ${(e as Error).message}`);
   } finally {
@@ -5761,8 +6106,9 @@ async function main(): Promise<void> {
     // restores the prior good packages instead of leaving them wiped/partial. Finalized at process exit.
     if (dartPackages !== undefined) {
       const r = emitDartPackages(
-        presentationDomainModules, dartOut, domainHash, packageInterface, dartPackages,
+        presentationDomainModules, dartOut, domainHash, typedLawGraphs, typedLawPathsByName, packageInterface, dartPackages,
         dartNames, nomosCompat, cfg.name, lawUsdzPath, cfg.application?.maxChildWorkspacesPerUser,
+        closedDomainModules,
       );
       dartFiles = r.written;
       dartCursedHints = r.cursed;
@@ -5776,7 +6122,7 @@ async function main(): Promise<void> {
         .replace(/^(?=[0-9])/, "n");
       const dartBarrel =
         typeof dartCfg === "object" && dartCfg.barrel !== undefined ? dartCfg.barrel : defaultBarrel;
-      dartFiles = emitDart(presentationDomainModules, dartOut, domainHash, packageInterface, dartSupportImport, dartBarrel, nomosCompat, dartNames, cfg.name);
+      dartFiles = emitDart(presentationDomainModules, dartOut, domainHash, typedLawGraphs, typedLawPathsByName, packageInterface, dartSupportImport, dartBarrel, nomosCompat, dartNames, cfg.name);
     }
     // COMPILE-VALID MUST MEAN COMPILABLE (co2): `githolon compile` reported success while the generated Dart
     // had hard compiler errors (a duplicate id symbol, missing contract-id defs). Run `dart analyze` over the