@githolon/dsl 0.49.0 → 0.51.0

package/src/evolve_preview.ts

@@ -0,0 +1,466 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine}.  If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * 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 / RETYPE refuses TYPED unless the deploy JSON carries a `dispositions`
+ * ({retired:[sid], retyped:{sid:why}, rebinds:{newSid:oldSid}}) acknowledging it in-history.
+ *
+ * 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
+ * dispositions fragment (pre-filled with the real sids) inside the refusal's `fix`, so the dev
+ * pastes it into their deploy JSON and the real deploy admits. It classifies:
+ *
+ *   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].
+ *   RETYPE   (refuse) — same sid, changed read-kind or merge-driver; needs dispositions.retyped.
+ *   PAYLOAD  (warn)   — a directive's payload shape changed; clients compiled against the old
+ *                       law get typed 422s until regenerated (directives are not sid-tracked).
+ *
+ * The preview NEVER needs to emit a `rebinds` fragment: a rename is detected by a MATCHED sid
+ * (the compiler carries it via the nomos.stable-ids.json lockfile), so it is already a silent
+ * admit — rebinds is only for the hand-repair path where the sid was lost, which this preview,
+ * reading the carried sids, never produces.
+ */
+import type { Finding } from "./law_check.js";
+import type { DirectivePayloadShape, DomainInterface } from "./shape_compat.js";
+import { domainInterface } from "./shape_compat.js";
+import type { StableIds } from "./stable_ids_types.js";
+import type { DomainModule } from "./codegen_dart.js";
+import type { WireSchema } from "./wire.js";
+
+// ── the normalized law shape both sides of the diff speak ──────────────────────────
+
+/** One aggregate's evolve-relevant surface: its stable id, current label, and its fields
+ *  keyed by FIELD SID (so a rename is a label move, not a new key). */
+export interface EvolveAggregate {
+  readonly sid: string;
+  readonly label: string;
+  /** keyed by FIELD SID. `driver` is the merge-law JSON (from the lockfile/usda schemas)
+   *  when known — it lets the retype arm catch a driver-only change (same read kind). */
+  readonly fields: Record<string, { sid: string; label: string; kind: string; driver?: string }>;
+}
+
+/** One domain's evolve surface: aggregates (sid-keyed) + directive payload shapes (name-keyed). */
+export interface EvolveDomain {
+  readonly domainSid?: string;
+  /** keyed by AGGREGATE SID. */
+  readonly aggregates: Record<string, EvolveAggregate>;
+  /** keyed by DIRECTIVE ID (directives are not sid-tracked — the dispatched name IS identity). */
+  readonly directives: Record<string, DirectivePayloadShape>;
+}
+
+/** A whole package's evolve surface, keyed by DOMAIN KEY. */
+export type EvolveLaw = Record<string, EvolveDomain>;
+
+/** The dispositions fragment the deploy JSON 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
+ *  schemas keyed by CURRENT aggregate label). The sids/kinds come from the stable-id block;
+ *  the drivers (when supplied) sharpen the retype arm. */
+function aggregatesFromStableIds(
+  stableIds: StableIds | undefined,
+  schemas?: Record<string, WireSchema>,
+): Record<string, EvolveAggregate> {
+  const out: Record<string, EvolveAggregate> = {};
+  if (stableIds?.aggregates === undefined) return out;
+  for (const [aggLabel, a] of Object.entries(stableIds.aggregates)) {
+    const fields: EvolveAggregate["fields"] = {};
+    for (const [fLabel, f] of Object.entries(a.fields ?? {})) {
+      const driver = schemas?.[aggLabel]?.[fLabel];
+      fields[f.sid] = {
+        sid: f.sid,
+        label: fLabel,
+        kind: f.kind ?? "",
+        ...(driver !== undefined ? { driver: JSON.stringify(driver) } : {}),
+      };
+    }
+    out[a.sid] = { sid: a.sid, label: aggLabel, fields };
+  }
+  return out;
+}
+
+/** Build an EvolveDomain from a DomainInterface (deploy.json's `interface`) — its aggregates are
+ *  already sid-keyed with kinds+labels, its directives carry payload shapes. Drivers are absent
+ *  from an interface (it exposes only read kinds), so a driver-only retype is not seen from an
+ *  interface alone — the lockfile lane (aggregatesFromStableIds + schemas) carries them. */
+function evolveDomainFromInterface(iface: DomainInterface): EvolveDomain {
+  const aggregates: Record<string, EvolveAggregate> = {};
+  for (const [aggSid, a] of Object.entries(iface.aggregates ?? {})) {
+    const fields: EvolveAggregate["fields"] = {};
+    for (const [fSid, f] of Object.entries(a.fields ?? {})) {
+      fields[fSid] = { sid: fSid, label: f.label, kind: f.kind };
+    }
+    aggregates[aggSid] = { sid: a.sid ?? aggSid, label: a.label, fields };
+  }
+  return {
+    ...(iface.domainSid !== undefined ? { domainSid: iface.domainSid } : {}),
+    aggregates,
+    directives: iface.directives ?? {},
+  };
+}
+
+/** The committed `nomos.stable-ids.json` lockfile shape (compile_package_main writes it). */
+export interface StableIdLockfile {
+  v: 1;
+  domains: Record<string, { stableIds: StableIds; schemas?: Record<string, WireSchema> }>;
+}
+
+/** A deploy.json body (the subset this preview reads): the per-domain interface + the package
+ *  bytes (for the embedded stable-ids/driver schemas when no lockfile rides alongside). */
+export interface DeployJson {
+  interface?: Record<string, DomainInterface>;
+  packageUsda?: string;
+}
+
+/** Extract the embedded USD-IR JSON from a `.package.usda` bundle (the `nomos:usdJsonHex` field —
+ *  the SAME substring contract executor/src/law58.rs::usd_json_from_package uses). */
+export function usdJsonFromPackage(bundle: string): unknown | undefined {
+  const key = 'nomos:usdJsonHex = "';
+  const start = bundle.indexOf(key);
+  if (start < 0) return undefined;
+  const from = start + key.length;
+  const end = bundle.indexOf('"', from);
+  if (end < 0) return undefined;
+  const hex = bundle.slice(from, end);
+  if (hex.length % 2 !== 0) return undefined;
+  try {
+    const bytes = Buffer.from(hex, "hex");
+    return JSON.parse(bytes.toString("utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+/** Per-domain-key { stableIds, schemas } parsed out of a package's embedded USD-IR (mirrors
+ *  executor/src/law58.rs::stable_ids_from_usd + the aggregate-prim schema harvest). */
+export function stableIdsFromUsd(
+  usd: unknown,
+): Record<string, { stableIds: StableIds; schemas: Record<string, WireSchema> }> {
+  const out: Record<string, { stableIds: StableIds; schemas: Record<string, WireSchema> }> = {};
+  const layers = (usd as { layers?: unknown[] })?.layers;
+  if (!Array.isArray(layers)) return out;
+  for (const layer of layers) {
+    const l = layer as {
+      path?: string;
+      nomosStableIds?: StableIds;
+      prims?: Array<{ kind?: string; type?: string; schema?: Record<string, unknown> }>;
+    };
+    const path = typeof l.path === "string" ? l.path : "";
+    const key = path.startsWith("/Nomos/") ? path.slice("/Nomos/".length) : "";
+    if (key === "" || l.nomosStableIds === undefined) continue;
+    const schemas: Record<string, WireSchema> = {};
+    for (const prim of l.prims ?? []) {
+      if (prim.kind === "aggregate" && typeof prim.type === "string" && prim.schema) {
+        schemas[prim.type] = prim.schema as WireSchema;
+      }
+    }
+    out[key] = { stableIds: l.nomosStableIds, schemas };
+  }
+  return out;
+}
+
+/** Build an EvolveLaw from a deploy.json body: interface for directive payloads + sid-keyed read
+ *  shapes, and the embedded package USD-IR for the driver schemas (so a driver-only retype is
+ *  seen from a deploy.json alone). */
+export function evolveLawFromDeployJson(deploy: DeployJson): EvolveLaw {
+  const law: EvolveLaw = {};
+  const ifaces = deploy.interface ?? {};
+  const usd = deploy.packageUsda !== undefined ? usdJsonFromPackage(deploy.packageUsda) : undefined;
+  const fromUsd = usd !== undefined ? stableIdsFromUsd(usd) : {};
+  for (const [key, iface] of Object.entries(ifaces)) {
+    const dom = evolveDomainFromInterface(iface);
+    // Augment fields with drivers off the package USD-IR schemas (interface carries none).
+    const usdDom = fromUsd[key];
+    if (usdDom !== undefined) {
+      for (const agg of Object.values(dom.aggregates)) {
+        const schema = usdDom.schemas[agg.label];
+        if (schema === undefined) continue;
+        for (const f of Object.values(agg.fields)) {
+          const driver = schema[f.label];
+          if (driver !== undefined) (f as { driver?: string }).driver = JSON.stringify(driver);
+        }
+      }
+    }
+    law[key] = dom;
+  }
+  // A deploy.json with NO interface (older builds) still yields aggregate identity from the USD.
+  for (const [key, sd] of Object.entries(fromUsd)) {
+    if (law[key] !== undefined) continue;
+    law[key] = { domainSid: sd.stableIds.domain, aggregates: aggregatesFromStableIds(sd.stableIds, sd.schemas), directives: {} };
+  }
+  return law;
+}
+
+/** Build an EvolveLaw from a `nomos.stable-ids.json` lockfile — aggregate identity + drivers, but
+ *  NO directive payloads (a lockfile carries no interface). Directive-level warnings are then
+ *  unavailable; the caller notes it. */
+export function evolveLawFromLockfile(lock: StableIdLockfile): EvolveLaw {
+  const law: EvolveLaw = {};
+  for (const [key, d] of Object.entries(lock.domains ?? {})) {
+    law[key] = {
+      domainSid: d.stableIds?.domain,
+      aggregates: aggregatesFromStableIds(d.stableIds, d.schemas),
+      directives: {},
+    };
+  }
+  return law;
+}
+
+/** Build the CURRENT build's EvolveLaw from the composed modules (directive payloads + sid-keyed
+ *  read shapes via `domainInterface`) plus the committed lockfile (the current sids/drivers). When
+ *  no lockfile is present the interface falls back to NAME-keyed identity (domainInterface's
+ *  pre-#58 fallback) — a rename then reads as removal+add; the caller warns to compile first. */
+export function currentEvolveLaw(
+  modules: readonly DomainModule[],
+  lock?: StableIdLockfile,
+): EvolveLaw {
+  const law: EvolveLaw = {};
+  for (const mod of modules) {
+    const key = mod.domain ?? mod.name;
+    const locked = lock?.domains[mod.name] ?? lock?.domains[key];
+    const stableIds = locked?.stableIds;
+    const iface = domainInterface(mod, stableIds);
+    const dom = evolveDomainFromInterface(iface);
+    // Fold drivers from the lockfile schemas (interface has none).
+    if (locked?.schemas !== undefined) {
+      for (const agg of Object.values(dom.aggregates)) {
+        const schema = locked.schemas[agg.label];
+        if (schema === undefined) continue;
+        for (const f of Object.values(agg.fields)) {
+          const driver = schema[f.label];
+          if (driver !== undefined) (f as { driver?: string }).driver = JSON.stringify(driver);
+        }
+      }
+    }
+    law[key] = dom;
+  }
+  return law;
+}
+
+// ── the diff ────────────────────────────────────────────────────────────────────────
+
+/** The full preview result: the findings AND the merged dispositions the destructive findings
+ *  demand, keyed by DOMAIN KEY (exactly the object a deploy JSON carries per installDomain). */
+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). */
+function payloadShapeText(shape: DirectivePayloadShape): string {
+  const parts = Object.entries(shape.fields ?? {})
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+    .map(([n, f]) => `${n}:${f.kind}${f.optional ? "?" : ""}`);
+  return `{ ${parts.join(", ")} }`;
+}
+
+function ensureDisp(map: Record<string, EvolveDispositionsJson>, domain: string): EvolveDispositionsJson {
+  return (map[domain] ??= {});
+}
+
+/** Diff one domain's aggregates/fields/directives BY STABLE ID and append findings + dispositions. */
+function diffDomain(
+  domain: string,
+  prior: EvolveDomain,
+  current: EvolveDomain,
+  findings: Finding[],
+  disp: Record<string, EvolveDispositionsJson>,
+): void {
+  const curAggBySid = current.aggregates;
+  const priorAggBySid = prior.aggregates;
+
+  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);
+      findings.push({
+        domain,
+        level: "refuse",
+        what: `aggregate '${oldAgg.label}' (stable id ${sid}) is REMOVED — the evolve gate will refuse without a disposition`,
+        fix: `paste into your deploy JSON: "dispositions": { "retired": ["${sid}"] }`,
+      });
+      continue;
+    }
+    if (newAgg.label !== oldAgg.label) {
+      findings.push({
+        domain,
+        level: "note",
+        what: `aggregate renamed '${oldAgg.label}' → '${newAgg.label}' (stable id ${sid})`,
+        fix: `admits silently; old rows read the new label — no disposition needed`,
+      });
+    }
+    // FIELD diff within the matched aggregate.
+    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);
+        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: `paste into your deploy JSON: "dispositions": { "retired": ["${fSid}"] }`,
+        });
+        continue;
+      }
+      if (newF.label !== oldF.label) {
+        findings.push({
+          domain,
+          level: "note",
+          what: `field renamed '${oldAgg.label}.${oldF.label}' → '${newAgg.label}.${newF.label}' (stable id ${fSid})`,
+          fix: `admits silently; old rows read the new label — no disposition needed`,
+        });
+      }
+      const kindChanged = oldF.kind !== "" && newF.kind !== "" && oldF.kind !== newF.kind;
+      const driverChanged =
+        oldF.driver !== undefined && newF.driver !== undefined && oldF.driver !== newF.driver;
+      if (kindChanged || driverChanged) {
+        const d = ensureDisp(disp, domain);
+        (d.retyped ??= {})[fSid] = "<why goes here>";
+        const how = kindChanged
+          ? `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: `paste into your deploy JSON: "dispositions": { "retyped": { "${fSid}": "<why goes here>" } } — or add a NEW field instead`,
+        });
+      }
+    }
+    // ADDITIVE fields (new sid within a surviving aggregate) — safe, admits silently.
+    for (const [fSid, newF] of Object.entries(newAgg.fields)) {
+      if (oldAgg.fields[fSid] !== undefined) continue;
+      findings.push({
+        domain,
+        level: "note",
+        what: `field '${newAgg.label}.${newF.label}' (stable id ${fSid}) is ADDED`,
+        fix: `additive — the evolve gate admits it silently; old rows read it absent (an optional field)`,
+      });
+    }
+  }
+  // ADDITIVE aggregates (new sid) — safe, admits silently.
+  for (const [sid, newAgg] of Object.entries(curAggBySid)) {
+    if (priorAggBySid[sid] !== undefined) continue;
+    findings.push({
+      domain,
+      level: "note",
+      what: `aggregate '${newAgg.label}' (stable id ${sid}) is ADDED`,
+      fix: `additive — the evolve gate admits it silently`,
+    });
+  }
+
+  // DIRECTIVES (name-keyed — not sid-tracked). A payload-shape change is a client break, not an
+  // evolve-gate refusal, so it is a WARN naming old vs new shape.
+  for (const [id, oldShape] of Object.entries(prior.directives)) {
+    const newShape = current.directives[id];
+    if (newShape === undefined) {
+      findings.push({
+        domain,
+        directiveId: id,
+        level: "warn",
+        what: `directive '${id}' is REMOVED — clients still calling it get a typed 422 until they drop/regenerate`,
+        fix: `keep it, or confirm every client stopped dispatching '${id}' before deploying`,
+      });
+      continue;
+    }
+    if (!samePayloadShape(oldShape, newShape)) {
+      findings.push({
+        domain,
+        directiveId: id,
+        level: "warn",
+        what: `directive '${id}' payload shape changed ${payloadShapeText(oldShape)} → ${payloadShapeText(newShape)} — clients compiled against the old law get typed 422s until regenerated`,
+        fix: `regenerate + redeploy dependent clients (the '.client.ts'/Dart surface) against the new law`,
+      });
+    }
+  }
+  for (const id of Object.keys(current.directives)) {
+    if (prior.directives[id] !== undefined) continue;
+    findings.push({
+      domain,
+      directiveId: id,
+      level: "note",
+      what: `directive '${id}' is ADDED`,
+      fix: `additive — a new write lane; no prior client depended on it`,
+    });
+  }
+}
+
+/** Do two directive payload shapes accept the same clients? (same field set, kinds, optionality). */
+function samePayloadShape(a: DirectivePayloadShape, b: DirectivePayloadShape): boolean {
+  const af = a.fields ?? {};
+  const bf = b.fields ?? {};
+  const names = new Set([...Object.keys(af), ...Object.keys(bf)]);
+  for (const n of names) {
+    const x = af[n];
+    const y = bf[n];
+    if (x === undefined || y === undefined) return false;
+    if (x.kind !== y.kind || !!x.optional !== !!y.optional) return false;
+  }
+  return true;
+}
+
+/**
+ * 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).
+ */
+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 (a true removal) redeploy with "dispositions": { "retired": ["${sid}"] }`,
+        });
+      }
+      continue;
+    }
+    diffDomain(domain, priorDom, currentDom, findings, dispositions);
+  }
+  for (const [domain, currentDom] of Object.entries(current)) {
+    if (prior[domain] !== undefined) continue;
+    findings.push({
+      domain,
+      level: "note",
+      what: `domain '${domain}' is ADDED (${Object.keys(currentDom.aggregates).length} aggregate(s))`,
+      fix: `additive — a new domain installs beside the existing law`,
+    });
+  }
+
+  const rank = { refuse: 0, warn: 1, note: 2 } as const;
+  findings.sort((a, b) => rank[a.level] - rank[b.level]);
+  return { findings, dispositions };
+}
+
+/** The findings-only surface (the `evolvePreview(prior, current): Finding[]` contract). */
+export function evolvePreview(prior: EvolveLaw, current: EvolveLaw): Finding[] {
+  return evolveDiff(prior, current).findings;
+}