@githolon/dsl 0.113.4 → 0.115.0

package/src/baseline_export.ts

@@ -0,0 +1,432 @@
+// NOMOS — EXPORT A RELEASED BASELINE FROM CUSTODY (architecture/domain_release_lifecycle.md, step 1).
+//
+// Input: a verified law unit set — the compiler's `build/<name>.units`, a release's units downloaded
+// from the console registry, or the units a workspace's installed law names. Every unit hash is
+// re-derived from the bytes before any opinion is read (release_inspection.ts `readInspectionUnits`),
+// so the baseline can only ever describe law that actually exists.
+//
+// Output: the continuity released law carries, in the baseline artifact (baseline_usda.ts):
+//
+//   * every ledger-minted declaration — its sid (the prim name), current label, prior labels and
+//     parent — with the generation recovered by re-minting (law_identity.ts mints a sid from
+//     `kind:parent:label:generation`, so the generation is provable from the sid, never guessed);
+//   * every retirement the released law declares, as a tombstone;
+//   * every operation field's transport allocation (canonical wire key + aliases), top-level and
+//     nested, under the ledger coordinate law_graph.ts allocates it by (wire_paths.ts).
+//
+// What released law does NOT carry — value contracts, merge drivers, tombstones older than the
+// release's own declarations — stays in `nomos.identity.usda`. The baseline is the anchor, not
+// the ledger. Prims whose sid is owned or structural (payload contracts, anonymous value types) are
+// not identities the compiler reconciles, so they are read for their wire keys and nothing else.
+import { createHash } from "node:crypto";
+import { readInspectionUnits } from "./release_inspection.js";
+import { lawUnitSetIdentityWith } from "./law_unit_set_identity.js";
+import {
+  LAW_FRAMEWORK_PARENT,
+  lawEntityKey,
+  validateLawIdentityRegistry,
+  type LawEntityKind,
+  type LawIdentityEntity,
+  type LawIdentityRegistry,
+} from "./law_identity.js";
+import {
+  mintAggregateSid,
+  mintDomainSid,
+  mintFieldSid,
+  mintGlobalAggregateSid,
+  mintStableId,
+} from "./stable_ids.js";
+import type { StableAggregateId, StableFieldId, StableIds } from "./stable_ids_types.js";
+import type { CompilerIdentityModel } from "./identity_model.js";
+import {
+  indexUsdaPrims,
+  readUsdaPrims,
+  usdaChild,
+  usdaString,
+  usdaStringList,
+  type UsdaPrim,
+} from "./law_layer_prims.js";
+import {
+  BASELINE_NO_RELEASE,
+  serializeBaselineUsda,
+  baselineSha256,
+  type BaselineSource,
+  type BaselineWireAllocation,
+  type ReleasedBaseline,
+} from "./baseline_usda.js";
+import { listElementPath, mapValuePath, nestedMemberPath, unionVariantPath } from "./wire_paths.js";
+
+/** The deepest generation re-minting looks for. A label recreated more often than this is unheard of. */
+const MAX_RECOVERED_GENERATION = 64;
+
+const sha256Hex = (bytes: Uint8Array): string => createHash("sha256").update(bytes).digest("hex");
+
+/** Container prim name → the entity kind its children declare. */
+const CONTAINER_KINDS: Readonly<Record<string, LawEntityKind>> = {
+  Aggregates: "aggregate",
+  Types: "type",
+  ObjectTypes: "object-type",
+  Contracts: "contract",
+  Relations: "relation",
+  Intents: "intent",
+  Reads: "read",
+  Policies: "policy",
+  Invariants: "invariant",
+  Capabilities: "capability",
+  WorkspaceTypes: "workspace-type",
+  Flows: "flow",
+};
+
+const SID = /^[0-9a-f]{16}$/u;
+
+export interface BaselineExportInput {
+  /** A directory of law units (`build/<name>.units` or a materialised release). */
+  readonly unitsDir: string;
+  readonly source: BaselineSource;
+  readonly release?: string;
+  readonly series?: string;
+  readonly predecessor?: string;
+  readonly workspace?: string;
+  readonly workspaceHead?: string;
+}
+
+export interface BaselineExport {
+  readonly baseline: ReleasedBaseline;
+  /** The artifact bytes, deterministic for the same units and provenance. */
+  readonly text: string;
+  /** Its content address — what `nomos.project.ts` pins. */
+  readonly sha256: string;
+  /** Declarations whose sid is owned or structural; read for wire keys only. */
+  readonly nonLedgerPrims: number;
+}
+
+interface ScannedEntity {
+  readonly key: string;
+  readonly entity: LawIdentityEntity;
+}
+
+function generationOf(
+  kind: LawEntityKind,
+  parent: string | undefined,
+  labels: readonly string[],
+  sid: string,
+): number | undefined {
+  for (const label of labels) {
+    for (let generation = 0; generation <= MAX_RECOVERED_GENERATION; generation += 1) {
+      if (mintStableId(`law-entity:${kind}:${parent ?? "@root"}:${label}:generation:${generation}`) === sid) {
+        return generation;
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Prove that `sid` is a ledger identity for (kind, parent, label lineage): either minted by
+ * law_identity.ts (generation recovered) or a legacy stable_ids.ts mint (generation 0). Returns the
+ * parent the ledger reconciles it under — a framework aggregate's is `@framework`, not its domain.
+ */
+function classifyLedgerEntity(
+  kind: LawEntityKind,
+  parent: string | undefined,
+  domainSid: string | undefined,
+  labels: readonly string[],
+  sid: string,
+): { parent: string | undefined; generation: number } | undefined {
+  const generation = generationOf(kind, parent, labels, sid);
+  if (generation !== undefined) return { parent, generation };
+  if (kind === "aggregate") {
+    const framework = generationOf(kind, LAW_FRAMEWORK_PARENT, labels, sid);
+    if (framework !== undefined) return { parent: LAW_FRAMEWORK_PARENT, generation: framework };
+    if (labels.some((label) => mintGlobalAggregateSid(label) === sid)) return { parent: LAW_FRAMEWORK_PARENT, generation: 0 };
+    if (domainSid !== undefined && labels.some((label) => mintAggregateSid(domainSid, label) === sid)) {
+      return { parent, generation: 0 };
+    }
+  }
+  if (kind === "domain" && labels.some((label) => mintDomainSid(label) === sid)) return { parent: undefined, generation: 0 };
+  if (kind === "field" && parent !== undefined) {
+    const parentSid = parent.slice(parent.indexOf("_") + 1);
+    if (labels.some((label) => mintFieldSid(parentSid, label) === sid)) return { parent, generation: 0 };
+  }
+  return undefined;
+}
+
+function sidOf(prim: UsdaPrim): string | undefined {
+  const split = prim.name.indexOf("_");
+  const sid = split === -1 ? "" : prim.name.slice(split + 1);
+  return SID.test(sid) ? sid : undefined;
+}
+
+/** Walk one domain layer for its ledger entities, declared retirements and stable-id surface. */
+function scanDomainLayer(
+  domainPrim: UsdaPrim,
+  out: { entities: ScannedEntity[]; nonLedger: { value: number } },
+): { name: string; stableIds: StableIds } | undefined {
+  const domainSid = sidOf(domainPrim);
+  const domainLabel = usdaString(domainPrim, "label");
+  if (domainSid === undefined || domainLabel === undefined) return undefined;
+  const domainLabels = [domainLabel, ...(usdaStringList(domainPrim, "was") ?? [])];
+  const domainClass = classifyLedgerEntity("domain", undefined, undefined, domainLabels, domainSid);
+  const domainKey = lawEntityKey("domain", domainSid);
+  if (domainClass !== undefined) {
+    out.entities.push({
+      key: domainKey,
+      entity: {
+        kind: "domain",
+        sid: domainSid,
+        label: domainLabel,
+        ...(domainLabels.length > 1 ? { priorLabels: domainLabels.slice(1) } : {}),
+        generation: domainClass.generation,
+        status: "active",
+      },
+    });
+  } else {
+    out.nonLedger.value += 1;
+  }
+
+  const aggregates: Record<string, StableAggregateId> = {};
+  const scanFields = (owner: UsdaPrim, ownerKey: string): Record<string, StableFieldId> => {
+    const fields: Record<string, StableFieldId> = {};
+    for (const fieldPrim of usdaChild(owner, "Fields")?.children ?? []) {
+      const sid = sidOf(fieldPrim);
+      const label = usdaString(fieldPrim, "label");
+      if (sid === undefined || label === undefined) continue;
+      const was = usdaStringList(fieldPrim, "was") ?? [];
+      const classified = classifyLedgerEntity("field", ownerKey, undefined, [label, ...was], sid);
+      if (classified === undefined) {
+        out.nonLedger.value += 1;
+        continue;
+      }
+      out.entities.push({
+        key: lawEntityKey("field", sid),
+        entity: {
+          kind: "field",
+          sid,
+          parent: ownerKey,
+          label,
+          ...(was.length > 0 ? { priorLabels: was } : {}),
+          generation: classified.generation,
+          status: "active",
+        },
+      });
+      fields[label] = { sid, ...(was.length > 0 ? { was: [...was] } : {}) };
+    }
+    return fields;
+  };
+
+  for (const container of domainPrim.children) {
+    const kind = CONTAINER_KINDS[container.name];
+    if (kind === undefined) continue;
+    for (const prim of container.children) {
+      const sid = sidOf(prim);
+      const label = usdaString(prim, "label");
+      if (sid === undefined || label === undefined) continue;
+      const was = usdaStringList(prim, "was") ?? [];
+      const classified = classifyLedgerEntity(kind, domainKey, domainSid, [label, ...was], sid);
+      if (classified === undefined) {
+        out.nonLedger.value += 1;
+        continue;
+      }
+      const key = lawEntityKey(kind, sid);
+      out.entities.push({
+        key,
+        entity: {
+          kind,
+          sid,
+          ...(classified.parent === undefined ? {} : { parent: classified.parent }),
+          label,
+          ...(was.length > 0 ? { priorLabels: was } : {}),
+          generation: classified.generation,
+          status: "active",
+        },
+      });
+      if (kind === "aggregate") {
+        const fields = scanFields(prim, key);
+        aggregates[label] = { sid, ...(was.length > 0 ? { was: [...was] } : {}), fields };
+      } else if (kind === "contract") {
+        scanFields(prim, key);
+      }
+    }
+  }
+
+  for (const retirement of usdaChild(domainPrim, "Retirements")?.children ?? []) {
+    const kind = usdaString(retirement, "entityKind");
+    const sid = usdaString(retirement, "sid");
+    const label = usdaString(retirement, "label");
+    if ((kind !== "aggregate" && kind !== "field") || sid === undefined || label === undefined || !SID.test(sid)) continue;
+    const parentSid = usdaString(retirement, "parentSid");
+    const parent = kind === "field"
+      ? (parentSid === undefined ? undefined : lawEntityKey("aggregate", parentSid))
+      : domainKey;
+    const classified = classifyLedgerEntity(kind, parent, domainSid, [label], sid);
+    if (classified === undefined) {
+      out.nonLedger.value += 1;
+      continue;
+    }
+    out.entities.push({
+      key: lawEntityKey(kind, sid),
+      entity: {
+        kind,
+        sid,
+        ...(classified.parent === undefined ? {} : { parent: classified.parent }),
+        label,
+        generation: classified.generation,
+        status: "retired",
+      },
+    });
+  }
+
+  return { name: domainLabel, stableIds: { v: 1, domain: domainSid, aggregates } };
+}
+
+/** Walk an intent's payload contracts for every field's transport allocation, nested included. */
+function scanWireAllocations(
+  intentPrim: UsdaPrim,
+  prims: ReadonlyMap<string, UsdaPrim>,
+  out: BaselineWireAllocation[],
+): void {
+  const intentSid = sidOf(intentPrim);
+  if (intentSid === undefined) return;
+  const intent = lawEntityKey("intent", intentSid);
+  const seen = new Set<string>();
+  const allocate = (field: UsdaPrim, path: string): void => {
+    const canonical = usdaString(field, "wireKey");
+    if (canonical === undefined) return;
+    const aliases = usdaStringList(field, "wireAliases") ?? [];
+    const coordinate = `${intent}\u0000${path}`;
+    if (seen.has(coordinate)) return;
+    seen.add(coordinate);
+    out.push({ intent, field: path, protobuf: { canonical, ...(aliases.length > 0 ? { aliases } : {}) } });
+  };
+  const walkType = (typePath: string | undefined, path: string, visiting: ReadonlySet<string>): void => {
+    if (typePath === undefined || visiting.has(typePath)) return;
+    const type = prims.get(typePath);
+    if (type === undefined) return;
+    const next = new Set(visiting).add(typePath);
+    switch (usdaString(type, "typeKind")) {
+      case "record":
+        for (const field of usdaChild(type, "Fields")?.children ?? []) walkField(field, path, next);
+        break;
+      case "list":
+        walkType(type.rels.get("elementType")?.[0], listElementPath(path), next);
+        break;
+      case "map":
+        walkType(type.rels.get("valueType")?.[0], mapValuePath(path), next);
+        break;
+      case "union": {
+        const variants = usdaChild(type, "Variants")?.children ?? [];
+        variants.forEach((variant, index) => {
+          const label = usdaString(variant, "label") ?? String(index);
+          walkType(variant.rels.get("type")?.[0], unionVariantPath(path, label), next);
+        });
+        break;
+      }
+      case "recursive":
+        walkType(type.rels.get("body")?.[0], path, next);
+        break;
+      default:
+        break;
+    }
+  };
+  const walkField = (field: UsdaPrim, parentPath: string, visiting: ReadonlySet<string>): void => {
+    const label = usdaString(field, "label");
+    if (label === undefined) return;
+    const path = parentPath === "" ? label : nestedMemberPath(parentPath, label);
+    allocate(field, path);
+    walkType(field.rels.get("type")?.[0], path, visiting);
+  };
+  for (const relation of ["accepts", "publicAccepts"]) {
+    const contract = prims.get(intentPrim.rels.get(relation)?.[0] ?? "");
+    if (contract === undefined) continue;
+    for (const field of usdaChild(contract, "Fields")?.children ?? []) walkField(field, "", new Set());
+  }
+}
+
+/** Order entities so every parent precedes its children (validation and import both need it). */
+function orderByParent(entities: readonly ScannedEntity[]): ScannedEntity[] {
+  const byKey = new Map(entities.map((scanned) => [scanned.key, scanned]));
+  const ordered: ScannedEntity[] = [];
+  const placed = new Set<string>();
+  const place = (scanned: ScannedEntity, trail: ReadonlySet<string>): void => {
+    if (placed.has(scanned.key)) return;
+    const parent = scanned.entity.parent;
+    if (parent !== undefined && parent !== LAW_FRAMEWORK_PARENT && !trail.has(parent)) {
+      const parentEntity = byKey.get(parent);
+      if (parentEntity !== undefined) place(parentEntity, new Set(trail).add(scanned.key));
+    }
+    placed.add(scanned.key);
+    ordered.push(scanned);
+  };
+  for (const scanned of [...entities].sort((l, r) => (l.key < r.key ? -1 : l.key > r.key ? 1 : 0))) place(scanned, new Set());
+  return ordered;
+}
+
+/** Export the baseline a verified unit set carries. Throws on unverifiable units or an unreadable layer. */
+export function exportBaselineFromUnits(input: BaselineExportInput): BaselineExport {
+  const units = readInspectionUnits(input.unitsDir);
+  const unitSet = lawUnitSetIdentityWith(sha256Hex, units.map((unit) => ({ key: unit.key, unitHash: unit.hash })));
+
+  const roots: UsdaPrim[] = [];
+  for (const unit of units) {
+    for (const asset of unit.assets) {
+      if (!/^domains\/[^/]+\.usda$/u.test(asset.logicalPath) && asset.logicalPath !== "framework.usda") continue;
+      roots.push(...readUsdaPrims(new TextDecoder().decode(asset.bytes)));
+    }
+  }
+  const prims = indexUsdaPrims(roots);
+
+  const scanned = { entities: [] as ScannedEntity[], nonLedger: { value: 0 } };
+  const domains: CompilerIdentityModel["domains"] = {};
+  const wireAllocations: BaselineWireAllocation[] = [];
+  for (const [primPath, prim] of prims) {
+    if (!/^\/Nomos\/Domains\/d_[0-9a-f]{16}$/u.test(primPath)) continue;
+    const domain = scanDomainLayer(prim, scanned);
+    if (domain !== undefined) domains[domain.name] = { stableIds: domain.stableIds };
+    for (const intent of usdaChild(prim, "Intents")?.children ?? []) scanWireAllocations(intent, prims, wireAllocations);
+  }
+
+  const entities: Record<string, LawIdentityEntity> = {};
+  for (const { key, entity } of orderByParent(scanned.entities)) {
+    const prior = entities[key];
+    if (prior !== undefined) {
+      // One framework aggregate composed into several domain layers is one identity; the layers agree.
+      if (prior.kind !== entity.kind || prior.label !== entity.label) {
+        throw new Error(`baseline export: ${key} is declared as '${prior.label}' and '${entity.label}' in the same unit set`);
+      }
+      continue;
+    }
+    // A field's aggregate or a retirement's parent must be a ledger entity of this set; a child of a
+    // non-ledger prim (an owned contract's field) is read for wire keys elsewhere, not as identity.
+    const parent = entity.parent;
+    if (parent !== undefined && parent !== LAW_FRAMEWORK_PARENT && entities[parent] === undefined) {
+      scanned.nonLedger.value += 1;
+      continue;
+    }
+    entities[key] = entity;
+  }
+  const identity: LawIdentityRegistry = {
+    v: 1,
+    entities: Object.fromEntries(Object.entries(entities).sort(([l], [r]) => (l < r ? -1 : l > r ? 1 : 0))),
+  };
+  validateLawIdentityRegistry(identity);
+
+  const baselineBody: Omit<ReleasedBaseline, "format"> = {
+    source: input.source,
+    release: input.release ?? BASELINE_NO_RELEASE,
+    series: input.series ?? "",
+    predecessor: input.predecessor ?? "",
+    unitSet,
+    units: units.map((unit) => ({ key: unit.key, unitHash: unit.hash })),
+    workspace: input.workspace ?? "",
+    workspaceHead: input.workspaceHead ?? "",
+    continuity: { v: 1, domains, identity },
+    wireAllocations: [...wireAllocations].sort((l, r) => (l.intent < r.intent ? -1 : l.intent > r.intent ? 1 : l.field < r.field ? -1 : l.field > r.field ? 1 : 0)),
+  };
+  const text = serializeBaselineUsda(baselineBody);
+  return {
+    baseline: { format: "nomos.baseline.v1", ...baselineBody },
+    text,
+    sha256: baselineSha256(text),
+    nonLedgerPrims: scanned.nonLedger.value,
+  };
+}