@githolon/dsl 0.105.13 → 0.105.15

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));
+}

package/src/evolve_preview.ts

@@ -7,9 +7,9 @@
  * THE EVOLVE PREVIEW — `githolon check --against <prior>` (architecture/author_time_gate.md,
  * the `--against` row of check slice 3). The evolve gate is the kernel's #58 diff-by-stable-id
  * (executor/src/law58.rs::evolve_violation): a RENAME (same sid, new label) admits silently; a
- * true REMOVAL / merge-driver change refuses TYPED unless the installation offer carries a
- * `dispositions` acknowledgement. A changed BUSINESS VALUE CONTRACT is stricter: it needs
- * deterministic `.evolvesFrom(...)` coverage and cannot be waived by an acknowledgement.
+ * true REMOVAL / merge-driver change refuses TYPED unless the candidate law itself carries the
+ * corresponding retirement or deterministic evolution. Application/deployment code never authors
+ * stable-id waivers.
  *
  * This module is the AUTHOR-TIME TWIN of that gate: given the PRIOR law and the CURRENT build,
  * it diffs them BY STABLE ID and pre-fires the gate's verdicts — with the EXACT generated
@@ -18,10 +18,10 @@
  *   RENAME   (note)   — same sid, new label; admits silently, old rows read the new label.
  *   ADDITIVE (note)   — a new aggregate/field/directive (incl. an additive optional VO field);
  *                       the evolve gate admits it silently (vo_first_class.md slice 6).
- *   REMOVAL  (refuse) — a sid disappeared; the gate REFUSES without dispositions.retired:[sid].
+ *   REMOVAL  (refuse) — a sid disappeared; declare a typed retirement in the evolution layer.
  *   CONTRACT (refuse) — same sid, changed value language without a deterministic projection;
  *                       needs `.evolvesFrom(...)`, never a disposition.
- *   DRIVER   (refuse) — same sid, changed merge driver; needs dispositions.retyped.
+ *   DRIVER   (refuse) — same sid, changed merge driver; needs a typed evolution or a new field.
  *   PAYLOAD  (warn)   — a directive's payload shape changed; clients compiled against the old
  *                       law get typed 422s until regenerated (directives are not sid-tracked).
  *
@@ -66,19 +66,17 @@ export interface EvolveDomain {
   readonly aggregates: Record<string, EvolveAggregate>;
   /** keyed by DIRECTIVE ID (directives are not sid-tracked — the dispatched name IS identity). */
   readonly directives: Record<string, DirectivePayloadShape>;
+  /** Authored candidate tombstones, kept label-shaped until the compiler resolves them to sids. */
+  readonly retirements?: readonly {
+    kind: "aggregate" | "field";
+    aggregate: string;
+    field?: string;
+  }[];
 }
 
 /** A whole package's evolve surface, keyed by DOMAIN KEY. */
 export type EvolveLaw = Record<string, EvolveDomain>;
 
-/** The dispositions fragment the installDomain offer carries to admit destructive evolves (the exact
- *  shape executor/src/law58.rs::dispositions_from_payload parses). */
-export interface EvolveDispositionsJson {
-  retired?: string[];
-  retyped?: Record<string, string>;
-  rebinds?: Record<string, string>;
-}
-
 // ── normalizers: build an EvolveLaw from the artifacts a dev already has ────────────
 
 /** Build ONE domain's aggregate surface from a #58 `StableIds` block (+ optional driver
@@ -217,29 +215,39 @@ export function currentEvolveLaw(
         const stableAggregate = Object.values(stableIds.aggregates).find(
           (candidate) => candidate.sid === agg.sid,
         );
-        const schema = locked?.schemas?.[agg.label];
+        const stableFields = new Map(
+          Object.values(stableAggregate?.fields ?? {})
+            .map((field) => [field.sid, field] as const),
+        );
+        const schema = locked?.schemas?.[agg.label]
+          ?? Object.entries(locked?.schemas ?? {}).find(([type]) => type.endsWith(`.${agg.label}`))?.[1];
         for (const f of Object.values(agg.fields)) {
-          const stableField = Object.values(stableAggregate?.fields ?? {}).find(
-            (candidate) => candidate.sid === f.sid,
-          );
+          const stableField = stableFields.get(f.sid);
           const driver = stableField?.driver ?? schema?.[f.label];
           if (driver !== undefined) (f as { driver?: string }).driver = JSON.stringify(driver);
+          if (stableField?.contract !== undefined) f.contract = stableField.contract;
+          if (stableField?.schema !== undefined) f.schema = stableField.schema;
+          if (stableField?.evolutions !== undefined) {
+            f.evolutions = stableField.evolutions.map((rule) => ({ from: rule.from, to: rule.to }));
+          }
         }
       }
     }
-    law[key] = dom;
+    law[key] = {
+      ...dom,
+      ...(mod.retirements !== undefined && mod.retirements.length > 0
+        ? { retirements: mod.retirements }
+        : {}),
+    };
   }
   return law;
 }
 
 // ── the diff ────────────────────────────────────────────────────────────────────────
 
-/** The full preview result: the findings AND the merged dispositions the destructive findings
- *  demand, keyed by DOMAIN KEY (the object carried by an installDomain offer). */
+/** The full author-time preview result. Mechanical transition authority stays in candidate law. */
 export interface EvolveDiffResult {
   readonly findings: Finding[];
-  /** domain key → the dispositions fragment that makes THIS domain's destructive evolves admit. */
-  readonly dispositions: Record<string, EvolveDispositionsJson>;
 }
 
 /** A short, bounded render of a directive's payload field shape (for a warn's old-vs-new naming). */
