@githolon/dsl 0.105.5 → 0.105.6

package/src/identity_model.ts

@@ -0,0 +1,123 @@
+import type { StableIds } from "./stable_ids_types.js";
+import type { WireSchema } from "./wire.js";
+import { mintGlobalAggregateSid } from "./stable_ids.js";
+import {
+  LAW_FRAMEWORK_PARENT,
+  emptyLawIdentityRegistry,
+  lawEntityKey,
+  validateLawIdentityRegistry,
+  type LawIdentityEntity,
+  type LawIdentityRegistry,
+} from "./law_identity.js";
+
+export interface CompilerIdentityDomain {
+  stableIds: StableIds;
+  schemas?: Record<string, WireSchema>;
+}
+
+/** The materialized lock shape consumed inside the compiler and authoring tools. */
+export interface CompilerIdentityModel {
+  v: 1;
+  domains: Record<string, CompilerIdentityDomain>;
+  /** Compiler-owned entity identity, including retirements. Semantics remain exclusively in USDA. */
+  identity?: LawIdentityRegistry;
+}
+
+/**
+ * Derive the compiler entity registry from domain/aggregate/field SIDs when a first-generation
+ * identity layer has no explicit registry yet. Once present, that registry retains every retirement.
+ */
+export function identityRegistryFromModel(
+  model: CompilerIdentityModel | undefined,
+): LawIdentityRegistry {
+  if (model?.identity !== undefined) {
+    validateLawIdentityRegistry(model.identity);
+    return model.identity;
+  }
+  if (model === undefined) return emptyLawIdentityRegistry();
+
+  const entities: Record<string, LawIdentityEntity> = {};
+  const aggregateOccurrences = new Map<string, number>();
+  for (const domain of Object.values(model.domains)) {
+    for (const aggregate of Object.values(domain.stableIds.aggregates)) {
+      aggregateOccurrences.set(aggregate.sid, (aggregateOccurrences.get(aggregate.sid) ?? 0) + 1);
+    }
+  }
+
+  for (const [domainName, domain] of Object.entries(model.domains).sort(([a], [b]) =>
+    compareText(a, b),
+  )) {
+    const domainKey = importIdentityEntity(entities, {
+      kind: "domain",
+      sid: domain.stableIds.domain,
+      label: domainName,
+      generation: 0,
+      status: "active",
+    });
+    for (const [aggregateName, aggregate] of Object.entries(domain.stableIds.aggregates).sort(
+      ([a], [b]) => compareText(a, b),
+    )) {
+      const parent =
+        (aggregateOccurrences.get(aggregate.sid) ?? 0) > 1 ||
+        aggregate.sid === mintGlobalAggregateSid(aggregateName)
+          ? LAW_FRAMEWORK_PARENT
+          : domainKey;
+      const aggregateKey = importIdentityEntity(entities, {
+        kind: "aggregate",
+        sid: aggregate.sid,
+        parent,
+        label: aggregateName,
+        ...(aggregate.was === undefined ? {} : { priorLabels: aggregate.was }),
+        generation: 0,
+        status: "active",
+      });
+      for (const [fieldName, field] of Object.entries(aggregate.fields).sort(([a], [b]) =>
+        compareText(a, b),
+      )) {
+        importIdentityEntity(entities, {
+          kind: "field",
+          sid: field.sid,
+          parent: aggregateKey,
+          label: fieldName,
+          ...(field.was === undefined ? {} : { priorLabels: field.was }),
+          generation: 0,
+          status: "active",
+        });
+      }
+    }
+  }
+
+  const registry: LawIdentityRegistry = {
+    v: 1,
+    entities: Object.fromEntries(Object.entries(entities).sort(([a], [b]) => compareText(a, b))),
+  };
+  validateLawIdentityRegistry(registry);
+  return registry;
+}
+
+function importIdentityEntity(
+  entities: Record<string, LawIdentityEntity>,
+  entity: LawIdentityEntity,
+): string {
+  const key = lawEntityKey(entity.kind, entity.sid);
+  const prior = entities[key];
+  if (prior === undefined) {
+    entities[key] = entity;
+    return key;
+  }
+  if (
+    prior.kind !== entity.kind ||
+    prior.parent !== entity.parent ||
+    prior.label !== entity.label ||
+    JSON.stringify(prior.priorLabels ?? []) !== JSON.stringify(entity.priorLabels ?? [])
+  ) {
+    throw new Error(
+      `NMS-ID-002 legacy SID ${key} aliases incompatible ${prior.kind} '${prior.label}' and ${entity.kind} '${entity.label}'`,
+    );
+  }
+  return key;
+}
+
+function compareText(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}

