@githolon/dsl 0.105.12 → 0.105.14

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.26";
-const NOMOS_FLUTTER_DEP = "^0.63.50";
+const NOMOS_CLIENT_DEP = "^0.64.29";
+const NOMOS_FLUTTER_DEP = "^0.63.52";
 // 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`);

package/src/evolution.ts

@@ -0,0 +1,313 @@
+// NOMOS — business model evolution as a separate, composable concern.
+//
+// Current aggregate files describe what the business means now. An evolution file
+// relates an earlier lawful field contract to that current meaning. The compiler
+// discovers these typed declarations under evolutions/<domain>/**/*.evolution.ts,
+// proves them, and lowers them into the same canonical USDA law. They are never host
+// configuration and never deployment-time stable-id strings.
+
+import type { AggregateHandle, StoredFields } from "./aggregate.js";
+import type {
+  Field,
+  FieldEvolutionDeclaration,
+  FieldValue,
+} from "./fields.js";
+
+const EVOLUTION_BRAND = "__nomos_field_evolution_v1" as const;
+const FORMER_AGGREGATE_BRAND = "__nomos_former_aggregate_v1" as const;
+const FORMER_FIELD_BRAND = "__nomos_former_field_v1" as const;
+const RETIREMENT_BRAND = "__nomos_retirement_v1" as const;
+
+export interface FieldEvolution<
+  A extends AggregateHandle = AggregateHandle,
+> {
+  readonly [EVOLUTION_BRAND]: true;
+  readonly aggregate: A;
+  readonly field: string;
+  readonly declaration: FieldEvolutionDeclaration;
+}
+
+export interface FieldEvolutionBuilder<T> {
+  /**
+   * Relate one earlier lawful field contract to the current field. With no
+   * projection, Nomos proves identity widening. A projection is admitted only
+   * for a finite source language and is exhaustively compiled to a case table.
+   */
+  from<From>(
+    source: Field<From>,
+    project?: (value: From) => T,
+  ): FieldEvolution;
+}
+
+export interface FormerField<AggregateId extends string = string, Name extends string = string> {
+  readonly [FORMER_FIELD_BRAND]: true;
+  readonly aggregate: AggregateId;
+  readonly name: Name;
+}
+
+export interface FormerAggregate<
+  Id extends string = string,
+  FieldName extends string = string,
+> {
+  readonly [FORMER_AGGREGATE_BRAND]: true;
+  readonly id: Id;
+  readonly fields: Readonly<Record<FieldName, FormerField<Id, FieldName>>>;
+}
+
+export interface Retirement {
+  readonly [RETIREMENT_BRAND]: true;
+  readonly kind: "aggregate" | "field";
+  readonly aggregate: string;
+  readonly field?: string;
+}
+
+/**
+ * Name a declaration from the immediately preceding model without putting it
+ * back into the current business model. The names occur once at this historical
+ * declaration site; every retirement elsewhere refers to the returned handles.
+ */
+export function formerAggregate<
+  const Id extends string,
+  const FieldName extends string,
+>(
+  id: Id,
+  fieldNames: readonly FieldName[] = [],
+): FormerAggregate<Id, FieldName> {
+  if (!id.trim()) throw new Error("formerAggregate(id) needs the prior aggregate's non-empty name");
+  const fields: Record<string, FormerField<Id, FieldName>> = {};
+  for (const name of fieldNames) {
+    if (!name.trim()) throw new Error(`formerAggregate(${id}) has an empty prior field name`);
+    if (fields[name] !== undefined) throw new Error(`formerAggregate(${id}) repeats prior field '${name}'`);
+    fields[name] = Object.freeze({
+      [FORMER_FIELD_BRAND]: true as const,
+      aggregate: id,
+      name,
+    });
+  }
+  return Object.freeze({
+    [FORMER_AGGREGATE_BRAND]: true as const,
+    id,
+    fields: Object.freeze(fields) as Readonly<Record<FieldName, FormerField<Id, FieldName>>>,
+  });
+}
+
+/** Declare one intentional tombstone in a separate evolution file. */
+export function retirement(
+  entity: FormerAggregate | FormerField,
+): Retirement {
+  if (entity === null || typeof entity !== "object") {
+    throw new Error("retirement(entity) needs a handle from formerAggregate(...)");
+  }
+  if ((entity as unknown as Record<string, unknown>)[FORMER_AGGREGATE_BRAND] === true) {
+    const aggregate = entity as FormerAggregate;
+    return Object.freeze({
+      [RETIREMENT_BRAND]: true as const,
+      kind: "aggregate" as const,
+      aggregate: aggregate.id,
+    });
+  }
+  if ((entity as unknown as Record<string, unknown>)[FORMER_FIELD_BRAND] === true) {
+    const field = entity as FormerField;
+    return Object.freeze({
+      [RETIREMENT_BRAND]: true as const,
+      kind: "field" as const,
+      aggregate: field.aggregate,
+      field: field.name,
+    });
+  }
+  throw new Error("retirement(entity) needs a handle from formerAggregate(...)");
+}
+
+/**
+ * Begin a separately authored evolution for one current business field.
+ *
+ * @example
+ * ```ts
+ * // evolutions/publication-reference.evolution.ts
+ * export const publicationReference = evolution(Snapshot, "publicationId")
+ *   .from(legacyPublicationId);
+ * ```
+ */
+export function evolution<
+  const Id extends string,
+  F extends Record<string, Field>,
+  K extends keyof StoredFields<F> & string,
+>(
+  aggregate: AggregateHandle<Id, F>,
+  field: K,
+): FieldEvolutionBuilder<FieldValue<StoredFields<F>[K]>> {
+  const target = (aggregate.fields as Record<string, Field>)[field];
+  if (target === undefined) {
+    throw new Error(
+      `evolution(${aggregate.id}, ${JSON.stringify(field)}): '${field}' is not a stored field of ${aggregate.id}`,
+    );
+  }
+  return {
+    from<From>(source: Field<From>, project?: (value: From) => FieldValue<StoredFields<F>[K]>): FieldEvolution {
+      // Reuse the field declaration's single proof implementation. The returned
+      // field is only a temporary immutable value from which we take the one new
+      // edge; the current aggregate declaration is never mutated.
+      const evolved = target.evolvesFrom(
+        source,
+        project as ((value: From) => unknown) | undefined,
+      );
+      const declarations = evolved.evolutions ?? [];
+      const declaration = declarations[declarations.length - 1];
+      if (declaration === undefined) {
+        throw new Error(
+          `evolution(${aggregate.id}, ${JSON.stringify(field)}): failed to construct an evolution edge`,
+        );
+      }
+      return Object.freeze({
+        [EVOLUTION_BRAND]: true as const,
+        aggregate,
+        field,
+        declaration,
+      });
+    },
+  };
+}
+
+export function isFieldEvolution(value: unknown): value is FieldEvolution {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    (value as Record<string, unknown>)[EVOLUTION_BRAND] === true
+  );
+}
+
+export function isRetirement(value: unknown): value is Retirement {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    (value as Record<string, unknown>)[RETIREMENT_BRAND] === true
+  );
+}
+
+/** Evolution files are compiler-only by construction; executable/business exports would be law
+ * that is absent from QuickJS. Refuse that split-brain shape at the file boundary. */
+export function assertEvolutionModuleExports(
+  module: Readonly<Record<string, unknown>>,
+  file: string,
+): void {
+  for (const [name, value] of Object.entries(module)) {
+    if (isFieldEvolution(value) || isRetirement(value)) continue;
+    throw new Error(
+      `${file}: evolution file export '${name}' is not evolution(...) or retirement(...). ` +
+        "Keep current aggregates, directives and helpers in business modules; evolution files " +
+        "are compiler-only historical law.",
+    );
+  }
+}
+
+/** Collect evolution edges without allowing re-exports to duplicate one object. */
+export function fieldEvolutionsOf(
+  modules: readonly Record<string, unknown>[],
+): FieldEvolution[] {
+  const seen = new Set<FieldEvolution>();
+  const out: FieldEvolution[] = [];
+  for (const module of modules) {
+    for (const value of Object.values(module)) {
+      if (!isFieldEvolution(value) || seen.has(value)) continue;
+      seen.add(value);
+      out.push(value);
+    }
+  }
+  return out;
+}
+
+/** Collect explicit tombstones; two files may not retire the same identity twice. */
+export function retirementsOf(
+  modules: readonly Record<string, unknown>[],
+  domain: string,
+): Retirement[] {
+  const out: Retirement[] = [];
+  const keys = new Set<string>();
+  for (const module of modules) {
+    for (const value of Object.values(module)) {
+      if (!isRetirement(value)) continue;
+      const key = value.kind === "aggregate"
+        ? `aggregate:${value.aggregate}`
+        : `field:${value.aggregate}.${value.field ?? ""}`;
+      if (!keys.add(key)) {
+        throw new Error(`domain '${domain}' retires '${key}' more than once`);
+      }
+      out.push(value);
+    }
+  }
+  return out;
+}
+
+function cloneFieldWithEvolution(
+  field: Field,
+  declaration: FieldEvolutionDeclaration,
+): Field {
+  const clone = Object.defineProperties(
+    {},
+    Object.getOwnPropertyDescriptors(field),
+  ) as Field;
+  Object.defineProperty(clone, "evolutions", {
+    value: Object.freeze([...(field.evolutions ?? []), declaration]),
+    enumerable: true,
+    configurable: true,
+    writable: false,
+  });
+  return clone;
+}
+
+/** Apply separately authored edges to the aggregate handles consumed by law emission. */
+export function applyFieldEvolutionsToAggregates(
+  aggregates: readonly AggregateHandle[],
+  evolutions: readonly FieldEvolution[],
+  domain: string,
+): AggregateHandle[] {
+  const byAggregate = new Map(aggregates.map((aggregate) => [aggregate.id, aggregate]));
+  const byTarget = new Map<string, FieldEvolution[]>();
+  for (const declaration of evolutions) {
+    const aggregate = byAggregate.get(declaration.aggregate.id);
+    if (aggregate === undefined) {
+      throw new Error(
+        `domain '${domain}' exports an evolution for '${declaration.aggregate.id}.${declaration.field}' ` +
+          "but does not export the current aggregate itself",
+      );
+    }
+    if ((aggregate.fields as Record<string, Field>)[declaration.field] === undefined) {
+      throw new Error(
+        `domain '${domain}' exports an evolution for missing current field ` +
+          `'${declaration.aggregate.id}.${declaration.field}'`,
+      );
+    }
+    const key = `${declaration.aggregate.id}\u0000${declaration.field}`;
+    const current = byTarget.get(key) ?? [];
+    current.push(declaration);
+    byTarget.set(key, current);
+  }
+
+  return aggregates.map((aggregate) => {
+    const targets = [...byTarget]
+      .filter(([key]) => key.startsWith(`${aggregate.id}\u0000`))
+      .flatMap(([, declarations]) => declarations);
+    if (targets.length === 0) return aggregate;
+    const fields = Object.defineProperties(
+      {},
+      Object.getOwnPropertyDescriptors(aggregate.fields),
+    ) as Record<string, Field>;
+    for (const target of targets) {
+      fields[target.field] = cloneFieldWithEvolution(
+        fields[target.field]!,
+        target.declaration,
+      );
+    }
+    const clone = Object.defineProperties(
+      {},
+      Object.getOwnPropertyDescriptors(aggregate),
+    ) as AggregateHandle;
+    Object.defineProperty(clone, "fields", {
+      value: fields,
+      enumerable: true,
+      configurable: true,
+      writable: false,
+    });
+    return clone;
+  });
+}

package/src/evolution_files.ts

@@ -0,0 +1,31 @@
+import { existsSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+const EVOLUTION_MODULE_SUFFIX = /\.evolution\.(?:ts|tsx|mts|mjs|js)$/;
+
+export function isEvolutionModulePath(file: string): boolean {
+  return EVOLUTION_MODULE_SUFFIX.test(file);
+}
+
+/**
+ * Discover compiler-only evolution concerns by convention. Both `compile` and
+ * `check` use this function so local assurance cannot inspect a different law
+ * closure from the one that will be deployed.
+ */
+export function discoverEvolutionModulePaths(
+  configDirectory: string,
+  domainKey: string,
+): string[] {
+  const root = path.join(configDirectory, "evolutions", domainKey);
+  if (!existsSync(root)) return [];
+  const out: string[] = [];
+  const visit = (directory: string): void => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile() && isEvolutionModulePath(entry.name)) out.push(absolute);
+    }
+  };
+  visit(root);
+  return out.sort((left, right) => left.localeCompare(right));
+}