@githolon/dsl 0.105.13 → 0.105.15

package/src/build_package.ts

@@ -27,6 +27,7 @@ import { createHash } from "node:crypto";
 import { z } from "zod";
 
 import type { AggregateHandle } from "./aggregate.js";
+import type { Field } from "./fields.js";
 import type { Directive } from "./directive.js";
 import type { DomainModule, PermissionVocabulary, DartImport } from "./codegen_dart.js";
 import type { AnyCount } from "./count.js";
@@ -83,6 +84,11 @@ import {
   applyConflictPolicyResolvers,
   conflictPoliciesOf,
 } from "./conflicts.js";
+import {
+  applyFieldEvolutionsToAggregates,
+  fieldEvolutionsOf,
+  retirementsOf,
+} from "./evolution.js";
 import {
   expandBusinessBirthExports,
   isBusinessBirthDirective,
@@ -200,6 +206,8 @@ export interface DomainModuleSpec {
 export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   const domain = spec.domain ?? spec.name;
   const conflictPolicies = conflictPoliciesOf(spec.modules, domain);
+  const fieldEvolutions = fieldEvolutionsOf(spec.modules);
+  const retirements = retirementsOf(spec.modules, domain);
   const applicationLanguage = applicationLanguageOf(spec.modules, domain);
   let merged: Mod = {};
   for (const m of spec.modules) merged = { ...merged, ...m };
@@ -520,11 +528,34 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
     directives.push(dir);
     autoDeclaredEnsures.push(ty);
   }
-  const aggregates = applyConflictPoliciesToAggregates(
-    [...byId.values()],
-    conflictPolicies,
+  const aggregates = applyFieldEvolutionsToAggregates(
+    applyConflictPoliciesToAggregates(
+      [...byId.values()],
+      conflictPolicies,
+      domain,
+    ),
+    fieldEvolutions,
     domain,
   );
+  const currentAggregates = new Map(aggregates.map((aggregate) => [aggregate.id, aggregate]));
+  for (const retired of retirements) {
+    const current = currentAggregates.get(retired.aggregate);
+    if (retired.kind === "aggregate" && current !== undefined) {
+      throw new Error(
+        `domain '${domain}' declares '${retired.aggregate}' both current and retired`,
+      );
+    }
+    if (
+      retired.kind === "field" &&
+      current !== undefined &&
+      retired.field !== undefined &&
+      (current.fields as Record<string, Field>)[retired.field] !== undefined
+    ) {
+      throw new Error(
+        `domain '${domain}' declares '${retired.aggregate}.${retired.field}' both current and retired`,
+      );
+    }
+  }
   const directiveIds = new Set(directives.map((d) => d.id));
   for (const task of declaredCapabilities) {
     for (const directive of [task.obligation, task.complete, task.fail, task.block, task.deadLetter]) {
@@ -855,6 +886,9 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
     // hash-bearing manifest; payload-field tracing also drives generated typed references.
     // Omit-when-empty because ordinary domains need no resolver metadata.
     ...(surfacedResolvers.length > 0 ? { surfacedResolvers } : {}),
+    // Explicit authored tombstones are law. The compiler identity registry may remember
+    // every disappearance, but only these declarations permit an activation to retire it.
+    ...(retirements.length > 0 ? { retirements } : {}),
     ...(queries.length > 0 ? { queries } : {}),
     ...(counts.length > 0 ? { counts } : {}),
     ...(spatials.length > 0 ? { spatials } : {}),

package/src/check_package_main.ts

@@ -17,6 +17,8 @@ import { pathToFileURL } from "node:url";
 import { composeDomainModule, type Mod } from "./build_package.js";
 import type { DomainModule } from "./codegen_dart.js";
 import { bindEnumTypeExports } from "./enum_type.js";
+import { discoverEvolutionModulePaths, isEvolutionModulePath } from "./evolution_files.js";
+import { assertEvolutionModuleExports } from "./evolution.js";
 import { checkDomainModules, formatFindings, hasRefusal, type Finding } from "./law_check.js";
 import { LawSourceMap } from "./law_source_map.js";
 import {
@@ -105,9 +107,18 @@ export async function loadComposedModulesWithSources(
     const files: string[] = [];
     for (const rel of d.modules) {
       const abs = path.resolve(cfgDir, rel);
+      if (isEvolutionModulePath(abs)) {
+        fail(
+          `domain '${d.key}': ${rel} is an evolution concern; move it under ` +
+            `evolutions/${d.key}/ and remove it from feature modules so it cannot enter QuickJS`,
+        );
+      }
       if (!existsSync(abs)) fail(`domain '${d.key}': module not found: ${abs}`);
       files.push(abs);
     }
+    for (const abs of discoverEvolutionModulePaths(cfgDir, d.key)) {
+      if (!files.includes(abs)) files.push(abs);
+    }
     try {
       assertPublicPackageImports(files);
     } catch (error) {
@@ -116,6 +127,7 @@ export async function loadComposedModulesWithSources(
     for (const abs of files) {
       // Cache-bust so a re-import (the LSP re-check after an edit) re-evaluates the edited module.
       const mod = (await import(`${pathToFileURL(abs).href}?t=${Date.now()}`)) as Mod;
+      if (isEvolutionModulePath(abs)) assertEvolutionModuleExports(mod, abs);
       bindEnumTypeExports(mod, abs);
       mods.push(mod);
     }
@@ -201,7 +213,6 @@ async function main(): Promise<void> {
   const findings: Finding[] = [...dependencyFindings, ...checkDomainModules(modules)];
 
   // ── EVOLVE PREVIEW (--against): diff the current build against a prior law + pre-fire the gate. ──
-  let evolveDispositions: Record<string, unknown> | undefined;
   if (againstIdx >= 0 || againstArg !== undefined) {
     if (againstArg === undefined || againstArg.startsWith("--")) {
       fail(`--against needs a path: --against <${NOMOS_IDENTITY_FILENAME} | package dir>`);
@@ -218,7 +229,6 @@ async function main(): Promise<void> {
     const current = currentEvolveLaw(modules, lock);
     const diff = evolveDiff(prior.law, current);
     findings.push(...diff.findings);
-    if (Object.keys(diff.dispositions).length > 0) evolveDispositions = diff.dispositions;
     if (!asJson) console.log(`githolon check: evolve preview against ${prior.source}`);
   }
 
@@ -255,14 +265,6 @@ async function main(): Promise<void> {
   }
   if (findings.length === 0) console.log("  all clear — no static twin flagged anything");
 
-  // The consolidated, pasteable dispositions the destructive evolves demand (per domain).
-  if (evolveDispositions !== undefined) {
-    console.log(
-      "\ngitholon check: to admit the destructive evolve, include `dispositions` in the installation offer:",
-    );
-    console.log(JSON.stringify(evolveDispositions, null, 2));
-  }
-
   process.exit(hasRefusal(findings) ? 1 : 0);
 }
 

package/src/codegen_dart.ts

@@ -2742,14 +2742,14 @@ export function generateDartActivityRegistry(entries: readonly PackageActivityEn
     `  final String summary;`,
     `  final NomosModelReview review;`,
     `  final Future<NomosModelAdoption> Function()? _stage;`,
-    `  final Future<NomosModelAdoption> Function(String, {Map<String, Object?>? dispositions})? _accept;`,
+    `  final Future<NomosModelAdoption> Function(String)? _accept;`,
     `  const NomosModelAdoption.adopted({required this.summary, required this.review})`,
     `      : status = NomosModelAdoptionStatus.adopted, _stage = null, _accept = null;`,
     `  const NomosModelAdoption.blocked({required this.summary, required this.review})`,
     `      : status = NomosModelAdoptionStatus.blocked, _stage = null, _accept = null;`,
     `  NomosModelAdoption.needsStaging({required this.summary, required this.review, required Future<NomosModelAdoption> Function() stage})`,
     `      : status = NomosModelAdoptionStatus.needsStaging, _stage = stage, _accept = null;`,
-    `  NomosModelAdoption.needsDecision({required this.summary, required this.review, required Future<NomosModelAdoption> Function(String, {Map<String, Object?>? dispositions}) accept})`,
+    `  NomosModelAdoption.needsDecision({required this.summary, required this.review, required Future<NomosModelAdoption> Function(String) accept})`,
     `      : status = NomosModelAdoptionStatus.needsDecision, _stage = null, _accept = accept;`,
     `  Future<NomosModelAdoption> stage() {`,
     `    final stageCandidate = _stage;`,
@@ -2758,14 +2758,14 @@ export function generateDartActivityRegistry(entries: readonly PackageActivityEn
     `    }`,
     `    return stageCandidate();`,
     `  }`,
-    `  Future<NomosModelAdoption> accept(String because, {Map<String, Object?>? dispositions}) {`,
+    `  Future<NomosModelAdoption> accept(String because) {`,
     `    final reason = because.trim();`,
     `    final acceptDecision = _accept;`,
     `    if (status != NomosModelAdoptionStatus.needsDecision || acceptDecision == null) {`,
     `      throw StateError('This model change is not waiting for a business decision.');`,
     `    }`,
     `    if (reason.isEmpty) throw ArgumentError('accept(reason) needs the business reason for changing prior outcomes');`,
-    `    return acceptDecision(reason, dispositions: dispositions);`,
+    `    return acceptDecision(reason);`,
     `  }`,
     `}`,
     ``,
@@ -4788,6 +4788,9 @@ export interface DomainModule {
    * Absent when the domain declares no Surfaced field (byte-identical — the era rule).
    */
   surfacedResolvers?: import("./surfaced_lint.js").SurfacedResolverBinding[];
+  /** Explicit tombstones authored in separate evolution files. These compile into
+   * candidate USDA and are never exposed through generated tenant clients. */
+  retirements?: import("./evolution.js").Retirement[];
   /**
    * STABLE-ID CONTINUITY (#58 — names are labels, identity is minted). When present
    * (attached by `nomos-compile` from the PRIOR build's identity manifests), the

package/src/codegen_dart_client.ts

@@ -1673,11 +1673,11 @@ export function generateDartBridgeClient(
       `      sameOutcome: projection?['equal'] as bool?, differences: differences);`,
       `  }`,
       ``,
-      `  Future<NomosModelAdoption> _adoptGeneratedModel([String? because, Map<String, Object?>? dispositions]) async {`,
+      `  Future<NomosModelAdoption> _adoptGeneratedModel([String? because]) async {`,
       `    final raw = await bridge.nomosFrameworkAdoptGeneratedModel(`,
       `      domain: ${dartStr(
         domain
-      )}, candidateHash: domainHash, because: because, dispositions: dispositions);`,
+      )}, candidateHash: domainHash, because: because);`,
       `    final reportRaw = raw['report'];`,
       `    final report = reportRaw is Map ? reportRaw.cast<String, Object?>() : null;`,
       `    final review = _nomosModelReview(report);`,
@@ -1703,20 +1703,9 @@ export function generateDartBridgeClient(
       `    if (stage == 'acceptance') {`,
       `      return NomosModelAdoption.needsDecision(`,
       `        summary: 'This model would change prior business outcomes. Review the differences and record why that is intended.',`,
-      `        review: review, accept: (reason, {dispositions}) => _adoptGeneratedModel(reason, dispositions));`,
+      `        review: review, accept: (reason) => _adoptGeneratedModel(reason));`,
       `    }`,
       `    final evolve = (report?['evolve'] as Map?)?.cast<String, Object?>();`,
-      `    // A field/aggregate the candidate genuinely removed is a #58 disposition decision, not a`,
-      `    // dead end: retry with the SAME accept/dispositions seam so the tenant's own policy can`,
-      `    // supply dispositions.retired. Every prior stage (promoted/staging-required/acceptance) is`,
-      `    // already handled above; 'identity' (needs sign-in) is the one remaining stage this must NOT`,
-      `    // paper over, so it is the sole exclusion rather than requiring an exact 'preflight' match or`,
-      `    // exact boolean report fields, which may not round-trip identically across every bridge.`,
-      `    if (stage != 'identity') {`,
-      `      return NomosModelAdoption.needsDecision(`,
-      `        summary: 'This model cannot yet interpret every existing value without a declared disposition. Review the differences and record why that is intended.',`,
-      `        review: review, accept: (reason, {dispositions}) => _adoptGeneratedModel(reason, dispositions));`,
-      `    }`,
       `    final rawError = raw['error']?.toString().trim();`,
       `    final summary = rawError != null && rawError.isNotEmpty`,
       `        ? rawError`,
@@ -2436,8 +2425,8 @@ export function generateDartBridgeClient(
           `            : null,`,
         ]),
     `        accept: adoption.status == NomosModelAdoptionStatus.needsDecision`,
-    `            ? (reason, {dispositions}) async {`,
-    `                final accepted = await adoption.accept(reason, dispositions: dispositions);`,
+    `            ? (reason) async {`,
+    `                final accepted = await adoption.accept(reason);`,
     `                // A retry that still isn't adopted (a transient business-outcome/history race,`,
     `                // e.g. concurrent writes landing between the bare preflight and this accept) must`,
     `                // NOT be swallowed as a terminal StateError: re-throw the SAME typed exception so`,

package/src/codegen_ts.ts

@@ -751,6 +751,9 @@ export interface TsClientOptions {
   readonly packageName: string;
   /** Content identity of the built typed USDA closure (`.law.usdz`). */
   readonly domainHash: string;
+  /** Sibling lossless USDZ transport carried by the generated client when its signed-in workspace
+   * still serves the predecessor model. The archive is never canonical state and is not embedded. */
+  readonly lawAssetName?: string;
   /** The package's STRUCTURAL INTERFACE (#72) — directives (payload shapes) + aggregates
    *  (read shapes, sid-keyed), keyed by domain. Baked in so `connect()` can negotiate
    *  shape-compatibility against the workspace's installed offer — NOT by hash. */
@@ -819,6 +822,7 @@ function emitTsActivityBlock(entries: readonly PackageActivityEntry[], describeM
     `}`,
     `type NomosModelAdoption =`,
     `  | { status: "adopted"; summary: string; review: NomosModelReview }`,
+    `  | { status: "needs-staging"; summary: string; review: NomosModelReview; stage(): Promise<NomosModelAdoption> }`,
     `  | { status: "needs-decision"; summary: string; review: NomosModelReview; accept(because: string): Promise<NomosModelAdoption> }`,
     `  | { status: "blocked"; summary: string; error: string; review: NomosModelReview };`,
     `type NomosModelRestoration =`,
@@ -868,7 +872,7 @@ function emitTsActivityBlock(entries: readonly PackageActivityEntry[], describeM
     `  };`,
     `}`,
     `async function _nomosAdoptModel(`,
-    `  holon: NomosHolon, domain: string, candidateHash: string, because?: string,`,
+    `  holon: NomosHolon, domain: string, candidateHash: string, lawAsset?: URL, because?: string,`,
     `): Promise<NomosModelAdoption> {`,
     `  if (!holon.__nomosAdoptModel) {`,
     `    const error = "This device needs the current Nomos client before it can adopt a model.";`,
@@ -879,6 +883,26 @@ function emitTsActivityBlock(entries: readonly PackageActivityEntry[], describeM
     `  if (raw.stage === "promoted" && raw.ok) {`,
     `    return { status: "adopted", summary: "Nomos proved this model against current history and made it active.", review };`,
     `  }`,
+    `  if (raw.stage === "staging-required" && lawAsset !== undefined && holon.__nomosStageGeneratedModel !== undefined) {`,
+    `    return {`,
+    `      status: "needs-staging",`,
+    `      summary: "This workspace is running the previous model. Nomos can stage this generated USDA candidate through its signed author gate.",`,
+    `      review,`,
+    `      stage: async () => {`,
+    `        // Keep Node's file loader behind a runtime-only boundary: browser-generated clients`,
+    `        // must typecheck without @types/node, while the local CLI can still stage its USDA asset.`,
+    `        const dynamicImport = Function("specifier", "return import(specifier)") as (specifier: string) => Promise<{ readFile(source: URL): Promise<Uint8Array> }>;`,
+    `        const { readFile } = await dynamicImport("node:fs/promises");`,
+    `        const lawUsdz = new Uint8Array(await readFile(lawAsset));`,
+    `        const staged = await holon.__nomosStageGeneratedModel!(domain, candidateHash, lawUsdz);`,
+    `        if (staged.ok !== true) {`,
+    `          const error = staged.error ?? "The workspace refused the generated USDA candidate.";`,
+    `          return { status: "blocked", summary: error, error, review };`,
+    `        }`,
+    `        return _nomosAdoptModel(holon, domain, candidateHash, lawAsset);`,
+    `      },`,
+    `    };`,
+    `  }`,
     `  if (raw.stage === "acceptance") {`,
     `    return {`,
     `      status: "needs-decision",`,
@@ -887,7 +911,7 @@ function emitTsActivityBlock(entries: readonly PackageActivityEntry[], describeM
     `      accept: async (reason: string) => {`,
     `        const stated = reason.trim();`,
     `        if (!stated) throw new Error("accept(reason) needs the business reason for changing prior outcomes");`,
-    `        return _nomosAdoptModel(holon, domain, candidateHash, stated);`,
+    `        return _nomosAdoptModel(holon, domain, candidateHash, lawAsset, stated);`,
     `      },`,
     `    };`,
     `  }`,
@@ -1807,6 +1831,8 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  /** FRAMEWORK-INTERNAL exact-history adoption seam. Generated clients expose only`,
     `   *  \`model.adopt()\` and a chained \`decision.accept(reason)\`. */`,
     `  __nomosAdoptModel?(domain: string, candidateHash: string, opts?: { because?: string }): Promise<__NomosModelAdoptionWire>;`,
+    `  /** FRAMEWORK-INTERNAL signed lifecycle offer used by generated model staging. */`,
+    `  __nomosStageGeneratedModel?(domain: string, candidateHash: string, lawUsdz: Uint8Array): Promise<{ ok?: boolean; error?: string }>;`,
     `  /** FRAMEWORK-INTERNAL exact-history restoration seam. Generated clients expose only`,
     `   *  \`model.restorePrevious()\` and a chained \`decision.accept(reason)\`. */`,
     `  __nomosRestorePreviousModel?(domain: string, currentHash: string, opts?: { because?: string }): Promise<__NomosModelRestorationWire>;`,
@@ -3844,7 +3870,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       `    /** Adopt THIS generated model. Nomos proves it against current history; a deliberate`,
       `     *  difference returns a decision whose accept(reason) re-proves and records the reason. */`,
       `    model: {`,
-      `      adopt: (): Promise<NomosModelAdoption> => _nomosAdoptModel(holon, ${JSON.stringify(domain)}, domainHash),`,
+      `      adopt: (): Promise<NomosModelAdoption> => _nomosAdoptModel(holon, ${JSON.stringify(domain)}, domainHash${opts.lawAssetName === undefined ? "" : `, new URL(${JSON.stringify(`./${opts.lawAssetName}`)}, import.meta.url)`}),`,
       `      restorePrevious: (): Promise<NomosModelRestoration> => _nomosRestorePreviousModel(holon, ${JSON.stringify(domain)}, domainHash),`,
       `    },`,
       ...(clientInterface !== undefined
@@ -3971,6 +3997,8 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       `  readonly signIn: (request?: { readonly deviceChallenge?: string }) => Promise<string>;`,
       `  /** Typed timings for developer tooling; Nomos routing, credentials and Git custody remain private. */`,
       `  readonly onPerformance?: (sample: ${applicationName}PerformanceSample) => void;`,
+      `  /** Supply the accountable business decision when this client intentionally changes the deployed model. */`,
+      `  readonly approveModel?: (decision: { readonly summary: string; readonly review: NomosModelReview }) => Promise<{ readonly because: string }>;`,
       `}`,
       `function _nomosPublicDomain<T extends Record<string, unknown>>(domain: T): _NomosPublicDomain<T> {`,
       `  const application: Record<string, unknown> = {};`,
@@ -4106,7 +4134,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       ` *  or parallel cache around it. Nomos owns offline custody and synchronization. */`,
       `export function ${applicationOpener}(options: ${applicationName}OpenOptions): Promise<${applicationName}> {`,
       `  return nomosInternalOpenGeneratedApplication(`,
-      `    { cloud: options.cloud, application: options.application, signIn: options.signIn, onPerformance: options.onPerformance, lawHash: ${hashConst}, readyCommands: [${rootBirths.map((birth) => `{ domain: ${JSON.stringify(birth.sourceDomain)}, packageHash: ${hashConst}, directiveId: ${JSON.stringify(birth.directiveId)} }`).join(", ")}] },`,
+      `    { cloud: options.cloud, application: options.application, signIn: options.signIn, onPerformance: options.onPerformance, approveModel: options.approveModel, lawHash: ${hashConst}, readyCommands: [${rootBirths.map((birth) => `{ domain: ${JSON.stringify(birth.sourceDomain)}, packageHash: ${hashConst}, directiveId: ${JSON.stringify(birth.directiveId)} }`).join(", ")}] },`,
       `    (holon, user) => _nomosBind${applicationName}(holon as NomosHolon, user),`,
       `  );`,
       `}`,

package/src/compile_package_main.ts

@@ -64,6 +64,8 @@ import {
 } from "./codegen_dart.js";
 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 { generateDartBridgeClient } from "./codegen_dart_client.js";
 import {
   dartApplicationClassName,
@@ -154,6 +156,7 @@ import {
   serializeIdentityUsda,
 } from "./identity_usda.js";
 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 { assertNoDartBarrelCollisions, type BarrelExportedFile } from "./dart_barrel_guard.js";
@@ -163,6 +166,7 @@ import { domainInterface, type DomainInterface } from "./shape_compat.js";
 import { generateTsProof, proofLegsIndex } from "./codegen_proof.js";
 import { usdzPack } from "./usdz.js";
 import { checkDomainModules, formatFindings, hasRefusal } from "./law_check.js";
+import { currentEvolveLaw, evolveDiff, evolveLawFromLockfile } from "./evolve_preview.js";
 import type { NomosCompat } from "./compat_manifest.js";
 import { requiredKernelFeatures, type FeatureProbeModule } from "./kernel_capabilities.js";
 import { APPLICATION_HOME_DOMAIN } from "./framework/application_home_domain.js";
@@ -1660,8 +1664,8 @@ const NOMOS_TYPES_DEP = "^0.8.7";
 // 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.28";
-const NOMOS_FLUTTER_DEP = "^0.63.51";
+const NOMOS_CLIENT_DEP = "^0.64.31";
+const NOMOS_FLUTTER_DEP = "^0.63.54";
 // 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).
@@ -3137,6 +3141,7 @@ async function main(): Promise<void> {
       fail(`each domain needs { key, modules: [path, ...] }; got ${JSON.stringify(d)}`);
     }
     const mods: Mod[] = [];
+    const evolutionMods: Mod[] = [];
     const sourceExprs: string[] = [];
     const directOfferExports = new Map<string, { modulePath: string; exportName: string; aggregateId: string }>();
     const directWorkspaceInvariantExports = new Map<string, {
@@ -3145,6 +3150,12 @@ async function main(): Promise<void> {
     }>();
     for (const rel of d.modules) {
       const abs = path.resolve(cfgDir, rel);
+      if (isEvolutionModulePath(abs)) {
+        fail(
+          `domain '${d.key}': ${rel} is an evolution concern; move it under ` +
+            `evolutions/${d.key}/ and remove it from feature modules so it cannot enter QuickJS`,
+        );
+      }
       if (!existsSync(abs)) fail(`domain '${d.key}': module not found: ${abs}`);
       const m = (await import(pathToFileURL(abs).href)) as Mod;
       bindEnumTypeExports(m, abs);
@@ -3182,6 +3193,16 @@ async function main(): Promise<void> {
         }
       }
     }
+    const configuredPaths = new Set(d.modules.map((rel) => path.resolve(cfgDir, rel)));
+    for (const abs of discoverEvolutionModulePaths(cfgDir, d.key)) {
+      // Explicitly listed files remain supported during migration, but the same
+      // module must not be composed twice when it is already in the convention.
+      if (configuredPaths.has(abs)) continue;
+      const evolutionModule = (await import(pathToFileURL(abs).href)) as Mod;
+      assertEvolutionModuleExports(evolutionModule, abs);
+      bindEnumTypeExports(evolutionModule, abs);
+      evolutionMods.push(evolutionModule);
+    }
     if (mods.some((mod) => Object.prototype.hasOwnProperty.call(mod, BUSINESS_BIRTH_POLICY_DOMAINS_EXPORT))) {
       fail(
         `domain '${d.key}' exports reserved compiler binding '${BUSINESS_BIRTH_POLICY_DOMAINS_EXPORT}'; ` +
@@ -3502,7 +3523,7 @@ async function main(): Promise<void> {
       composeDomainModule({
         name: d.name ?? d.key,
         domain: d.key,
-        modules: mods,
+        modules: [...mods, ...evolutionMods],
         ...(extraAggregates.length > 0 ? { extraAggregates } : {}),
         ...(queries.length > 0 ? { queries } : {}),
         ...(counts.length > 0 ? { counts } : {}),
@@ -3748,7 +3769,8 @@ async function main(): Promise<void> {
   // exactly ONE disappeared + ONE appeared name of the same kind/shape is an inferred
   // RENAME (sid carried, lineage recorded, printed below); anything else mints fresh
   // at first appearance (a leftover disappearance is THE EVOLVE GATE's typed question
-  // at deploy — answered in the upgrade intent's disposition). The resolved continuity
+  // at compile — answered by a typed declaration in evolutions/<domain>/*.evolution.ts).
+  // The resolved continuity
   // is attached to the module so the canonical manifest + USD-IR carry it.
   const lockPath = path.join(cfgDir, NOMOS_IDENTITY_FILENAME);
   const priorLock: CompilerIdentityModel | undefined = existsSync(lockPath)
@@ -3891,6 +3913,63 @@ async function main(): Promise<void> {
       schemas: Object.fromEntries(currentAggs.map((a) => [a.id, a.schema])),
     };
   }
+
+  // ── ORDINARY-COMPILE EVOLUTION GATE ──────────────────────────────────────────────
+  // Agents reliably run `compile`; they do not reliably discover an optional migration command.
+  // Compare the candidate against the committed identity frontier here, after stable-id
+  // reconciliation (so inferred renames have their true identity) but before writing either the
+  // lock or the custody package. The kernel independently repeats the same admission decision at
+  // deployment; this is its fast, local static twin, not a replacement for runtime authority.
+  //
+  // 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) {
+    const priorDomainsForPackage: CompilerIdentityModel["domains"] = {};
+    const priorIdentity = identityRegistryFromModel(priorLock);
+    const frameworkAggregateSids = new Set(
+      Object.values(priorIdentity.entities)
+        .filter((entity) => entity.kind === "aggregate" && entity.parent === LAW_FRAMEWORK_PARENT)
+        .map((entity) => entity.sid),
+    );
+    for (const mod of domainModules) {
+      const domainKey = mod.domain ?? mod.name;
+      const locked = priorLock.domains[mod.name] ?? priorLock.domains[domainKey];
+      if (locked !== undefined) {
+        // Framework aggregates are shared implementation law, reconciled under @framework rather
+        // than owned by this tenant domain. A package may compose a different framework subset as
+        // its topology changes; never instruct a tenant to author a retirement for Nomos internals.
+        const localAggregates = Object.fromEntries(
+          Object.entries(locked.stableIds.aggregates)
+            .filter(([, aggregate]) => !frameworkAggregateSids.has(aggregate.sid)),
+        );
+        priorDomainsForPackage[domainKey] = {
+          stableIds: { ...locked.stableIds, aggregates: localAggregates },
+          ...(locked.schemas === undefined
+            ? {}
+            : {
+                schemas: Object.fromEntries(
+                  Object.entries(locked.schemas).filter(([label]) => label in localAggregates),
+                ),
+              }),
+        };
+      }
+    }
+    const priorLaw = evolveLawFromLockfile({
+      v: 1,
+      domains: priorDomainsForPackage,
+      ...(priorLock.identity === undefined ? {} : { identity: priorLock.identity }),
+    });
+    const candidateLaw = currentEvolveLaw(domainModules, nextLock);
+    const evolutionFindings = evolveDiff(priorLaw, candidateLaw).findings;
+    const evolutionRefusals = evolutionFindings.filter((finding) => finding.level === "refuse");
+    if (evolutionRefusals.length > 0) {
+      console.error("nomos-compile: candidate law evolution refused before custody emission:");
+      for (const line of formatFindings(evolutionRefusals)) console.error(`             ✗ ${line}`);
+      process.exitCode = 1;
+      return;
+    }
+  }
   // Persist the typed identity layer (commit it with the law: it is how a rename keeps its
   // identity across clean clones). Existing project-domain order is retained, so once sibling
   // packages are registered, recompiling them in any order rewrites the same bytes without a
@@ -5214,8 +5293,11 @@ async function main(): Promise<void> {
       : `package asset: NOT EMITTED — declare rootPart: { name, kind: "component" | "assembly" }`,
     `typed application: ${cfg.name}.client.mjs — open${cfg.name.split(/[^A-Za-z0-9]+/).filter(Boolean).map((part) => part[0]!.toUpperCase() + part.slice(1)).join("")}Application({ cloud, signIn })`,
     proofPath !== undefined
-      ? `generated proof: ${cfg.name}.proof.mts — run: githolon proof (live; ends ALL GREEN or names the jam)`
+      ? `generated proof: ${cfg.name}.proof.mts — fresh: githolon proof; existing custody: githolon proof --upgrade`
       : `generated proof: SKIPPED — ${proofSkip}`,
+    ...(priorLock === undefined
+      ? []
+      : [`upgrade proof: githolon proof --upgrade — exact existing history, disposable promotion, cold restart`]),
     ``,
   ].join("\n");
   writeFileSync(path.join(outDir, `${cfg.name}.summary.txt`), summaryTxt, "utf8");
@@ -5258,6 +5340,7 @@ async function main(): Promise<void> {
   const clientOptions = {
     packageName: cfg.name,
     domainHash,
+    lawAssetName: `${cfg.name}.law.usdz`,
     interface: packageInterface,
     compat: nomosCompat,
     homeDomain: resolveApplicationTopology(presentationDomainModules).homeDomain,
@@ -5271,6 +5354,11 @@ async function main(): Promise<void> {
   if (!existsSync(runtimePath)) {
     fail("the compiler-private generated application runtime is missing — reinstall @githolon/dsl");
   }
+  // Validate the generated ESM clients as ESM even when the tenant project has no package.json yet.
+  // NodeNext classifies a plain `.ts` file from the nearest package boundary, so a freshly scaffolded
+  // or fixture-only project would otherwise be treated as CommonJS and reject the intentional
+  // `import.meta.url` used to locate its adjacent law asset. The compiler options below describe the
+  // generated `.mjs` runtime contract directly instead of inheriting unrelated tenant metadata.
   const temporaryClientPath = path.join(outDir, `.${cfg.name}.client.source.ts`);
   const temporaryHeadlessClientPath = path.join(outDir, `.${cfg.name}.headless.source.ts`);
   const temporaryRuntimeTypesPath = path.join(outDir, `.${cfg.name}.application-runtime.d.ts`);
@@ -5278,7 +5366,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; 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 }[] },`,
     `  bind: (holon: unknown, user: { readonly identityId: string; readonly identityAddress: string }) => T,`,
     `): Promise<T & {`,
     `  currentStatus(): Promise<any>;`,
@@ -5357,8 +5445,8 @@ async function main(): Promise<void> {
       [temporaryClientPath, temporaryHeadlessClientPath, temporaryRuntimeTypesPath],
       {
         target: ts.ScriptTarget.ES2022,
-        module: ts.ModuleKind.NodeNext,
-        moduleResolution: ts.ModuleResolutionKind.NodeNext,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
         declaration: true,
         emitDeclarationOnly: true,
         noEmitOnError: true,
@@ -6042,12 +6130,15 @@ async function main(): Promise<void> {
   console.log(`  deploy     githolon deploy <workspace> --file ${rel(lawUsdzPath)}`);
   console.log(``);
   console.log(`your business path:`);
+  if (priorLock !== undefined) {
+    console.log(`  npx githolon proof --upgrade  # candidate -> exact existing history -> disposable promotion -> cold restart`);
+  }
   if (proofPath !== undefined) {
     console.log(`  npx githolon proof         # generated birth -> verify -> durable restore -> business read-back`);
     console.log(`  npx githolon dev           # rerun that proof on every save`);
     console.log(`  npx githolon proof --live  # the same business proof against Nomos Cloud`);
     if (proofDomains.length > 1) {
-      console.log(`  this package proves ${proofDomains.length} domains (${proofDomains.join(", ")}) — default '${proofDomains[0]}'; pick another: npx githolon proof --domain <key>`);
+      console.log(`  this package proves all ${proofDomains.length} business areas together (${proofDomains.join(", ")})`);
     }
   } else {
     console.log(`  add a business birth declaration to generate an end-to-end proof`);