@githolon/dsl 0.114.0 → 0.116.2

package/src/law_check.ts

@@ -1103,6 +1103,39 @@ function invariantFindings(mod: DomainModule, aggById: ReadonlyMap<string, Aggre
   return out;
 }
 
+// ── VALUE IDENTITY (CAP-853) — `JSON.stringify` COMPARISON WARN ──────────────────────────
+// `JSON.stringify(a) === JSON.stringify(b)` compares TEXT, and json text depends on member insertion
+// order: a value object read back from storage arrives in storage order, so the comparison calls a
+// value unequal to itself (CO2's field-publication invariant refused every round-tripped snapshot).
+// Law compares typed values with `<Vo>.equals(a, b)` (`nomos.vo-canonical.v1`). This is a source-text
+// heuristic over the law bodies Nomos runs (plans, aggregate invariants, workspace invariants), so it
+// WARNS — it cannot prove the operands are structured values.
+const JSON_STRINGIFY_COMPARISON =
+  /JSON\.stringify\s*\((?:[^()]|\((?:[^()]|\([^()]*\))*\))*\)\s*[!=]==?|[!=]==?\s*JSON\.stringify\s*\(/;
+
+function jsonStringifyComparisonFindings(mod: DomainModule): Finding[] {
+  const domain = mod.domain ?? mod.name;
+  const out: Finding[] = [];
+  const judge = (body: unknown, subject: string, directiveId?: string): void => {
+    if (typeof body !== "function") return;
+    if (!JSON_STRINGIFY_COMPARISON.test(Function.prototype.toString.call(body))) return;
+    out.push({
+      domain,
+      ...(directiveId === undefined ? {} : { directiveId }),
+      level: "warn",
+      what: `${subject} compares JSON.stringify(...) text — member order is not part of a value, so a value read back from storage can compare unequal to itself`,
+      fix: "compare typed values with <ValueObject>.equals(a, b) (or valueIdentity(schema).equals for lists/maps of them); for plain json leaves compare the fields you mean",
+    });
+  };
+  for (const dir of mod.directives as Directive<unknown>[]) judge(dir.plan, `directive '${dir.id}' plan`, dir.id);
+  for (const agg of mod.aggregates) judge(agg.invariant, `aggregate '${agg.id}' invariant`);
+  for (const wi of mod.workspaceInvariants ?? []) {
+    judge(wi.assert, `workspace invariant '${wi.id}' assert`, wi.on);
+    judge(wi.reads, `workspace invariant '${wi.id}' reads`, wi.on);
+  }
+  return out;
+}
+
 // ── TWIN 2 (slice 2) — TOP-LEVEL PORT-READ pool-eligibility WARN ───────────────────
 // A tenant MODULE whose TOP LEVEL reads the captured ports (`Date.now()`/`new Date()`/`Math.random()`
 // at module scope, not inside a plan) makes the built engine lump PRISTINE-POOL-INELIGIBLE
@@ -1359,6 +1392,7 @@ export function checkDomainModules(
     findings.push(...nullBanFindings(mod, aggById));
     findings.push(...nullClearAuthorityFindings(mod, aggById));
     findings.push(...attestedReadFindings(mod));
+    findings.push(...jsonStringifyComparisonFindings(mod));
   }
 
   // The BIRTH-RECIPE twin (unify): fold the scattered `.births()` recipe diagnostics into the

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

@@ -1,3 +1,4 @@
+import { usdaString } from "./usda_text.js";
 import type {
   LawAggregateNode,
   LawAnonymousValueFieldNode,
@@ -28,6 +29,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 +422,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 +469,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 +979,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)}>`,
@@ -2062,9 +1947,7 @@ function requiredPath(id: string, paths: ReadonlyMap<string, string>): string {
   return path;
 }
 
-function quote(value: string): string {
-  return JSON.stringify(value);
-}
+const quote = usdaString;
 
 function fail(message: string): never {
   throw new Error(`NMS-USDA-001 ${message}`);

package/src/law_layer_prims.ts

@@ -0,0 +1,174 @@
+// 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.
+import { usdaUnquote } from "./usda_text.js";
+
+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 with OpenUSD's escape rules (and legacy `\uXXXX`). */
+export function unquoteUsda(raw: string): string {
+  return usdaUnquote(raw);
+}
+
+/** 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));
+}