@githolon/dsl 0.113.4 → 0.115.0

package/src/law_graph.ts

@@ -32,6 +32,8 @@ import {
 } from "./relation_schema.js";
 import type { StableFieldEvolution, StableIds } from "./stable_ids_types.js";
 import { isBusinessIntent, publicOfferRoute } from "./intent.js";
+import { listElementPath, mapValuePath, nestedMemberPath, unionVariantPath } from "./wire_paths.js";
+import { anonymousTypeOwnsPrim, internAnonymousValues } from "./anonymous_value_interning.js";
 import {
   lowerLawValueType,
   type LawConstant,
@@ -634,6 +636,8 @@ export interface LawIntentNode {
   readonly requiresHostCapabilities: readonly string[];
   readonly resolves?: LawRef<"field">;
   readonly births: boolean;
+  /** The typed birth key declaration (business births only); see `Directive.birthKey`. */
+  readonly birthKey?: { readonly type: string; readonly brand: string; readonly namespace: string };
   readonly birthRecord?: LawRef<"aggregate">;
   readonly birthPrefix?: string;
   readonly birthDelegations?: LawRef<"field">;
@@ -1269,6 +1273,8 @@ export function discoverLawGraph(
     }
     fail(`intent '${intent.id}' in domain '${module.domain ?? module.name}' targets unknown aggregate '${aggregateId}'`);
   };
+  /** Nested payload paths by intent key → field node id, for phase 2 of nested wire continuity. */
+  const nestedPathsByIntent = new Map<string, Map<string, string>>();
   const intentNodes: LawIntentNode[] = intents.map((intent) => {
     const intentEntity = intentEntities.get(intent.id)!;
     const liveOperationFieldNames = new Set<string>();
@@ -1289,7 +1295,64 @@ export function discoverLawGraph(
         }
         return field;
       });
-      const labels = fields.map((field) => field.name);
+      // NESTED CONTINUITY (CAP-660). A field inside a structural value — a record member, a map
+      // value, a list element, a union variant — used to take its structural sid as its wire key, so
+      // a change anywhere in the enclosing structure moved every sibling's key (the 1 October 2026
+      // `canvasRequirements.isRequired` incident). Nested fields are now ledgered under their path
+      // (wire_paths.ts) in the intent's operation-field scope: the first allocation is still the
+      // structural sid (unchanged law bytes for every existing package), and from then on the
+      // ledger keeps it through named and structural generations.
+      const nestedByPath = new Map<string, LawAnonymousValueFieldNode>();
+      const pathsByNode = new Map<string, string[]>();
+      const walkNested = (valueRef: LawValueTypeRef, path: string, visiting: ReadonlySet<string>): void => {
+        if (visiting.has(valueRef.id)) return;
+        const valueNode = provisionalById.get(valueRef.id as string as LawStructuralSid<"value-type">);
+        if (valueNode?.kind !== "structural" || valueNode.structuralKind !== "value-type") return;
+        const next = new Set(visiting).add(valueRef.id);
+        switch (valueNode.expression.kind) {
+          case "record":
+            for (const memberRef of valueNode.expression.fields) {
+              const member = provisionalById.get(memberRef.id);
+              if (member?.kind !== "structural" || member.structuralKind !== "value-field") continue;
+              const memberPath = nestedMemberPath(path, member.name);
+              if (nestedByPath.has(memberPath)) continue;
+              nestedByPath.set(memberPath, member);
+              pathsByNode.set(member.entity.id, [...(pathsByNode.get(member.entity.id) ?? []), memberPath]);
+              walkNested(member.value, memberPath, next);
+            }
+            break;
+          case "list":
+            walkNested(valueNode.expression.element, listElementPath(path), next);
+            break;
+          case "map":
+            walkNested(valueNode.expression.value, mapValuePath(path), next);
+            break;
+          case "sum":
+            valueNode.expression.variants.forEach((variantRef, index) => {
+              const variant = provisionalById.get(variantRef.id);
+              if (variant?.kind !== "structural" || variant.structuralKind !== "value-variant") return;
+              walkNested(variant.value, unionVariantPath(path, variant.label ?? String(index)), next);
+            });
+            break;
+          case "nullable":
+          case "default":
+          case "recursive":
+            walkNested(valueNode.expression.value, path, next);
+            break;
+          default:
+            break;
+        }
+      };
+      for (const field of fields) walkNested(field.value, field.name, new Set());
+      // Phase 1 of nested continuity: ledger every nested path NOW so it is live for this intent's
+      // retirement pass and so an earlier generation's allocation is found, but allocate no wire yet.
+      // The wire a nested field is served on is the canonical interned member's (law_graph_usda.ts
+      // shares one prim between structurally identical records), which is only known once every
+      // intent, read and contract of the domain is lowered: phase 2, below the intent loop.
+      const intentPaths = nestedPathsByIntent.get(intentEntity.id) ?? new Map<string, string>();
+      for (const [path, node] of nestedByPath) if (!intentPaths.has(path)) intentPaths.set(path, node.entity.id);
+      nestedPathsByIntent.set(intentEntity.id, intentPaths);
+      const labels = [...fields.map((field) => field.name), ...nestedByPath.keys()];
       for (const label of labels) liveOperationFieldNames.add(label);
       const preferredOperationFieldWire = Object.fromEntries(
         fields.map((field) => [
@@ -1636,6 +1699,13 @@ export function discoverLawGraph(
       requiresHostCapabilities: [...new Set(intent.declaredHostCapabilities ?? [])].sort(compareText),
       ...(resolvedField === undefined ? {} : { resolves: ref(resolvedField.entity) }),
       births: intent.birthsChild === true,
+      ...(intent.birthsChild !== true || intent.birthKey === undefined ? {} : {
+        birthKey: {
+          type: intent.birthKey.type,
+          brand: intent.birthKey.brand,
+          namespace: intent.birthKey.namespace,
+        },
+      }),
       ...(intent.birthsChild !== true || aggregateByLabel.get("NomosBirthRecord") === undefined ? {} : {
         birthRecord: ref(aggregateByLabel.get("NomosBirthRecord")!.node.entity),
         birthPrefix: "nomos-birth-record:",
@@ -2554,6 +2624,77 @@ export function discoverLawGraph(
       },
     }),
   };
+  // NESTED WIRE CONTINUITY, PHASE 2 (CAP-660). Every nested payload field is served on the wire key of
+  // the canonical interned member (the prim law_graph_usda.ts emits; the key codegen_call_proto.ts
+  // encodes). Its first allocation is exactly that member's structural sid — the key every existing
+  // package already serves, so law bytes do not move — and from then on the ledger keeps it under
+  // the field's path through named and structural generations. Paths that end up sharing one
+  // canonical member must agree on one allocation: two released keys for one served prim is an
+  // explicit evolution decision, never a compile's silent pick.
+  {
+    const valueNodes = [...anonymousValueNodes.values()];
+    const interning = internAnonymousValues({
+      types: valueNodes.filter((node): node is LawAnonymousValueTypeNode => node.structuralKind === "value-type"),
+      fields: valueNodes.filter((node): node is LawAnonymousValueFieldNode => node.structuralKind === "value-field"),
+      variants: valueNodes.filter((node): node is LawAnonymousValueVariantNode => node.structuralKind === "value-variant"),
+      ownsPrim: anonymousTypeOwnsPrim,
+    });
+    const canonicalFieldOf = (fieldId: string): string => interning.canonicalFieldIdById.get(fieldId) ?? fieldId;
+    const allocationByCanonical = new Map<string, { canonical: string; aliases: Set<string>; owners: string[] }>();
+    for (const [intentKey, paths] of nestedPathsByIntent) {
+      if (paths.size === 0) continue;
+      const intentLabel = registry.entities[intentKey]?.label ?? intentKey;
+      const preferredOperationFieldWire: Record<string, LawOperationFieldWire> = {};
+      for (const [path, fieldId] of paths) {
+        const canonical = anonymousValueNodes.get(canonicalFieldOf(fieldId));
+        if (canonical === undefined) fail(`directive '${intentLabel}': nested field '${path}' has no canonical value node`);
+        preferredOperationFieldWire[path] = { protobuf: { canonical: canonical.entity.sid } };
+      }
+      const ledger = identities.reconcile({
+        kind: "operation-field",
+        parent: intentKey,
+        labels: [...paths.keys()],
+        preferredOperationFieldWire,
+        retireAbsent: false,
+      });
+      registry = ledger.registry;
+      for (const [path, fieldId] of paths) {
+        const entity = registry.entities[ledger.resolved[path] ?? ""];
+        if (entity?.kind !== "operation-field" || entity.status !== "active" || entity.operationFieldWire === undefined) {
+          fail(`directive '${intentLabel}' has no active wire allocation for nested field '${path}'`);
+        }
+        const wire = entity.operationFieldWire.protobuf;
+        const canonicalId = canonicalFieldOf(fieldId);
+        const owner = `${intentLabel}.${path}`;
+        const prior = allocationByCanonical.get(canonicalId);
+        if (prior === undefined) {
+          allocationByCanonical.set(canonicalId, { canonical: wire.canonical, aliases: new Set(wire.aliases ?? []), owners: [owner] });
+          continue;
+        }
+        if (prior.canonical !== wire.canonical) {
+          fail(
+            `NMS-WIRE-001 nested fields ${[...prior.owners, owner].map((name) => `'${name}'`).join(" and ")} share one structural value ` +
+              `but hold different wire allocations (${prior.canonical}, ${wire.canonical}); ` +
+              "declare an evolution plan for the reallocation instead of letting a compile choose",
+          );
+        }
+        for (const alias of wire.aliases ?? []) prior.aliases.add(alias);
+        prior.owners.push(owner);
+      }
+    }
+    // Every node of an allocated equivalence class — the canonical member the law emits and each
+    // duplicate a generated client reads — carries the one allocation.
+    for (const node of valueNodes) {
+      if (node.structuralKind !== "value-field") continue;
+      const allocation = allocationByCanonical.get(canonicalFieldOf(node.entity.id));
+      if (allocation === undefined) continue;
+      const aliases = [...allocation.aliases].sort(compareText);
+      anonymousValueNodes.set(node.entity.id, {
+        ...node,
+        entity: { ...node.entity, wireKey: allocation.canonical, ...(aliases.length === 0 ? {} : { wireAliases: aliases }) },
+      });
+    }
+  }
   const nodes: DeclaredLawNode[] = [
     domainNode,
     ...aggregateNodes,

package/src/law_graph_usda.ts

@@ -28,6 +28,7 @@ import type {
   LawWorkspaceRelationNode,
 } from "./law_graph.js";
 import { MemberAuthenticationKind, type AuthenticationProviderRef } from "./member_authentication.js";
+import { internAnonymousValues } from "./anonymous_value_interning.js";
 
 const FRAMEWORK_SCALAR: Readonly<Record<string, string>> = {
   string: "/Nomos/Framework/Types/t_0000000000000001",
@@ -420,112 +421,18 @@ export function compileSparseLawGraphUsda(
   };
   for (const type of anonymousTypes) resolveAnonymousTypePath(type.entity.id);
 
-  // Anonymous value types are structural values, not independently lived declarations. The graph
-  // deliberately retains their source owner for diagnostics, but USDA must not turn that provenance
-  // into thousands of duplicate runtime prims. Compute a semantic key which excludes owner identity,
-  // then point every equivalent type graph at one canonical prim. Declared types remain untouched.
-  // Recursive graphs keep their owner-scoped identity for now: aliasing a cycle needs an explicit
-  // recursion-isomorphism proof, whereas every acyclic case below is exact by construction.
-  const semanticTypeKeyMemo = new Map<string, string | null>();
-  const semanticTypeKey = (id: string, active = new Set<string>()): string | undefined => {
-    const memoized = semanticTypeKeyMemo.get(id);
-    if (memoized !== undefined) return memoized ?? undefined;
-    if (active.has(id)) {
-      semanticTypeKeyMemo.set(id, null);
-      return undefined;
-    }
-    const node = anonymousTypeById.get(id);
-    if (node === undefined) return undefined;
-    active.add(id);
-    const childKey = (childId: string): string | undefined => semanticTypeKey(childId, active);
-    let key: string | undefined;
-    switch (node.expression.kind) {
-      case "string":
-      case "number":
-      case "integer":
-      case "boolean":
-      case "null":
-      case "unknown":
-      case "enum":
-      case "literal":
-        key = JSON.stringify(node.expression);
-        break;
-      case "list": {
-        const child = childKey(node.expression.element.id);
-        if (child !== undefined) key = JSON.stringify(["list", child]);
-        break;
-      }
-      case "map": {
-        const child = childKey(node.expression.value.id);
-        if (child !== undefined) key = JSON.stringify(["map", child]);
-        break;
-      }
-      case "nullable":
-      case "default": {
-        // Wrappers do not own prims, but their meaning must survive structural
-        // interning. A nullable field is not the same contract as a non-null field.
-        const child = childKey(node.expression.value.id);
-        if (child !== undefined) key = JSON.stringify(node.expression.kind === "nullable"
-          ? ["nullable", child]
-          : ["default", child, node.expression.defaultValue]);
-        break;
-      }
-      case "record": {
-        const members: Array<readonly [string, boolean, string]> = [];
-        for (const field of anonymousFieldsByOwner.get(id) ?? []) {
-          const child = childKey(field.value.id);
-          if (child === undefined) break;
-          members.push([field.name, field.required, child]);
-        }
-        if (members.length === (anonymousFieldsByOwner.get(id)?.length ?? 0)) {
-          members.sort(([left], [right]) => left.localeCompare(right));
-          key = JSON.stringify(["record", members,
-            node.expression.semantic?.kind === "value-object" ? node.expression.semantic.geometry : undefined]);
-        }
-        break;
-      }
-      case "sum": {
-        const members: Array<readonly [string, string]> = [];
-        for (const variant of anonymousVariantsByOwner.get(id) ?? []) {
-          const child = childKey(variant.value.id);
-          if (child === undefined) break;
-          // A union arm's discriminator is part of its wire contract. Two sums
-          // with the same carried value shapes but different arm labels cannot
-          // share one USDA prim: authoring reconstructs the nominal oneof from
-          // these labels before it decodes the generated Protobuf call.
-          members.push([variant.label ?? variant.entity.label, child]);
-        }
-        if (members.length === (anonymousVariantsByOwner.get(id)?.length ?? 0)) {
-          members.sort(([leftLabel, leftChild], [rightLabel, rightChild]) =>
-            leftLabel.localeCompare(rightLabel) || leftChild.localeCompare(rightChild));
-          key = JSON.stringify(["sum", members]);
-        }
-        break;
-      }
-      case "recursive":
-        key = undefined;
-        break;
-    }
-    active.delete(id);
-    semanticTypeKeyMemo.set(id, key ?? null);
-    return key;
-  };
-
-  const canonicalTypeBySemanticKey = new Map<string, LawAnonymousValueTypeNode>();
-  const canonicalTypeIdById = new Map<string, string>();
-  for (const type of [...anonymousTypes].sort((left, right) => left.entity.sid.localeCompare(right.entity.sid))) {
-    const ownPath = pathById.get(type.entity.id);
-    if (ownPath?.endsWith(`/Types/t_${type.entity.sid}`) !== true) continue;
-    const key = semanticTypeKey(type.entity.id);
-    if (key === undefined) continue;
-    const canonical = canonicalTypeBySemanticKey.get(key);
-    if (canonical === undefined) {
-      canonicalTypeBySemanticKey.set(key, type);
-      canonicalTypeIdById.set(type.entity.id, type.entity.id);
-      continue;
-    }
-    canonicalTypeIdById.set(type.entity.id, canonical.entity.id);
-    pathById.set(type.entity.id, requiredPath(canonical.entity.id, pathById));
+  // Anonymous value types are structural values, not independently lived declarations: one semantic
+  // shape, one canonical prim (anonymous_value_interning.ts — the same interning the graph discovery
+  // ledgers nested wire keys against). Declared types remain untouched.
+  const interning = internAnonymousValues({
+    types: anonymousTypes,
+    fields: anonymousFields,
+    variants: anonymousVariants,
+    ownsPrim: (type) => pathById.get(type.entity.id)?.endsWith(`/Types/t_${type.entity.sid}`) === true,
+  });
+  const canonicalTypeIdById = interning.canonicalTypeIdById;
+  for (const [typeId, canonicalId] of canonicalTypeIdById) {
+    if (typeId !== canonicalId) pathById.set(typeId, requiredPath(canonicalId, pathById));
   }
 
   // Wrapper types do not own a USDA prim: their identity is the final path of the carried type.
@@ -561,41 +468,11 @@ export function compileSparseLawGraphUsda(
   // When two record/sum types share one canonical prim, their nested structural references must
   // share the canonical child paths too. This preserves effects which target a nested payload field;
   // no dangling path is allowed merely because its source owner was the non-canonical occurrence.
-  for (const [duplicateId, canonicalId] of canonicalTypeIdById) {
-    if (duplicateId === canonicalId) continue;
-    const canonicalFields = new Map<string, LawAnonymousValueFieldNode>();
-    for (const field of anonymousFieldsByOwner.get(canonicalId) ?? []) {
-      const child = semanticTypeKey(field.value.id);
-      if (child !== undefined) canonicalFields.set(JSON.stringify([field.name, field.required, child]), field);
-    }
-    for (const field of anonymousFieldsByOwner.get(duplicateId) ?? []) {
-      const child = semanticTypeKey(field.value.id);
-      const canonical = child === undefined
-        ? undefined
-        : canonicalFields.get(JSON.stringify([field.name, field.required, child]));
-      if (canonical !== undefined) {
-        pathById.set(field.entity.id, requiredPath(canonical.entity.id, pathById));
-      }
-    }
-
-    const canonicalVariants = new Map<string, LawAnonymousValueVariantNode[]>();
-    for (const variant of anonymousVariantsByOwner.get(canonicalId) ?? []) {
-      const child = semanticTypeKey(variant.value.id);
-      if (child === undefined) continue;
-      const key = JSON.stringify([variant.label ?? variant.entity.label, child]);
-      const matches = canonicalVariants.get(key) ?? [];
-      matches.push(variant);
-      canonicalVariants.set(key, matches);
-    }
-    for (const variant of anonymousVariantsByOwner.get(duplicateId) ?? []) {
-      const child = semanticTypeKey(variant.value.id);
-      if (child === undefined) continue;
-      const key = JSON.stringify([variant.label ?? variant.entity.label, child]);
-      const canonical = canonicalVariants.get(key)?.shift();
-      if (canonical !== undefined) {
-        pathById.set(variant.entity.id, requiredPath(canonical.entity.id, pathById));
-      }
-    }
+  for (const [fieldId, canonicalId] of interning.canonicalFieldIdById) {
+    pathById.set(fieldId, requiredPath(canonicalId, pathById));
+  }
+  for (const [variantId, canonicalId] of interning.canonicalVariantIdById) {
+    pathById.set(variantId, requiredPath(canonicalId, pathById));
   }
   for (const field of fields) {
     const owner = pathById.get(field.owner.id);
@@ -1101,6 +978,13 @@ function emitIntent(
     body.push(`${pad}custom rel nomos:resolves = <${requiredPath(intent.resolves.id, paths)}>`);
   }
   if (intent.births) body.push(`${pad}custom uniform bool nomos:births = true`);
+  if (intent.birthKey !== undefined) {
+    body.push(
+      `${pad}custom uniform token nomos:birthKeyType = ${quote(intent.birthKey.type)}`,
+      `${pad}custom uniform string nomos:birthKeyBrand = ${quote(intent.birthKey.brand)}`,
+      `${pad}custom uniform string nomos:birthKeyNamespace = ${quote(intent.birthKey.namespace)}`,
+    );
+  }
   if (intent.birthRecord !== undefined) {
     body.push(
       `${pad}custom rel nomos:birthRecord = <${requiredPath(intent.birthRecord.id, paths)}>`,

package/src/law_layer_prims.ts

@@ -0,0 +1,199 @@
+// NOMOS — A tolerant structural reader for compiler-authored USDA layers.
+//
+// The compiler writes one opinion per line with every prim's braces on their own lines
+// (law_graph_usda.ts, identity_usda.ts). This reader recovers that prim tree and the raw text of
+// each `nomos:*` opinion without interpreting USD composition. It is NOT a USD parser: an authored
+// stage with arbitrary layout is out of scope, and a layer the compiler did not write is refused by
+// the callers that know what they expect to find.
+//
+// Why a second reader beside identity_usda.ts: that one is exact for the identity layer's typed
+// subset and throws on anything else. Law layers carry relationships, dictionaries and typed
+// literals that layer never contains, so the baseline export needs a reader that keeps going past
+// opinions it does not understand instead of refusing a whole released layer over one of them.
+
+export interface UsdaPrim {
+  /** The prim's name, unquoted. */
+  readonly name: string;
+  /** The schema/type word between `def` and the name, or "" for an untyped `over`. */
+  readonly type: string;
+  /** Absolute prim path, `/A/B/C`. */
+  readonly path: string;
+  /** `nomos:<attr>` opinions by attribute name, raw literal text (quoted strings keep their quotes). */
+  readonly attrs: ReadonlyMap<string, string>;
+  /** `rel nomos:<name>` targets by relationship name (one or several prim paths). */
+  readonly rels: ReadonlyMap<string, readonly string[]>;
+  readonly children: readonly UsdaPrim[];
+}
+
+const PRIM_OPEN = /^\s*(?:def|over|class)\b(?:\s+([A-Za-z_][A-Za-z0-9_]*))?\s+"((?:[^"\\]|\\.)*)"\s*(?:\(\s*)?$/;
+const REL = /^\s*(?:custom\s+)?(?:uniform\s+)?rel\s+nomos:([A-Za-z0-9_]+)\s*=\s*(.+?)\s*$/;
+const ATTR = /^\s*(?:custom\s+)?(?:uniform\s+)?[A-Za-z0-9_]+(?:\[\])?\s+nomos:([A-Za-z0-9_]+)\s*=\s*(.+?)\s*$/;
+
+/** Decode a USDA quoted string literal (the escapes the compiler writes). */
+export function unquoteUsda(raw: string): string {
+  const value = raw.trim();
+  if (!value.startsWith('"') || !value.endsWith('"') || value.length < 2) {
+    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) 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;
+}
+
+/** Decode a one-line USDA string array literal `["a", "b"]`. */
+export function unquoteUsdaList(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(unquoteUsda(body.slice(start, index)));
+      start = index + 1;
+    }
+  }
+  if (quoted) throw new Error("unterminated USDA string array");
+  items.push(unquoteUsda(body.slice(start)));
+  return items;
+}
+
+function relTargets(raw: string): string[] {
+  const value = raw.trim();
+  const body = value.startsWith("[") && value.endsWith("]") ? value.slice(1, -1) : value;
+  return body
+    .split(",")
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0)
+    .map((item) => {
+      if (!item.startsWith("<") || !item.endsWith(">")) throw new Error(`expected a USDA relationship target, got ${item}`);
+      return item.slice(1, -1);
+    });
+}
+
+interface MutablePrim {
+  name: string;
+  type: string;
+  path: string;
+  attrs: Map<string, string>;
+  rels: Map<string, string[]>;
+  children: MutablePrim[];
+}
+
+/** Read every root prim of a compiler-authored layer. The layer header `( … )` and any
+ * dictionary-valued opinion (`… = {` … `}`) are skipped structurally. */
+export function readUsdaPrims(text: string): UsdaPrim[] {
+  const roots: MutablePrim[] = [];
+  const stack: MutablePrim[] = [];
+  const lines = text.split(/\r?\n/);
+  let index = 0;
+  // Skip the layer header: everything before the first prim line.
+  while (index < lines.length && PRIM_OPEN.exec(lines[index]!) === null) index += 1;
+  let pending: MutablePrim | undefined;
+  let dictionaryDepth = 0;
+  for (; index < lines.length; index += 1) {
+    const line = lines[index]!;
+    const trimmed = line.trim();
+    if (dictionaryDepth > 0) {
+      if (trimmed.endsWith("{")) dictionaryDepth += 1;
+      else if (trimmed === "}") dictionaryDepth -= 1;
+      continue;
+    }
+    if (pending !== undefined) {
+      // Between a prim's opening line and its `{`: prim metadata we do not read.
+      if (trimmed === "{") {
+        stack.push(pending);
+        pending = undefined;
+      }
+      continue;
+    }
+    const open = PRIM_OPEN.exec(line);
+    if (open !== null) {
+      const name = unquoteUsda(`"${open[2] ?? ""}"`);
+      const parent = stack[stack.length - 1];
+      const prim: MutablePrim = {
+        name,
+        type: open[1] ?? "",
+        path: `${parent?.path ?? ""}/${name}`,
+        attrs: new Map(),
+        rels: new Map(),
+        children: [],
+      };
+      (parent?.children ?? roots).push(prim);
+      pending = prim;
+      continue;
+    }
+    if (trimmed === "}") {
+      stack.pop();
+      continue;
+    }
+    if (trimmed.endsWith("= {")) {
+      dictionaryDepth = 1;
+      continue;
+    }
+    const current = stack[stack.length - 1];
+    if (current === undefined) continue;
+    const rel = REL.exec(line);
+    if (rel !== null) {
+      current.rels.set(rel[1]!, relTargets(rel[2]!));
+      continue;
+    }
+    const attr = ATTR.exec(line);
+    if (attr !== null) current.attrs.set(attr[1]!, attr[2]!);
+  }
+  return roots;
+}
+
+/** Index every prim of a forest by absolute path. */
+export function indexUsdaPrims(roots: readonly UsdaPrim[]): Map<string, UsdaPrim> {
+  const index = new Map<string, UsdaPrim>();
+  const visit = (prim: UsdaPrim): void => {
+    index.set(prim.path, prim);
+    for (const child of prim.children) visit(child);
+  };
+  for (const root of roots) visit(root);
+  return index;
+}
+
+/** A `nomos:<attr>` string opinion, decoded, or undefined when the prim carries none. */
+export function usdaString(prim: UsdaPrim, attr: string): string | undefined {
+  const raw = prim.attrs.get(attr);
+  return raw === undefined ? undefined : unquoteUsda(raw);
+}
+
+/** A `nomos:<attr>` string-array opinion, decoded, or undefined when the prim carries none. */
+export function usdaStringList(prim: UsdaPrim, attr: string): string[] | undefined {
+  const raw = prim.attrs.get(attr);
+  return raw === undefined ? undefined : unquoteUsdaList(raw);
+}
+
+export function usdaChild(prim: UsdaPrim | undefined, name: string): UsdaPrim | undefined {
+  return prim?.children.find((child) => child.name === name);
+}

package/src/law_unit_selection.ts

@@ -0,0 +1,45 @@
+// PER-KIND LAW (CAP-809, architecture/frontier_law_storage.md slice 6).
+//
+// A workspace kind installs only the domains it serves. Its law is a unit set holding the framework unit, the
+// composition unit and the domain units of exactly those domains; the kernel admits such a set and its composed stage
+// exports only the domains it holds. The subset is a version of the same law identity (the package name), so
+// installing it over the complete set (or the reverse) replaces that version at the frontier like any other.
+
+import { COMPOSITION_UNIT, FRAMEWORK_UNIT, domainUnitKey, type LawUnit } from "./law_units.js";
+
+/** A domain's key in a package (`nomos:domains`). Typed: a bare string never selects law. */
+export type LawDomainKey = string & { readonly __nomosLawDomainKey: unique symbol };
+
+export function lawDomainKey(name: string): LawDomainKey {
+  if (name.length === 0 || name.trim() !== name || name.includes("\0")) {
+    throw new TypeError(`${JSON.stringify(name)} is not a domain key`);
+  }
+  return name as LawDomainKey;
+}
+
+/**
+ * The units a workspace kind installs: framework, composition, and the domain unit of each domain it serves.
+ * Refuses an empty selection, a repeated domain and a domain the compiled package does not hold — a selection
+ * names law exactly, it never silently drops a domain.
+ */
+export function unitsForDomains(units: readonly LawUnit[], domains: readonly LawDomainKey[]): LawUnit[] {
+  if (domains.length === 0) throw new Error("a workspace kind must serve at least one domain");
+  const wanted = new Set<string>();
+  for (const domain of domains) {
+    if (wanted.has(domain)) throw new Error(`domain ${domain} is selected twice`);
+    wanted.add(domain);
+  }
+  const byKey = new Map(units.map((unit) => [unit.key, unit] as const));
+  const selected: LawUnit[] = [];
+  for (const key of [FRAMEWORK_UNIT, COMPOSITION_UNIT]) {
+    const unit = byKey.get(key);
+    if (unit === undefined) throw new Error(`the compiled units have no ${key} unit`);
+    selected.push(unit);
+  }
+  for (const domain of wanted) {
+    const unit = byKey.get(domainUnitKey(domain));
+    if (unit === undefined) throw new Error(`the compiled units hold no domain ${domain}`);
+    selected.push(unit);
+  }
+  return selected.sort((left, right) => (left.key < right.key ? -1 : left.key > right.key ? 1 : 0));
+}

package/src/law_unit_set_identity.ts

@@ -0,0 +1,44 @@
+// THE LAW IDENTITY (CAP-773, architecture/law_units_format.md "Identities").
+//
+// A law is a set of content-addressed units (framework, composition, one per domain). Its identity is the unit set
+// identity: sha256("nomos-law-unit-set-identity-v1\0" { key "\0" unitHash "\0" }*), units sorted by key in byte
+// order. It names exactly which units the set holds and nothing about how a kernel composes them, so publishers,
+// generated clients, the console and qualification all name law by it, and every kernel agrees on it whatever its
+// composer version. The kernel's definition is `law_unit_set_identity` (kernel/src/law_units.rs); the two are bound
+// by one vector (law_unit_set_identity.test.ts, law_units.rs tests) and by a compiled fixture the real kernel composes
+// (kernel/tests/compiled_law_units.rs).
+//
+// Not the law identity: the realised closure a target's kernel composes from the set (it also depends on the
+// kernel's OpenUSD pin and composer version), the compiler's package closure (`build/<name>.law.sha256`), and the
+// kernel's composition identity (the set record's `setIdentity`, which binds the set to one composer).
+//
+// Dependency-free and synchronous over the bytes: each runtime hashes the preimage with its own sha256 (node:crypto
+// in the compiler, WebCrypto in the console and CLI, the Peer Office's own digest on a device).
+
+export const LAW_UNIT_SET_IDENTITY_TAG = "nomos-law-unit-set-identity-v1";
+
+export interface LawUnitSetMember {
+  readonly key: string;
+  readonly unitHash: string;
+}
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const byteOrder = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+/** The exact bytes the unit set identity hashes. Refuses a duplicate key or a unit hash that is not a sha256. */
+export function lawUnitSetIdentityPreimage(units: readonly LawUnitSetMember[]): Uint8Array {
+  const sorted = [...units].sort((left, right) => byteOrder(left.key, right.key));
+  const parts = [`${LAW_UNIT_SET_IDENTITY_TAG}\0`];
+  sorted.forEach((unit, index) => {
+    if (unit.key.length === 0 || unit.key.includes("\0")) throw new Error(`law unit key ${JSON.stringify(unit.key)} is not a unit key`);
+    if (index > 0 && sorted[index - 1]!.key === unit.key) throw new Error(`law unit ${unit.key} appears twice in one set`);
+    if (!HEX64.test(unit.unitHash)) throw new Error(`law unit ${unit.key} names ${JSON.stringify(unit.unitHash)}, not a unit hash`);
+    parts.push(unit.key, "\0", unit.unitHash, "\0");
+  });
+  return new TextEncoder().encode(parts.join(""));
+}
+
+/** The unit set identity, hashed with the caller's synchronous sha256 (lowercase hex out). */
+export function lawUnitSetIdentityWith(sha256Hex: (bytes: Uint8Array) => string, units: readonly LawUnitSetMember[]): string {
+  return sha256Hex(lawUnitSetIdentityPreimage(units));
+}