package/src/identity_usda.ts

@@ -0,0 +1,548 @@
+// NOMOS — COMPILER IDENTITY CUSTODY, IN TYPED USDA (W4).
+//
+// This is the committed compiler identity layer. The compiler pipeline is
+// `.ts -> .usda` with nothing else in between: the only committed artifact carrying identity
+// forward across compiles is this layer, and it is USDA like everything else Nomos remembers.
+//
+// WHY A COMMITTED LAYER AT ALL. The emitted law closure encodes every ACTIVE entity's identity, but
+// `build/` is deliberately ignored and therefore cannot carry author-time continuity through a clean
+// clone. This small committed layer carries the complete current identity plus every retirement. It
+// is not executable law and no runtime consumes it; it is the compiler's one durable identity source.
+//
+// NO JSON, INCLUDING FOR OPAQUE DESCRIPTORS. A field's canonical value `shape` and merge `driver`
+// are compiler-derived structured values. They are written here through the generic typed-USDA value
+// codec below rather than stringified, so this file has no JSON in it at any depth.
+import {
+  emptyLawIdentityRegistry,
+  lawEntityKeyParts,
+  validateLawIdentityRegistry,
+  type LawIdentityEntity,
+  type LawIdentityRegistry,
+  type LawIdentityStatus,
+} from "./law_identity.js";
+import type { StableAggregateId, StableFieldId, StableIds } from "./stable_ids_types.js";
+import type { CompilerIdentityModel } from "./identity_model.js";
+import type { WireSchema } from "./wire.js";
+
+export const NOMOS_IDENTITY_LAYER_FORMAT = "nomos.identity.v1";
+/** The committed identity layer's filename, beside the package config. */
+export const NOMOS_IDENTITY_FILENAME = "nomos.identity.usda";
+
+function quote(value: string): string {
+  return `"${value.replace(/[\\"\u0000-\u001f]/gu, (character) => {
+    switch (character) {
+      case "\\": return "\\\\";
+      case '"': return '\\"';
+      case "\n": return "\\n";
+      case "\r": return "\\r";
+      case "\t": return "\\t";
+      case "\b": return "\\b";
+      case "\f": return "\\f";
+      default: return `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`;
+    }
+  })}"`;
+}
+
+function parseQuoted(raw: string): string {
+  const value = raw.trim();
+  if (!value.startsWith('"') || !value.endsWith('"')) {
+    throw new Error(`expected a quoted USDA string, got ${value}`);
+  }
+  let out = "";
+  for (let index = 1; index < value.length - 1; index += 1) {
+    const character = value[index]!;
+    if (character !== "\\") {
+      out += character;
+      continue;
+    }
+    index += 1;
+    const escaped = value[index];
+    if (escaped === undefined || index >= value.length - 1) throw new Error("unterminated USDA escape");
+    if (escaped === "u") {
+      const digits = value.slice(index + 1, index + 5);
+      if (!/^[0-9a-fA-F]{4}$/u.test(digits)) throw new Error(`invalid USDA unicode escape \\u${digits}`);
+      out += String.fromCharCode(Number.parseInt(digits, 16));
+      index += 4;
+      continue;
+    }
+    const decoded: Record<string, string> = {
+      "\\": "\\",
+      '"': '"',
+      n: "\n",
+      r: "\r",
+      t: "\t",
+      b: "\b",
+      f: "\f",
+    };
+    const replacement = decoded[escaped];
+    if (replacement === undefined) throw new Error(`unsupported USDA escape \\${escaped}`);
+    out += replacement;
+  }
+  return out;
+}
+
+function parseStringList(raw: string): string[] {
+  const value = raw.trim();
+  if (!value.startsWith("[") || !value.endsWith("]")) throw new Error(`expected a USDA array, got ${value}`);
+  const body = value.slice(1, -1).trim();
+  if (body === "") return [];
+  const items: string[] = [];
+  let start = 0;
+  let quoted = false;
+  let escaped = false;
+  for (let index = 0; index < body.length; index += 1) {
+    const character = body[index]!;
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (quoted && character === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (character === '"') quoted = !quoted;
+    if (!quoted && character === ",") {
+      items.push(parseQuoted(body.slice(start, index)));
+      start = index + 1;
+    }
+  }
+  if (quoted) throw new Error("unterminated USDA string array");
+  items.push(parseQuoted(body.slice(start)));
+  return items;
+}
+const stringList = (items: readonly string[]): string =>
+  `[${items.map((item) => quote(item)).join(", ")}]`;
+const pad = (indent: number): string => " ".repeat(indent);
+
+// ── generic typed-USDA value codec ─────────────────────────────────────────────────────────────
+// A scalar becomes a typed `nomos:value`; a container becomes a Scope whose children are its
+// members. `nomos:valueKind` names the shape so the reader never guesses, and member NAMES are
+// carried in `nomos:key` rather than in the prim name — a JSON object key is arbitrary text and
+// must not be forced through prim-name sanitisation, which is lossy and can collide.
+
+type PlainValue = unknown;
+
+function emitValue(value: PlainValue, primName: string, indent: number, key?: string): string[] {
+  const p = pad(indent);
+  const head = [`${p}def Scope ${quote(primName)}`, `${p}{`];
+  const keyLine = key === undefined ? [] : [`${p}    custom uniform string nomos:key = ${quote(key)}`];
+  const close = [`${p}}`];
+
+  if (value === null || value === undefined) {
+    return [...head, ...keyLine, `${p}    custom uniform string nomos:valueKind = "null"`, ...close];
+  }
+  if (typeof value === "string") {
+    return [
+      ...head, ...keyLine,
+      `${p}    custom uniform string nomos:valueKind = "string"`,
+      `${p}    custom uniform string nomos:value = ${quote(value)}`,
+      ...close,
+    ];
+  }
+  if (typeof value === "boolean") {
+    return [
+      ...head, ...keyLine,
+      `${p}    custom uniform string nomos:valueKind = "bool"`,
+      `${p}    custom uniform bool nomos:value = ${value ? "true" : "false"}`,
+      ...close,
+    ];
+  }
+  if (typeof value === "number") {
+    const isInt = Number.isInteger(value);
+    return [
+      ...head, ...keyLine,
+      `${p}    custom uniform string nomos:valueKind = ${isInt ? '"int"' : '"double"'}`,
+      `${p}    custom uniform ${isInt ? "int64" : "double"} nomos:value = ${isInt ? String(value) : String(value)}`,
+      ...close,
+    ];
+  }
+  if (Array.isArray(value)) {
+    return [
+      ...head, ...keyLine,
+      `${p}    custom uniform string nomos:valueKind = "array"`,
+      ...value.flatMap((item, index) => emitValue(item, `i_${index}`, indent + 4)),
+      ...close,
+    ];
+  }
+  const entries = Object.entries(value as Record<string, PlainValue>)
+    .filter(([, member]) => member !== undefined)
+    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+  return [
+    ...head, ...keyLine,
+    `${p}    custom uniform string nomos:valueKind = "object"`,
+    ...entries.flatMap(([memberKey, member], index) => emitValue(member, `m_${index}`, indent + 4, memberKey)),
+    ...close,
+  ];
+}
+
+// ── reader ─────────────────────────────────────────────────────────────────────────────────────
+// A deliberately small structural reader for the exact subset this compiler writes. It is not a
+// general USD parser: it reads `def Scope "<name>" { … }` nesting and `custom uniform <type>
+// nomos:<attr> = <literal>` attributes, which is all this layer ever contains.
+
+interface Prim {
+  readonly name: string;
+  readonly attrs: Record<string, unknown>;
+  readonly children: Prim[];
+}
+
+// Attributes are written bare when the `NomosEntity` schema declares their type, and with
+// `custom uniform` only where a prim carries something the schema does not describe.
+const ATTR = /^\s*(?:custom\s+)?(?:uniform\s+)?(\S+)\s+nomos:([A-Za-z0-9_]+)\s*=\s*(.+?)\s*$/;
+const REL = /^\s*rel\s+nomos:([A-Za-z0-9_]+)\s*=\s*<([^>]+)>\s*$/;
+// `def Scope "X"`, `def NomosEntity "X"` — a typed prim names its schema between the keyword and the name.
+const OPEN = /^\s*(?:def|over)\s+(?:[A-Za-z_][A-Za-z0-9_]*\s+)?"((?:[^"\\]|\\.)*)"\s*$/;
+
+function parseLiteral(type: string, raw: string): unknown {
+  if (type.endsWith("[]")) {
+    return parseStringList(raw);
+  }
+  if (type === "bool") return raw === "true";
+  if (type === "int" || type === "int64" || type === "double") return Number(raw);
+  return parseQuoted(raw);
+}
+
+function parsePrims(lines: readonly string[], start: number, out: Prim[]): number {
+  let index = start;
+  while (index < lines.length) {
+    const line = lines[index] ?? "";
+    if (/^\s*}\s*$/.test(line)) return index + 1;
+    const open = OPEN.exec(line);
+    if (open === null) { index += 1; continue; }
+    let cursor = index + 1;
+    while (cursor < lines.length && !/^\s*\{\s*$/.test(lines[cursor] ?? "")) cursor += 1;
+    const prim: Prim = { name: parseQuoted(`"${open[1] ?? ""}"`), attrs: {}, children: [] };
+    cursor += 1;
+    // consume this prim's own attributes, then recurse into nested prims
+    while (cursor < lines.length) {
+      const relation = REL.exec(lines[cursor] ?? "");
+      if (relation !== null) {
+        prim.attrs[relation[1] ?? ""] = relation[2] ?? "";
+        cursor += 1;
+        continue;
+      }
+      const attr = ATTR.exec(lines[cursor] ?? "");
+      if (attr !== null) {
+        prim.attrs[attr[2] ?? ""] = parseLiteral(attr[1] ?? "", attr[3] ?? "");
+        cursor += 1;
+        continue;
+      }
+      break;
+    }
+    cursor = parsePrims(lines, cursor, prim.children);
+    out.push(prim);
+    index = cursor;
+  }
+  return index;
+}
+
+function readValue(prim: Prim): PlainValue {
+  const kind = prim.attrs.valueKind as string | undefined;
+  if (kind === "null" || kind === undefined) return null;
+  if (kind === "string" || kind === "bool" || kind === "int" || kind === "double") return prim.attrs.value;
+  if (kind === "array") return prim.children.map(readValue);
+  const record: Record<string, PlainValue> = {};
+  for (const child of prim.children) {
+    const key = child.attrs.key as string | undefined;
+    if (key !== undefined) record[key] = readValue(child);
+  }
+  return record;
+}
+
+function childNamed(prim: Prim | undefined, name: string): Prim | undefined {
+  return prim?.children.find((child) => child.name === name);
+}
+
+// ── identity layer ─────────────────────────────────────────────────────────────────────────────
+
+function emitField(label: string, field: StableFieldId, indent: number): string[] {
+  const p = pad(indent);
+  const inner = pad(indent + 4);
+  return [
+    `${p}def Scope ${quote(`f_${field.sid}`)}`,
+    `${p}{`,
+    `${inner}custom uniform string nomos:label = ${quote(label)}`,
+    `${inner}custom uniform string nomos:sid = ${quote(field.sid)}`,
+    ...(field.was === undefined || field.was.length === 0 ? [] : [`${inner}custom uniform string[] nomos:was = ${stringList(field.was)}`]),
+    ...(field.kind === undefined ? [] : [`${inner}custom uniform string nomos:kind = ${quote(field.kind)}`]),
+    ...(field.contract === undefined ? [] : [`${inner}rel nomos:valueContract = </NomosIdentity/ValueContracts/c_${field.contract}>`]),
+    ...(field.schema === undefined ? [] : [`${inner}custom uniform string nomos:schemaIdentity = ${quote(field.schema)}`]),
+    ...(field.fromBirth === undefined ? [] : [`${inner}custom uniform bool nomos:fromBirth = true`]),
+    ...(field.driver === undefined ? [] : emitValue(field.driver, "Driver", indent + 4)),
+    ...(field.evolutions === undefined || field.evolutions.length === 0
+      ? []
+      : emitValue(field.evolutions, "Evolutions", indent + 4)),
+    `${p}}`,
+  ];
+}
+
+function readField(
+  prim: Prim,
+  contracts: ReadonlyMap<string, unknown>,
+): { label: string; field: StableFieldId } {
+  const driver = childNamed(prim, "Driver");
+  const evolutions = childNamed(prim, "Evolutions");
+  const field: Record<string, unknown> = { sid: prim.attrs.sid };
+  if (Array.isArray(prim.attrs.was) && prim.attrs.was.length > 0) field.was = prim.attrs.was;
+  if (prim.attrs.kind !== undefined) field.kind = prim.attrs.kind;
+  const contractPath = prim.attrs.valueContract as string | undefined;
+  if (contractPath !== undefined) {
+    const contract = contractPath.split("/").at(-1)?.replace(/^c_/u, "");
+    if (!contract) throw new Error(`${NOMOS_IDENTITY_FILENAME} field ${prim.name} has an invalid value-contract relationship`);
+    const shape = contracts.get(contract);
+    if (shape === undefined) throw new Error(`${NOMOS_IDENTITY_FILENAME} field ${prim.name} references missing value contract ${contract}`);
+    field.contract = contract;
+    field.shape = shape;
+  }
+  if (prim.attrs.schemaIdentity !== undefined) field.schema = prim.attrs.schemaIdentity;
+  if (prim.attrs.fromBirth === true) field.fromBirth = true;
+  if (driver !== undefined) field.driver = readValue(driver);
+  if (evolutions !== undefined) field.evolutions = readValue(evolutions);
+  return { label: prim.attrs.label as string, field: field as unknown as StableFieldId };
+}
+
+function emitAggregate(label: string, aggregate: StableAggregateId, indent: number): string[] {
+  const p = pad(indent);
+  const inner = pad(indent + 4);
+  const fields = Object.entries(aggregate.fields).sort(([l], [r]) => (l < r ? -1 : l > r ? 1 : 0));
+  return [
+    `${p}def Scope ${quote(`a_${aggregate.sid}`)}`,
+    `${p}{`,
+    `${inner}custom uniform string nomos:label = ${quote(label)}`,
+    `${inner}custom uniform string nomos:sid = ${quote(aggregate.sid)}`,
+    ...(aggregate.was === undefined || aggregate.was.length === 0 ? [] : [`${inner}custom uniform string[] nomos:was = ${stringList(aggregate.was)}`]),
+    ...(fields.length === 0 ? [] : [
+      `${inner}def Scope "Fields"`,
+      `${inner}{`,
+      ...fields.flatMap(([fieldLabel, field]) => emitField(fieldLabel, field, indent + 8)),
+      `${inner}}`,
+    ]),
+    `${p}}`,
+  ];
+}
+
+// ENCODE WHAT USDA ALREADY ENCODES, ONCE. The entity KEY is `<kind-prefix>_<sid>`, so a prim named
+// by its key carries both kind and sid structurally — restating them as attributes is pure
+// duplication. Parentage is prim NESTING. Types come from the `NomosEntity` schema declared once at
+// the top of the layer, so no attribute needs `custom uniform`. Defaults (`generation = 0`,
+// `status = "active"`) are schema fallbacks and are omitted.
+//
+// An entity whose parent is absent from THIS layer — the ordinary case in a tombstone-only layer,
+// where a retired field's aggregate is usually still alive and therefore not here — cannot nest, so
+// it keeps an explicit `nomos:parent` and sits at the root. Correct either way, compact when it can be.
+function emitEntity(
+  key: string,
+  entity: LawIdentityEntity,
+  children: ReadonlyMap<string, readonly [string, LawIdentityEntity][]>,
+  nested: boolean,
+  indent: number,
+): string[] {
+  const p = pad(indent);
+  const inner = pad(indent + 4);
+  return [
+    `${p}def NomosEntity ${quote(key)}`,
+    `${p}{`,
+    `${inner}string nomos:label = ${quote(entity.label)}`,
+    ...(nested || entity.parent === undefined ? [] : [`${inner}string nomos:parent = ${quote(entity.parent)}`]),
+    ...(entity.priorLabels === undefined || entity.priorLabels.length === 0
+      ? []
+      : [`${inner}string[] nomos:was = ${stringList(entity.priorLabels)}`]),
+    ...(entity.generation === 0 ? [] : [`${inner}int nomos:generation = ${entity.generation}`]),
+    // STATUS IS THE POINT OF THIS LAYER — a retired entity is retained forever so its sid can
+    // never be handed to a later declaration wearing the same label. "active" is the fallback.
+    ...(entity.status === "active" ? [] : [`${inner}token nomos:status = ${quote(entity.status)}`]),
+    ...(children.get(key) ?? []).flatMap(([childKey, child]) =>
+      emitEntity(childKey, child, children, true, indent + 4),
+    ),
+    `${p}}`,
+  ];
+}
+
+/** The schema that lets every entity prim carry bare, typed attributes with fallbacks. */
+const NOMOS_ENTITY_SCHEMA = [
+  'class "NomosEntity"',
+  "{",
+  '    string nomos:label = ""',
+  '    string nomos:parent = ""',
+  "    string[] nomos:was = []",
+  "    int nomos:generation = 0",
+  '    token nomos:status = "active"',
+  "}",
+].join("\n");
+
+function emitEntityForest(entities: Readonly<Record<string, LawIdentityEntity>>, indent: number): string[] {
+  const children = new Map<string, [string, LawIdentityEntity][]>();
+  const sorted = Object.entries(entities).sort(([l], [r]) => (l < r ? -1 : l > r ? 1 : 0));
+  for (const [key, entity] of sorted) {
+    const parent = entity.parent;
+    if (parent === undefined || entities[parent] === undefined) continue;
+    const bucket = children.get(parent) ?? children.set(parent, []).get(parent)!;
+    bucket.push([key, entity]);
+  }
+  return sorted
+    .filter(([, entity]) => entity.parent === undefined || entities[entity.parent] === undefined)
+    .flatMap(([key, entity]) => emitEntity(key, entity, children, false, indent));
+}
+
+function readEntityForest(
+  prims: readonly Prim[],
+  parentKey: string | undefined,
+  out: Record<string, LawIdentityEntity>,
+): void {
+  for (const prim of prims) {
+    const { kind, sid } = lawEntityKeyParts(prim.name);
+    const declaredParent = prim.attrs.parent as string | undefined;
+    const was = prim.attrs.was;
+    out[prim.name] = {
+      kind,
+      sid,
+      label: prim.attrs.label as string,
+      ...(parentKey !== undefined
+        ? { parent: parentKey }
+        : declaredParent === undefined || declaredParent === ""
+          ? {}
+          : { parent: declaredParent }),
+      ...(Array.isArray(was) && was.length > 0 ? { priorLabels: was as string[] } : {}),
+      generation: Number(prim.attrs.generation ?? 0),
+      status: (prim.attrs.status ?? "active") as LawIdentityStatus,
+    };
+    readEntityForest(prim.children, prim.name, out);
+  }
+}
+
+/** Render the committed identity layer. Deterministic: every map is emitted in sorted key order. */
+export function serializeIdentityUsda(lock: CompilerIdentityModel): string {
+  if (lock.identity !== undefined) validateLawIdentityRegistry(lock.identity);
+  const entities = Object.entries(lock.identity?.entities ?? {}).sort(([l], [r]) => (l < r ? -1 : l > r ? 1 : 0));
+  const domains = Object.entries(lock.domains).sort(([l], [r]) => (l < r ? -1 : l > r ? 1 : 0));
+  const contracts = new Map<string, unknown>();
+  const renderedContracts = new Map<string, string>();
+  for (const [, domain] of domains) for (const aggregate of Object.values(domain.stableIds.aggregates)) {
+    for (const field of Object.values(aggregate.fields)) {
+      if (field.contract === undefined || field.shape === undefined) continue;
+      const rendered = emitValue(field.shape, "Shape", 0).join("\n");
+      const prior = renderedContracts.get(field.contract);
+      if (prior !== undefined && prior !== rendered) {
+        throw new Error(`${NOMOS_IDENTITY_FILENAME} value contract ${field.contract} has two different shapes`);
+      }
+      contracts.set(field.contract, field.shape);
+      renderedContracts.set(field.contract, rendered);
+    }
+  }
+
+  return [
+    "#usda 1.0",
+    "(",
+    '    defaultPrim = "NomosIdentity"',
+    "    customLayerData = {",
+    `        string "nomos:format" = ${quote(NOMOS_IDENTITY_LAYER_FORMAT)}`,
+    "    }",
+    ")",
+    "",
+    NOMOS_ENTITY_SCHEMA,
+    "",
+    'def Scope "NomosIdentity"',
+    "{",
+    '    def Scope "Entities"',
+    "    {",
+    ...emitEntityForest(Object.fromEntries(entities), 8),
+    "    }",
+    '    def Scope "ValueContracts"',
+    "    {",
+    ...[...contracts.entries()].sort(([l], [r]) => (l < r ? -1 : l > r ? 1 : 0)).flatMap(([identity, shape]) => [
+      `        def Scope ${quote(`c_${identity}`)}`,
+      "        {",
+      ...emitValue(shape, "Shape", 12),
+      "        }",
+    ]),
+    "    }",
+    '    def Scope "Domains"',
+    "    {",
+    ...domains.flatMap(([name, domain]) => {
+      const aggregates = Object.entries(domain.stableIds.aggregates).sort(([l], [r]) => (l < r ? -1 : l > r ? 1 : 0));
+      return [
+        `        def Scope ${quote(`d_${domain.stableIds.domain}`)}`,
+        "        {",
+        `            custom uniform string nomos:name = ${quote(name)}`,
+        `            custom uniform string nomos:sid = ${quote(domain.stableIds.domain)}`,
+        ...(domain.schemas === undefined ? [] : emitValue(domain.schemas, "Schemas", 12)),
+        ...(aggregates.length === 0 ? [] : [
+          '            def Scope "Aggregates"',
+          "            {",
+          ...aggregates.flatMap(([label, aggregate]) => emitAggregate(label, aggregate, 16)),
+          "            }",
+        ]),
+        "        }",
+      ];
+    }),
+    "    }",
+    "}",
+    "",
+  ].join("\n");
+}
+
+/** Read the committed identity layer back into the compiler's in-memory lock model. */
+export function parseIdentityUsda(text: string): CompilerIdentityModel {
+  if (!text.startsWith("#usda")) {
+    throw new Error(`${NOMOS_IDENTITY_FILENAME} is not a USDA layer`);
+  }
+  if (!text.includes(NOMOS_IDENTITY_LAYER_FORMAT)) {
+    throw new Error(
+      `${NOMOS_IDENTITY_FILENAME} is not ${NOMOS_IDENTITY_LAYER_FORMAT} — refusing to guess an identity encoding`,
+    );
+  }
+  const roots: Prim[] = [];
+  // Skip the layer header before scanning. `customLayerData = { … }` closes with a braced line of
+  // its own, which the prim reader would otherwise treat as the end of the enclosing scope and stop
+  // before reaching the first prim. Root prims sit at column 0, so that is where parsing starts.
+  const lines = text.split(/\r?\n/);
+  const firstPrim = lines.findIndex((line) => /^def\s+Scope\s/.test(line));
+  if (firstPrim === -1) throw new Error(`${NOMOS_IDENTITY_FILENAME} has no NomosIdentity prim`);
+  parsePrims(lines.slice(firstPrim), 0, roots);
+  const root = roots.find((prim) => prim.name === "NomosIdentity");
+  if (root === undefined) throw new Error(`${NOMOS_IDENTITY_FILENAME} has no NomosIdentity prim`);
+
+  const entities: Record<string, LawIdentityEntity> = {};
+  readEntityForest(childNamed(root, "Entities")?.children ?? [], undefined, entities);
+  const identity: LawIdentityRegistry = { v: 1, entities };
+  validateLawIdentityRegistry(identity);
+
+  const contracts = new Map<string, unknown>();
+  for (const prim of childNamed(root, "ValueContracts")?.children ?? []) {
+    const identity = prim.name.replace(/^c_/u, "");
+    const shape = childNamed(prim, "Shape");
+    if (!identity || shape === undefined) throw new Error(`${NOMOS_IDENTITY_FILENAME} has an invalid value-contract prim ${prim.name}`);
+    contracts.set(identity, readValue(shape));
+  }
+
+  const domains: CompilerIdentityModel["domains"] = {};
+  for (const prim of childNamed(root, "Domains")?.children ?? []) {
+    const aggregates: Record<string, StableAggregateId> = {};
+    for (const aggregatePrim of childNamed(prim, "Aggregates")?.children ?? []) {
+      const fields: Record<string, StableFieldId> = {};
+      for (const fieldPrim of childNamed(aggregatePrim, "Fields")?.children ?? []) {
+        const { label, field } = readField(fieldPrim, contracts);
+        fields[label] = field;
+      }
+      const was = aggregatePrim.attrs.was;
+      aggregates[aggregatePrim.attrs.label as string] = {
+        sid: aggregatePrim.attrs.sid as string,
+        ...(Array.isArray(was) && was.length > 0 ? { was: was as string[] } : {}),
+        fields,
+      };
+    }
+    const schemas = childNamed(prim, "Schemas");
+    const stableIds: StableIds = { v: 1, domain: prim.attrs.sid as string, aggregates };
+    domains[prim.attrs.name as string] = {
+      stableIds,
+      ...(schemas === undefined ? {} : { schemas: readValue(schemas) as Record<string, WireSchema> }),
+    };
+  }
+
+  return { v: 1, domains, ...(Object.keys(entities).length === 0 ? {} : { identity }) };
+}
+
+/** An empty identity layer — the first compile of a package that has never been compiled. */
+export function emptyIdentityLock(): CompilerIdentityModel {
+  return { v: 1, domains: {}, identity: emptyLawIdentityRegistry() };
+}

package/src/law_identity.ts

@@ -115,6 +115,21 @@ export function lawEntityKey(kind: LawEntityKind, sid: string): string {
   return `${KIND_PREFIX[kind]}_${sid}`;
 }
 
+/** Invert `lawEntityKey`. A durable encoding can carry identity in the KEY alone — the kind prefix
+ *  and the sid — instead of restating both as attributes beside it. */
+export function lawEntityKeyParts(key: string): { kind: LawEntityKind; sid: string } {
+  const split = key.indexOf("_");
+  const prefix = split === -1 ? "" : key.slice(0, split);
+  const sid = split === -1 ? "" : key.slice(split + 1);
+  const found = (Object.entries(KIND_PREFIX) as [LawEntityKind, string][]).find(
+    ([, candidate]) => candidate === prefix,
+  );
+  if (found === undefined || !SID_PATTERN.test(sid)) {
+    throw new Error(`NMS-ID-004 '${key}' is not a law entity key`);
+  }
+  return { kind: found[0], sid };
+}
+
 /** Identity for a compiler-owned slot whose lifecycle is exactly its stable owner's. */
 export function mintOwnedLawSid(ownerSid: string, slotKind: string, slot: string): string {
   assertSid(ownerSid, "owner");