@githolon/dsl 0.105.13 → 0.105.14

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,

package/src/law_graph.ts

@@ -745,10 +745,20 @@ export type DeclaredLawNode =
 export interface LawGraph {
   readonly v: 1;
   readonly domain: LawDomainNode;
+  /** Explicit tombstones authored in evolution files. The compiler registry remembers
+   * every disappearance, but only these candidate-carried facts authorize retirement. */
+  readonly retirements: readonly LawRetirement[];
   /** Canonically SID-ordered, so module/export discovery order cannot affect traversal. */
   readonly nodes: readonly DeclaredLawNode[];
 }
 
+export interface LawRetirement {
+  readonly kind: "aggregate" | "field";
+  readonly sid: string;
+  readonly label: string;
+  readonly parentSid?: string;
+}
+
 export interface DiscoverLawGraphOptions {
   readonly intentCarries?: readonly LawIdentityCarry[];
   readonly readCarries?: readonly LawIdentityCarry[];
@@ -2273,7 +2283,54 @@ export function discoverLawGraph(
     ...predicateNodes.values(),
   ].sort((a, b) => compareText(a.entity.id, b.entity.id));
   registry = identities.finish();
-  return { registry, graph: { v: 1, domain: domainNode, nodes } };
+  const identityEntity = (
+    kind: "aggregate" | "field",
+    parent: string,
+    label: string,
+    status?: "active" | "retired",
+  ) => {
+    const matches = Object.entries(registry.entities).filter(([, candidate]) =>
+      candidate.kind === kind &&
+      candidate.parent === parent &&
+      (status === undefined || candidate.status === status) &&
+      (candidate.label === label || candidate.priorLabels?.includes(label) === true)
+    );
+    if (matches.length !== 1) {
+      fail(
+        `${kind} retirement '${label}' resolves to ${matches.length} prior identities under '${parent}'; ` +
+          "a retirement must name exactly one declaration from the committed identity layer",
+      );
+    }
+    return matches[0]!;
+  };
+  const retirements = (module.retirements ?? []).map((declaration): LawRetirement => {
+    const [aggregateKey, aggregate] = identityEntity(
+      "aggregate",
+      domainKey,
+      declaration.aggregate,
+      declaration.kind === "aggregate" ? "retired" : undefined,
+    );
+    if (declaration.kind === "aggregate") {
+      return {
+        kind: "aggregate",
+        sid: aggregate.sid,
+        label: aggregate.label,
+      };
+    }
+    const [, field] = identityEntity(
+      "field",
+      aggregateKey,
+      declaration.field ?? "",
+      "retired",
+    );
+    return {
+      kind: "field",
+      sid: field.sid,
+      label: field.label,
+      parentSid: aggregate.sid,
+    };
+  }).sort((left, right) => compareText(`${left.kind}:${left.sid}`, `${right.kind}:${right.sid}`));
+  return { registry, graph: { v: 1, domain: domainNode, retirements, nodes } };
 }
 
 type ReadInputBase = { id: string; public: boolean };

package/src/law_graph_usda.ts

@@ -17,6 +17,7 @@ import type {
   LawPredicateNode,
   LawReadContractNode,
   LawReadNode,
+  LawRetirement,
   LawRelationNode,
   LawRelationObjectTypeNode,
   LawRelationPredicateNode,
@@ -586,6 +587,19 @@ export function emitSparseLawGraphUsda(
       `            custom uniform string nomos:parentCertField = ${quote(domain.parentAttestedBirth.certField)}`,
     );
   }
+  if (graph.retirements.length > 0) {
+    lines.push("", '            def Scope "Retirements"', "            {");
+    for (const retirement of graph.retirements) {
+      const name = `${retirement.kind === "aggregate" ? "a" : "f"}_${retirement.sid}`;
+      lines.push(
+        `                def NomosRetirement ${quote(name)}`,
+        "                {",
+        ...emitRetirement(retirement, 20),
+        "                }",
+      );
+    }
+    lines.push("            }");
+  }
   lines.push("");
   emitContainer(lines, "Aggregates", aggregates, 12, (aggregate, indent) =>
     emitAggregate(aggregate, fields, pathById, resolveDependency, indent));
@@ -664,6 +678,18 @@ export function emitSparseLawGraphUsda(
   return lines.join("\n");
 }
 
+function emitRetirement(retirement: LawRetirement, indent: number): string[] {
+  const pad = " ".repeat(indent);
+  return [
+    `${pad}custom uniform token nomos:entityKind = ${quote(retirement.kind)}`,
+    `${pad}custom uniform string nomos:label = ${quote(retirement.label)}`,
+    `${pad}custom uniform string nomos:sid = ${quote(retirement.sid)}`,
+    ...(retirement.parentSid === undefined
+      ? []
+      : [`${pad}custom uniform string nomos:parentSid = ${quote(retirement.parentSid)}`]),
+  ];
+}
+
 function emitAggregate(
   aggregate: LawAggregateNode,
   fields: readonly LawFieldNode[],

package/src/stable_ids_for_module.ts

@@ -170,7 +170,7 @@ function fieldEvolutionRules(
       fieldSid,
       declaration.source.kind,
       source.contract,
-      driver,
+      encodeDriver(declaration.source.driver),
     );
     if (declaration.mode === "identity" && !safeIdentityProjection(source.shape, target.shape)) {
       throw new Error(