@@ -250,10 +258,6 @@ function payloadShapeText(shape: DirectivePayloadShape): string {
   return `{ ${parts.join(", ")} }`;
 }
 
-function ensureDisp(map: Record<string, EvolveDispositionsJson>, domain: string): EvolveDispositionsJson {
-  return (map[domain] ??= {});
-}
-
 /** Mirror executor::law58::evolution_reaches: one deterministic route per source,
  *  accumulated across supported releases, must terminate at the current schema. */
 function evolutionReaches(
@@ -276,13 +280,12 @@ function evolutionReaches(
   return true;
 }
 
-/** Diff one domain's aggregates/fields/directives BY STABLE ID and append findings + dispositions. */
+/** Diff one domain's aggregates/fields/directives BY STABLE ID and append findings. */
 function diffDomain(
   domain: string,
   prior: EvolveDomain,
   current: EvolveDomain,
   findings: Finding[],
-  disp: Record<string, EvolveDispositionsJson>,
 ): void {
   const curAggBySid = current.aggregates;
   const priorAggBySid = prior.aggregates;
@@ -290,14 +293,18 @@ function diffDomain(
   for (const [sid, oldAgg] of Object.entries(priorAggBySid)) {
     const newAgg = curAggBySid[sid];
     if (newAgg === undefined) {
-      // REMOVAL of a whole aggregate — retiring the agg sid satisfies the kernel's diff_by_sid.
-      const d = ensureDisp(disp, domain);
-      (d.retired ??= []).push(sid);
+      const declared = current.retirements?.some(
+        (retirement) => retirement.kind === "aggregate" && retirement.aggregate === oldAgg.label,
+      ) ?? false;
       findings.push({
         domain,
-        level: "refuse",
-        what: `aggregate '${oldAgg.label}' (stable id ${sid}) is REMOVED — the evolve gate will refuse without a disposition`,
-        fix: `include in the installation offer: "dispositions": { "retired": ["${sid}"] }`,
+        level: declared ? "note" : "refuse",
+        what: declared
+          ? `aggregate '${oldAgg.label}' (stable id ${sid}) is RETIRED by candidate law`
+          : `aggregate '${oldAgg.label}' (stable id ${sid}) is REMOVED without a candidate-law retirement`,
+        fix: declared
+          ? "the compiler will lower this declaration to a typed USDA tombstone"
+          : `create evolutions/${domain}/<concern>.evolution.ts and export retirement(formerAggregate("${oldAgg.label}"))`,
       });
       continue;
     }
@@ -313,13 +320,20 @@ function diffDomain(
     for (const [fSid, oldF] of Object.entries(oldAgg.fields)) {
       const newF = newAgg.fields[fSid];
       if (newF === undefined) {
-        const d = ensureDisp(disp, domain);
-        (d.retired ??= []).push(fSid);
+        const declared = current.retirements?.some(
+          (retirement) => retirement.kind === "field"
+            && retirement.aggregate === oldAgg.label
+            && retirement.field === oldF.label,
+        ) ?? false;
         findings.push({
           domain,
-          level: "refuse",
-          what: `field '${oldAgg.label}.${oldF.label}' (stable id ${fSid}) is REMOVED — the evolve gate will refuse without a disposition`,
-          fix: `include in the installation offer: "dispositions": { "retired": ["${fSid}"] }`,
+          level: declared ? "note" : "refuse",
+          what: declared
+            ? `field '${oldAgg.label}.${oldF.label}' (stable id ${fSid}) is RETIRED by candidate law`
+            : `field '${oldAgg.label}.${oldF.label}' (stable id ${fSid}) is REMOVED without a candidate-law retirement`,
+          fix: declared
+            ? "the compiler will lower this declaration to a typed USDA tombstone"
+            : `create evolutions/${domain}/<concern>.evolution.ts, name formerAggregate("${oldAgg.label}", ["${oldF.label}"]), and export its retirement`,
         });
         continue;
       }
@@ -336,27 +350,26 @@ function diffDomain(
         oldF.driver !== undefined && newF.driver !== undefined && oldF.driver !== newF.driver;
       const contractChanged =
         oldF.contract !== undefined && newF.contract !== undefined && oldF.contract !== newF.contract;
-      const contractCovered = contractChanged && evolutionReaches(newF, oldF.schema, newF.schema);
+      const evolutionCovered = evolutionReaches(newF, oldF.schema, newF.schema);
+      const contractCovered = contractChanged && evolutionCovered;
       if (contractChanged && !contractCovered) {
         findings.push({
           domain,
           level: "refuse",
           what: `field '${oldAgg.label}.${oldF.label}' (stable id ${fSid}) changes its business value contract without deterministic evolution coverage`,
-          fix: `declare .evolvesFrom(oldField) for a compatible widening or .evolvesFrom(oldField, value => nextValue) for an exhaustive finite business mapping; dispositions.retyped cannot waive this`,
+          fix: `in evolutions/${domain}/<concern>.evolution.ts export evolution(CurrentAggregate, "${newF.label}").from(oldField), optionally with an exhaustive finite business mapping`,
         });
         continue;
       }
-      if ((kindChanged && !contractCovered) || driverChanged) {
-        const d = ensureDisp(disp, domain);
-        (d.retyped ??= {})[fSid] = "<why goes here>";
+      if ((kindChanged || driverChanged) && !evolutionCovered) {
         const how = kindChanged && !contractCovered
           ? `read kind ${oldF.kind} → ${newF.kind}`
           : `merge driver ${oldF.driver} → ${newF.driver}`;
         findings.push({
           domain,
           level: "refuse",
-          what: `field '${oldAgg.label}.${oldF.label}' (stable id ${fSid}) is RETYPED in place (${how}) — the evolve gate will refuse without a disposition`,
-          fix: `include in the installation offer: "dispositions": { "retyped": { "${fSid}": "<why goes here>" } } — or add a NEW field instead`,
+          what: `field '${oldAgg.label}.${oldF.label}' (stable id ${fSid}) changes in place (${how}) without a candidate-law evolution`,
+          fix: `declare the old field contract and export evolution(CurrentAggregate, "${newF.label}").from(oldField) from evolutions/${domain}/<concern>.evolution.ts — or add a new field`,
         });
       }
     }
@@ -433,31 +446,27 @@ function samePayloadShape(a: DirectivePayloadShape, b: DirectivePayloadShape): b
 }
 
 /**
- * The full evolve preview: diff PRIOR vs CURRENT law by stable id, returning the findings AND
- * the merged dispositions the destructive ones demand (per domain key). Domains present in only
- * one side are ADDITIVE (new domain — note) or a whole-domain REMOVAL (refuse per aggregate).
+ * The full evolve preview: diff PRIOR vs CURRENT law by stable id. Domains present in only one
+ * side are ADDITIVE (new domain — note) or a whole-domain REMOVAL (refuse per aggregate).
  */
 export function evolveDiff(prior: EvolveLaw, current: EvolveLaw): EvolveDiffResult {
   const findings: Finding[] = [];
-  const dispositions: Record<string, EvolveDispositionsJson> = {};
 
   for (const [domain, priorDom] of Object.entries(prior)) {
     const currentDom = current[domain];
     if (currentDom === undefined) {
       // The whole domain uninstalled — every aggregate's stable identity disappears.
-      const d = ensureDisp(dispositions, domain);
       for (const [sid, agg] of Object.entries(priorDom.aggregates)) {
-        (d.retired ??= []).push(sid);
         findings.push({
           domain,
           level: "refuse",
           what: `domain '${domain}' aggregate '${agg.label}' (stable id ${sid}) disappears — the current build no longer carries domain '${domain}'`,
-          fix: `restore the domain, or include "dispositions": { "retired": ["${sid}"] } in the replacement installation offer`,
+          fix: `restore the domain and retire its aggregates in a typed evolution layer before removing executable law`,
         });
       }
       continue;
     }
-    diffDomain(domain, priorDom, currentDom, findings, dispositions);
+    diffDomain(domain, priorDom, currentDom, findings);
   }
   for (const [domain, currentDom] of Object.entries(current)) {
     if (prior[domain] !== undefined) continue;
@@ -471,7 +480,7 @@ export function evolveDiff(prior: EvolveLaw, current: EvolveLaw): EvolveDiffResu
 
   const rank = { refuse: 0, warn: 1, note: 2 } as const;
   findings.sort((a, b) => rank[a.level] - rank[b.level]);
-  return { findings, dispositions };
+  return { findings };
 }
 
 /** The findings-only surface (the `evolvePreview(prior, current): Finding[]` contract). */

package/src/index.ts

@@ -160,6 +160,16 @@ export {
   type ConflictPolicy,
   type ConflictRule,
 } from "./conflicts.js";
+export {
+  evolution,
+  formerAggregate,
+  retirement,
+  type FieldEvolution,
+  type FieldEvolutionBuilder,
+  type FormerAggregate,
+  type FormerField,
+  type Retirement,
+} from "./evolution.js";
 export {
   intent,
   language,