@githolon/dsl 0.101.5 → 0.102.0

package/src/usd_layers.ts

@@ -19,13 +19,14 @@
  *     (and a real `.usda` text layer standard USD tooling opens), instead of
  *     lowering only the composed result.
  *   * `flattenLayeredUsd` is the ordered opinion-map fold over those layers —
- *     and the proof obligation is BYTE-EQUALITY:
+ *     and the proof obligation is CANONICAL LAW EQUALITY:
  *
- *       JSON.stringify(flattenLayeredUsd(layers)) === emitUsdJsonForModules([composed])
+ *       canonicalJson(flattenLayeredUsd(layers)) === canonicalJson(emitUsd([composed]))
  *
  *     i.e. Φ(fold_modules(A, B)) == fold_layers(Φ(A), Φ(B)) — flatten-after-lower
- *     equals lower-after-compose, byte for byte. `nomos-compile --layered`
- *     ASSERTS this fail-closed on every layered compile (never assumed).
+ *     equals lower-after-compose. `nomos-compile` ASSERTS this fail-closed on every
+ *     compile (never assumed); release builds can additionally require stock OpenUSD's
+ *     `usdcat --flatten` to resolve the same canonical law.
  *
  * WHERE THE TWO FOLDS COULD DIVERGE (the lemma, stated honestly): USD composes
  * PER-ATTRIBUTE (a weaker layer's attribute shows through a stronger prim that is
@@ -36,7 +37,7 @@
  * for a directive's required attributes (target/marker/requires/payload). The gap
  * is omit-when-empty boundaries (`reads`/`emits`) on a RE-declared directive:
  * "omitted" means "none" to the module fold but "no opinion" (show-through) to
- * USD. The compile-time byte-equality assertion fail-closes that case rather than
+ * USD. The compile-time canonical-equality assertion fail-closes that case rather than
  * silently shipping either answer.
  *
  * STATE vs LAW (why this is sound): law composition is this non-commutative
@@ -44,8 +45,8 @@
  * commutative semilattice world (Lww/AddWins/MapOf merge drivers — order-free by
  * construction). The domainHash is deliberately NON-homomorphic: it is sha256 over
  * the COMPOSED canonical bytes, so identity lives on the flattened law, never on
- * any decomposition of it. Layered emission is therefore OPT-IN and additive: the
- * flattened `.package.usda` emission and its hash do not move by one byte.
+ * any decomposition of it. Every package therefore emits its authored layer stack;
+ * the executable `.package.usda` envelope carries that resolved law and its hash.
  *
  * LIVRPS note: the module list maps onto the SUBLAYER arc only (local opinions per
  * layer, stronger-over-weaker). The reference/variant arcs of `usd.ts` are the
@@ -54,10 +55,11 @@
  * re-authoring its own module stack is opinion strength; a foreign layer composing
  * over deployed law is a monotonic move.
  *
- * BUILD-TIME ONLY (Buffer for hex): reached via `@githolon/dsl/usd-layers`, never
+ * BUILD-TIME ONLY (Buffer for lossless UTF-8 identifier tokens): reached via `@githolon/dsl/usd-layers`, never
  * the runtime barrel.
  */
 import type { AggregateHandle } from "./aggregate.js";
+import { createHash } from "node:crypto";
 import { READ_PROJECTION_DELIMITER } from "./read_projection_namespace.js";
 import type { Field } from "./fields.js";
 import type { DomainModule } from "./codegen_dart.js";
@@ -78,21 +80,14 @@ import { withBusinessCorrectionLayer } from "./framework/business_corrections.js
 export const NOMOS_USD_LAYER_FORMAT = "nomos.usd-layer.v1";
 /** The layered-root format marker — the subLayers document. */
 export const NOMOS_USD_LAYERED_PACKAGE_FORMAT = "nomos.usd-layered-package.v1";
+/** The self-contained ledger/runtime stage: native law plus indexed executable plan assets. */
+export const NOMOS_USD_PLAN_PACKAGE_FORMAT = "nomos.openusd-plan-package.v2";
 
 // ── small codecs ───────────────────────────────────────────────────────────────────
 
-/** Lowercase hex of the UTF-8 bytes (same convention as the package envelope). */
-function hexUtf8(text: string): string {
-  return Buffer.from(text, "utf8").toString("hex");
-}
-
-function unhexUtf8(hex: string): string {
-  return Buffer.from(hex, "hex").toString("utf8");
-}
-
 /** Escape a string for a double-quoted usda string literal. */
 export function usdaString(s: string): string {
-  return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  return JSON.stringify(s);
 }
 
 /** A usda `string[]` literal. */
@@ -149,6 +144,79 @@ export function primName(id: string): string {
   return /^[A-Za-z_]/.test(sanitized) ? sanitized : `_${sanitized}`;
 }
 
+/** Lossless USD identifier for an arbitrary business field label. */
+export function fieldToken(field: string): string {
+  return `f${Buffer.from(field, "utf8").toString("hex")}`;
+}
+
+/** Inverse of {@link fieldToken}. */
+export function parseFieldToken(token: string): string {
+  if (!/^f(?:[0-9a-f]{2})+$/.test(token)) throw new Error(`usd-layers: malformed field token '${token}'`);
+  return Buffer.from(token.slice(1), "hex").toString("utf8");
+}
+
+/** Canonical JSON text used only to content-stamp a native USD value tree. */
+function stableValueJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableValueJson).join(",")}]`;
+  return `{${Object.keys(value as Record<string, unknown>).sort().map((key) =>
+    `${JSON.stringify(key)}:${stableValueJson((value as Record<string, unknown>)[key])}`).join(",")}}`;
+}
+
+/**
+ * Encode an arbitrary law value as an ordinary USD prim tree. No JSON text is carried. Every node
+ * bears the root content stamp so a stronger layer replaces the whole value: weaker descendants
+ * may show through structurally under USD composition, but the reader ignores their old stamp.
+ */
+export function nativeValueLines(name: string, value: unknown, indent: string): string[] {
+  const hash = createHash("sha256").update(stableValueJson(value)).digest("hex");
+  const keyHex = (key: string): string => Buffer.from(key, "utf8").toString("hex");
+  const scalarLine = (nodeValue: unknown, attr: string, at: string): string => {
+    if (nodeValue === null) return `${at}custom bool nomos:zv:${attr} = true`;
+    if (typeof nodeValue === "string") return `${at}custom string nomos:sv:${attr} = ${usdaString(nodeValue)}`;
+    if (typeof nodeValue === "boolean") return `${at}custom bool nomos:bv:${attr} = ${nodeValue ? "true" : "false"}`;
+    if (typeof nodeValue === "number" && Number.isFinite(nodeValue)) {
+      const usdType = Number.isSafeInteger(nodeValue) && !Object.is(nodeValue, -0) ? "int64" : "double";
+      return `${at}custom ${usdType} nomos:nv:${attr} = ${Object.is(nodeValue, -0) ? "-0" : String(nodeValue)}`;
+    }
+    throw new Error(`usd-layers: '${name}' contains a non-JSON value (${typeof nodeValue})`);
+  };
+  const emitContainer = (nodeName: string, nodeValue: unknown, at: string): string[] => {
+    const isArray = Array.isArray(nodeValue);
+    const isObject = nodeValue !== null && typeof nodeValue === "object" && !isArray;
+    const lines = [
+      `${at}def Scope ${usdaString(nodeName)}`,
+      `${at}{`,
+      `${at}    custom string nomos:containerKind = ${usdaString(isArray ? "array" : isObject ? "object" : "scalar")}`,
+    ];
+    const entries: readonly [string | undefined, unknown][] = isArray
+      ? nodeValue.map((child) => [undefined, child] as const)
+      : isObject
+        // The content hash canonicalizes object keys. The physical tree MUST use the same order:
+        // two layers carrying the same object with different JS insertion order otherwise share a
+        // root hash but compose incompatible positional children under that root.
+        ? Object.entries(nodeValue as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b))
+        : [[undefined, nodeValue]];
+    entries.forEach(([key, child], index) => {
+      const position = `i${String(index).padStart(6, "0")}`;
+      const identity = key === undefined ? position : `${position}:k${keyHex(key)}`;
+      if (child !== null && typeof child === "object") {
+        lines.push("", ...emitContainer(identity.replace(/:/g, "_"), child, `${at}    `));
+      } else {
+        lines.push(scalarLine(child, identity, `${at}    `));
+      }
+    });
+    lines.push(`${at}}`);
+    return lines;
+  };
+  const rootName = `__nms_${primName(name)}_${hash}`;
+  return [
+    `${indent}custom string nomos:value:${name} = ${usdaString(hash)}`,
+    "",
+    ...emitContainer(rootName, value, indent),
+  ];
+}
+
 /** Field→driver map with keys sorted (the canonical schema shape `manifest.ts` emits). */
 function sortedSchema(schema: WireSchema): WireSchema {
   const out: WireSchema = {};
@@ -157,82 +225,26 @@ function sortedSchema(schema: WireSchema): WireSchema {
 }
 
 function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string): string[] {
-  return [
+  const attrs = [
     `${indent}custom string nomos:kind = "domain"`,
     `${indent}custom string nomos:domain = ${usdaString(domain)}`,
-    ...(layer.nomosIdentityManifest !== undefined
-      ? [`${indent}custom string nomos:identityManifestHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosIdentityManifest)))}`]
-      : []),
-    ...(layer.nomosReadProjection !== undefined
-      ? [`${indent}custom string nomos:readProjectionHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosReadProjection)))}`]
-      : []),
-    ...(layer.nomosStableIds !== undefined
-      ? [`${indent}custom string nomos:stableIdsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosStableIds)))}`]
-      : []),
-    ...(layer.nomosInterface !== undefined
-      ? [`${indent}custom string nomos:interfaceHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosInterface)))}`]
-      : []),
-    ...(layer.nomosReadGate !== undefined
-      ? [`${indent}custom string nomos:readGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosReadGate)))}`]
-      : []),
-    ...(layer.nomosReadVisibility !== undefined
-      ? [`${indent}custom string nomos:readVisibilityHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosReadVisibility)))}`]
-      : []),
-    ...(layer.nomosEncryption !== undefined
-      ? [`${indent}custom string nomos:encryptionHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosEncryption)))}`]
-      : []),
-    ...(layer.nomosAttributedGate !== undefined
-      ? [`${indent}custom string nomos:attributedGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosAttributedGate)))}`]
-      : []),
-    ...(layer.nomosRelations !== undefined
-      ? [`${indent}custom string nomos:relationsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosRelations)))}`]
-      : []),
-    ...(layer.nomosRelationNamespace !== undefined
-      ? [`${indent}custom string nomos:relationNamespaceHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosRelationNamespace)))}`]
-      : []),
-    ...(layer.nomosReadProjectionNamespace !== undefined
-      ? [`${indent}custom string nomos:readProjectionNamespaceHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosReadProjectionNamespace)))}`]
-      : []),
-    ...(layer.nomosRelationGate !== undefined
-      ? [`${indent}custom string nomos:relationGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosRelationGate)))}`]
-      : []),
-    ...(layer.nomosAttestationGate !== undefined
-      ? [`${indent}custom string nomos:attestationGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosAttestationGate)))}`]
-      : []),
-    ...(layer.nomosDelegationGate !== undefined
-      ? [`${indent}custom string nomos:delegationGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosDelegationGate)))}`]
-      : []),
-    ...(layer.nomosAttestedReadGate !== undefined
-      ? [`${indent}custom string nomos:attestedReadGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosAttestedReadGate)))}`]
-      : []),
-    ...(layer.nomosBirthGate !== undefined
-      ? [`${indent}custom string nomos:birthGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosBirthGate)))}`]
-      : []),
-    ...(layer.nomosBirthRecordGate !== undefined
-      ? [`${indent}custom string nomos:birthRecordGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosBirthRecordGate)))}`]
-      : []),
-    ...(layer.nomosParentAttestedBirth !== undefined
-      ? [`${indent}custom string nomos:parentAttestedBirthHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosParentAttestedBirth)))}`]
-      : []),
-    ...(layer.nomosVerifiedFirstEnroll !== undefined
-      ? [`${indent}custom string nomos:verifiedFirstEnrollHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosVerifiedFirstEnroll)))}`]
-      : []),
-    ...(layer.nomosEraCertGate !== undefined
-      ? [`${indent}custom string nomos:eraCertGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosEraCertGate)))}`]
-      : []),
-    ...(layer.nomosValueObjects !== undefined
-      ? [`${indent}custom string nomos:valueObjectsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosValueObjects)))}`]
-      : []),
-    ...(layer.nomosContracts !== undefined
-      ? [`${indent}custom string nomos:contractsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosContracts)))}`]
-      : []),
-    ...(layer.nomosForeignRefs !== undefined
-      ? [`${indent}custom string nomos:foreignRefsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosForeignRefs)))}`]
-      : []),
-    ...(layer.nomosFlowGate !== undefined
-      ? [`${indent}custom string nomos:flowGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosFlowGate)))}`]
-      : []),
   ];
+  const values: readonly [string, unknown][] = [
+    ["identityManifest", layer.nomosIdentityManifest], ["readProjection", layer.nomosReadProjection],
+    ["stableIds", layer.nomosStableIds], ["interface", layer.nomosInterface], ["readGate", layer.nomosReadGate],
+    ["invariantGate", layer.nomosInvariantGate], ["readVisibility", layer.nomosReadVisibility],
+    ["encryption", layer.nomosEncryption], ["capabilities", layer.nomosCapabilities],
+    ["attributedGate", layer.nomosAttributedGate], ["relations", layer.nomosRelations],
+    ["relationNamespace", layer.nomosRelationNamespace], ["readProjectionNamespace", layer.nomosReadProjectionNamespace],
+    ["relationGate", layer.nomosRelationGate], ["attestationGate", layer.nomosAttestationGate],
+    ["delegationGate", layer.nomosDelegationGate], ["attestedReadGate", layer.nomosAttestedReadGate],
+    ["birthGate", layer.nomosBirthGate], ["birthRecordGate", layer.nomosBirthRecordGate],
+    ["parentAttestedBirth", layer.nomosParentAttestedBirth], ["verifiedFirstEnroll", layer.nomosVerifiedFirstEnroll],
+    ["eraCertGate", layer.nomosEraCertGate], ["valueObjects", layer.nomosValueObjects],
+    ["contracts", layer.nomosContracts], ["foreignRefs", layer.nomosForeignRefs], ["flowGate", layer.nomosFlowGate],
+  ];
+  for (const [name, value] of values) if (value !== undefined) attrs.push("", ...nativeValueLines(name, value, indent));
+  return attrs;
 }
 
 // ── per-module layer emission ────────────────────────────────────────────────────────
@@ -265,11 +277,18 @@ export interface EmittedModuleLayer {
 export function emitLayeredDomain(
   domain: string,
   modules: readonly LayeredModuleInput[],
+  options: { readonly applyBusinessCorrectionLayer?: boolean } = {},
 ): EmittedModuleLayer[] {
   if (modules.length === 0) {
     throw new Error(`usd-layers: domain '${domain}' has no modules to layer`);
   }
-  const normalizedModules = withBusinessCorrectionLayer(modules.map((entry) => entry.module));
+  // Raw callers need the cross-module correction prelude. The package compiler,
+  // however, passes modules already lowered through composeDomainModule; re-inferring
+  // the prelude here would turn framework-expanded capability directives into public
+  // business verbs and invent law that the canonical fold never declared.
+  const normalizedModules = options.applyBusinessCorrectionLayer === false
+    ? modules.map((entry) => entry.module)
+    : withBusinessCorrectionLayer(modules.map((entry) => entry.module));
   const out: EmittedModuleLayer[] = [];
   const seenPaths = new Set<string>();
   for (const [index, m] of modules.entries()) {
@@ -328,8 +347,8 @@ function relationLines(
  * One module layer as REAL `.usda` text: `/Nomos/<domain>` scopes, one prim per
  * aggregate (field→merge-driver as readable `nomos:driver:<field>` attributes,
  * `t.ref`/`t.hasMany` as USD relationships), one prim per directive, one prim per
- * declared query/derived/combined. Nested JSON (payload schema / emits / returns)
- * rides hex-encoded so the round-trip is byte-faithful. Re-touched prim paths use
+ * declared query/derived/combined. Structured values are ordinary stamped USD prim trees,
+ * so the round-trip is byte-faithful without a hidden JSON authority. Re-touched prim paths use
  * the `over` specifier; everything carries `nomos:id` so the sanitized prim name
  * never loses the wire id.
  */
@@ -337,12 +356,12 @@ export function usdaLayerText(
   domain: string,
   moduleName: string,
   layer: UsdLayer,
-  module: DomainModule,
+  module: DomainModule | undefined,
   overPaths: ReadonlySet<string>,
 ): string {
   const domainScope = `/Nomos/${primName(domain)}`;
   const aggById = new Map<string, AggregateHandle>();
-  for (const a of module.aggregates as AggregateHandle[]) aggById.set(a.id, a);
+  for (const a of (module?.aggregates ?? []) as AggregateHandle[]) aggById.set(a.id, a);
 
   const ind2 = "        ";
   const ind3 = "            ";
@@ -358,7 +377,7 @@ export function usdaLayerText(
         `${ind3}custom string nomos:id = ${usdaString(prim.type)}`,
       );
       for (const [field, driver] of Object.entries(prim.schema)) {
-        body.push(`${ind3}custom string nomos:driver:${field} = ${usdaString(driverToken(driver))}`);
+        body.push(`${ind3}custom string nomos:driver:${fieldToken(field)} = ${usdaString(driverToken(driver))}`);
       }
       body.push(...relationLines(domainScope, aggById.get(prim.type), ind3));
     } else {
@@ -373,21 +392,13 @@ export function usdaLayerText(
         body.push(`${ind3}custom string[] nomos:reads = ${usdaStringArray(prim.reads)}`);
       }
       if (prim.emits !== undefined) {
-        body.push(
-          `${ind3}custom string nomos:emitsHex = ${usdaString(hexUtf8(JSON.stringify(prim.emits)))}`,
-        );
+        body.push("", ...nativeValueLines("emits", prim.emits, ind3));
       }
       if (prim.secondaryOutputs !== undefined) {
-        body.push(
-          `${ind3}custom string nomos:secondaryOutputsHex = ${usdaString(hexUtf8(JSON.stringify(prim.secondaryOutputs)))}`,
-        );
+        body.push("", ...nativeValueLines("secondaryOutputs", prim.secondaryOutputs, ind3));
       }
       if (prim.payloadJsonSchema !== undefined) {
-        body.push(
-          `${ind3}custom string nomos:payloadJsonSchemaHex = ${usdaString(
-            hexUtf8(JSON.stringify(prim.payloadJsonSchema)),
-          )}`,
-        );
+        body.push("", ...nativeValueLines("payloadJsonSchema", prim.payloadJsonSchema, ind3));
       }
     }
     body.push(`${ind2}}`, ``);
@@ -412,7 +423,8 @@ export function usdaLayerText(
       `${ind3}custom string nomos:kind = "derived"`,
       `${ind3}custom string nomos:id = ${usdaString(d.id)}`,
       `${ind3}custom string nomos:of = ${usdaString(d.of)}`,
-      `${ind3}custom string nomos:returnsHex = ${usdaString(hexUtf8(JSON.stringify(d.returns)))}`,
+      ``,
+      ...nativeValueLines("returns", d.returns, ind3),
       `${ind2}}`,
       ``,
     );
@@ -426,7 +438,8 @@ export function usdaLayerText(
       `${ind3}custom string nomos:of = ${usdaString(c.of)}`,
       `${ind3}custom string nomos:refField = ${usdaString(c.refField)}`,
       `${ind3}custom string nomos:readsFrom = ${usdaString(c.reads)}`,
-      `${ind3}custom string nomos:returnsHex = ${usdaString(hexUtf8(JSON.stringify(c.returns)))}`,
+      ``,
+      ...nativeValueLines("returns", c.returns, ind3),
       `${ind2}}`,
       ``,
     );
@@ -448,8 +461,7 @@ export function usdaLayerText(
     `{`,
     `    def Scope ${usdaString(primName(domain))}`,
     `    {`,
-    // Stable ids + holon-owned manifests: layer-level law keys, hex-carried
-    // so the .usda round-trips byte-faithfully to the IR layer.
+    // Stable ids + holon-owned manifests: native layer-level law values.
     ...domainLayerAttrLines(domain, layer, "        "),
     ``,
     ...body,
@@ -510,6 +522,119 @@ export function layeredRootUsda(
   ].join("\n");
 }
 
+export interface UsdPlanAsset {
+  readonly sha256: string;
+  readonly javascript: string;
+}
+
+export interface UsdPlanRoute {
+  readonly selector: string;
+  readonly planSha256: string;
+}
+
+/**
+ * Emit the one self-contained stage stored on the ledger. Law remains ordinary USD prims and
+ * attributes; executable implementation details are separate, content-addressed plan assets.
+ * The route index is data, not another config format, and therefore composes/travels with the law.
+ */
+export function nativePlanPackageUsda(
+  packageName: string,
+  document: UsdDocument,
+  modules: readonly DomainModule[],
+  plans: readonly UsdPlanAsset[],
+  routes: readonly UsdPlanRoute[],
+): string {
+  const modulesByDomain = new Map(modules.map((module) => [module.domain ?? module.name, module] as const));
+  const planByHash = new Map<string, UsdPlanAsset>();
+  for (const plan of plans) {
+    const actual = createHash("sha256").update(plan.javascript, "utf8").digest("hex");
+    if (actual !== plan.sha256) {
+      throw new Error(`usd-layers: plan '${plan.sha256}' content hashes to '${actual}'`);
+    }
+    planByHash.set(plan.sha256, plan);
+  }
+  for (const route of routes) {
+    if (!planByHash.has(route.planSha256)) {
+      throw new Error(`usd-layers: route '${route.selector}' names missing plan '${route.planSha256}'`);
+    }
+  }
+
+  const domainBlocks: string[] = [];
+  for (const layer of document.layers) {
+    const domain = layer.path.slice(layer.path.lastIndexOf("/") + 1);
+    const module = modulesByDomain.get(domain);
+    const lines = usdaLayerText(domain, "composed", layer, module, new Set()).split("\n");
+    const marker = `    def Scope ${usdaString(primName(domain))}`;
+    const start = lines.indexOf(marker);
+    if (start < 0) throw new Error(`usd-layers: could not extract native domain '${domain}'`);
+    let balance = 0;
+    let opened = false;
+    let end = -1;
+    for (let index = start; index < lines.length; index += 1) {
+      const line = lines[index]!;
+      for (const char of line) {
+        if (char === "{") { balance += 1; opened = true; }
+        if (char === "}") balance -= 1;
+      }
+      if (opened && balance === 0) { end = index; break; }
+    }
+    if (end < 0) throw new Error(`usd-layers: native domain '${domain}' has unbalanced scopes`);
+    domainBlocks.push(...lines.slice(start, end + 1), "");
+  }
+  if (domainBlocks[domainBlocks.length - 1] === "") domainBlocks.pop();
+
+  const sortedPlans = [...planByHash.values()].sort((a, b) => a.sha256.localeCompare(b.sha256));
+  const sortedRoutes = [...routes].sort((a, b) => a.selector.localeCompare(b.selector));
+  const runtime: string[] = [
+    `def Scope "__NomosRuntime_7e9c"`,
+    `{`,
+    `    custom string nomos:kind = "runtime"`,
+    `    custom string nomos:format = ${usdaString(NOMOS_USD_PLAN_PACKAGE_FORMAT)}`,
+    `    custom string nomos:package = ${usdaString(packageName)}`,
+    ``,
+    `    def Scope "Routes"`,
+    `    {`,
+  ];
+  sortedRoutes.forEach((route, index) => runtime.push(
+    `        def Scope "r${String(index).padStart(6, "0")}"`,
+    `        {`,
+    `            custom string nomos:selector = ${usdaString(route.selector)}`,
+    `            custom string nomos:plan = ${usdaString(route.planSha256)}`,
+    `        }`,
+    ``,
+  ));
+  if (runtime[runtime.length - 1] === "") runtime.pop();
+  runtime.push(`    }`, ``, `    def Scope "Plans"`, `    {`);
+  sortedPlans.forEach((plan) => runtime.push(
+    `        def Scope ${usdaString(`p_${plan.sha256}`)}`,
+    `        {`,
+    `            custom string nomos:sha256 = ${usdaString(plan.sha256)}`,
+    `            custom string nomos:language = "javascript"`,
+    `            custom string nomos:source = ${usdaString(plan.javascript)}`,
+    `        }`,
+    ``,
+  ));
+  if (runtime[runtime.length - 1] === "") runtime.pop();
+  runtime.push(`    }`, `}`);
+
+  return [
+    `#usda 1.0`,
+    `(`,
+    `    customLayerData = {`,
+    `        string "nomos:format" = ${usdaString(NOMOS_USD_PLAN_PACKAGE_FORMAT)}`,
+    `    }`,
+    `)`,
+    ``,
+    `def Scope "Nomos"`,
+    `{`,
+    ...domainBlocks,
+    `}`,
+    ``,
+    ...runtime,
+    ``,
+  ].join("\n");
+}
+
 // ── the ordered opinion-map fold (flatten) ───────────────────────────────────────────
 
 /** Strongest-opinion-per-attribute merge of two prims at one path (over = stronger). */
@@ -609,9 +734,25 @@ function foldIdentityManifest(
   const workspaceTypes = foldById(manifests.map((m) => m.workspaceTypes));
   const homes = foldRecord(manifests.map((m) => m.homes));
   const routes = foldByKey(manifests.map((m) => m.routes), (r) => r.directive);
+  const aggregatesById = new Map<string, NonNullable<UsdLayer["nomosIdentityManifest"]>["aggregates"][number]>();
+  for (const manifest of manifests) {
+    for (const aggregate of manifest.aggregates) aggregatesById.set(aggregate.id, aggregate);
+  }
+  // Aggregate namespace qualification happens after the canonical manifest has
+  // sorted its bare business labels. Preserve that order here: sorting the final
+  // `co2.Asset` spelling would incorrectly move every framework aggregate ahead
+  // of the tenant model even though the laws are otherwise identical.
+  const identityLabel = (id: string): string => id.slice(id.lastIndexOf(".") + 1);
+  const aggregates = [...aggregatesById.values()].sort((a, b) => {
+    const aLabel = identityLabel(a.id);
+    const bLabel = identityLabel(b.id);
+    return aLabel !== bLabel
+      ? aLabel < bLabel ? -1 : 1
+      : a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+  });
   return {
     domain,
-    aggregates: foldById(manifests.map((m) => m.aggregates)) ?? [],
+    aggregates,
     directives: foldById(manifests.map((m) => m.directives)) ?? [],
     ...(stableIds !== undefined ? { stableIds } : {}),
     ...(workspaceInvariants !== undefined ? { workspaceInvariants } : {}),
@@ -702,14 +843,18 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         stableIds = { v: 1, domain: domainSid, aggregates };
       }
     }
-    // THE STRUCTURAL INTERFACE (#72): fold per-module interfaces — directives + aggregates merged
-    // later-wins, SORTED keys (matching the composed emission's sorted-key `domainInterface`).
+    // THE STRUCTURAL INTERFACE (#72): fold per-module interfaces — directives, aggregates and their
+    // declared cross-workspace read edges merge later-wins, with sorted keys (matching the composed
+    // emission's sorted-key `domainInterface`). `foreignReads` is optional only at the final boundary;
+    // dropping it while folding makes a layered package describe a weaker law than its module fold.
     let iface: UsdLayer["nomosInterface"];
     {
       type Dir = NonNullable<UsdLayer["nomosInterface"]>["directives"][string];
       type Agg = NonNullable<UsdLayer["nomosInterface"]>["aggregates"][string];
+      type ForeignReads = NonNullable<NonNullable<UsdLayer["nomosInterface"]>["foreignReads"]>[string];
       const dirs = new Map<string, Dir>();
       const aggsI = new Map<string, Agg>();
+      const foreignReads = new Map<string, ForeignReads>();
       let domainI: string | undefined;
       let domainSidI: string | undefined;
       for (const l of stack) {
@@ -718,18 +863,22 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         domainSidI = l.nomosInterface.domainSid;
         for (const [id, spec] of Object.entries(l.nomosInterface.directives)) dirs.set(id, spec);
         for (const [sid, spec] of Object.entries(l.nomosInterface.aggregates)) aggsI.set(sid, spec);
+        for (const [id, edges] of Object.entries(l.nomosInterface.foreignReads ?? {})) foreignReads.set(id, edges);
       }
       if (domainI !== undefined) {
         const directivesRec: Record<string, Dir> = {};
         for (const k of [...dirs.keys()].sort()) directivesRec[k] = dirs.get(k)!;
         const aggregatesRec: Record<string, Agg> = {};
         for (const k of [...aggsI.keys()].sort()) aggregatesRec[k] = aggsI.get(k)!;
+        const foreignReadsRec: Record<string, ForeignReads> = {};
+        for (const k of [...foreignReads.keys()].sort()) foreignReadsRec[k] = foreignReads.get(k)!;
         iface = {
           v: 1,
           domain: domainI,
           ...(domainSidI !== undefined ? { domainSid: domainSidI } : {}),
           directives: directivesRec,
           aggregates: aggregatesRec,
+          ...(foreignReads.size > 0 ? { foreignReads: foreignReadsRec } : {}),
         };
       }
     }
@@ -754,6 +903,29 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         readGate = { v: 1, queries: queriesRec, directives: directivesRec };
       }
     }
+    // THE INVARIANT GATE: aggregate invariant presence is a set; named workspace
+    // invariants are later-wins by id. Both are sorted exactly as the canonical emit.
+    let invariantGate: UsdLayer["nomosInvariantGate"];
+    {
+      const aggregates = new Set<string>();
+      const workspaceInvariants = new Map<string, { id: string; on: string }>();
+      for (const layer of stack) {
+        if (layer.nomosInvariantGate === undefined) continue;
+        for (const aggregate of layer.nomosInvariantGate.aggregates ?? []) aggregates.add(aggregate);
+        for (const invariant of layer.nomosInvariantGate.workspaceInvariants ?? []) {
+          workspaceInvariants.set(invariant.id, invariant);
+        }
+      }
+      if (aggregates.size > 0 || workspaceInvariants.size > 0) {
+        invariantGate = {
+          v: 1,
+          ...(aggregates.size > 0 ? { aggregates: [...aggregates].sort() } : {}),
+          ...(workspaceInvariants.size > 0
+            ? { workspaceInvariants: [...workspaceInvariants.values()].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0) }
+            : {}),
+        };
+      }
+    }
     // The read-visibility gate (slice 5.1): per-aggregate required-read caps merged
     // later-wins, SORTED keys (matching the composed emission). Omit-when-empty.
     let readVisibility: UsdLayer["nomosReadVisibility"];
@@ -784,6 +956,27 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         encryption = { v: 1, aggregates: aggregatesRec };
       }
     }
+    // DECLARED IMPURE CAPABILITIES: compiler composition dedupes by task aggregate;
+    // mirror that exact rule here, with the stronger layer winning and canonical
+    // aggregate-id order. Omit-when-empty (the capability era rule).
+    let capabilities: UsdLayer["nomosCapabilities"];
+    {
+      type Capability = NonNullable<UsdLayer["nomosCapabilities"]>["capabilities"][number];
+      const byAggregate = new Map<string, Capability>();
+      for (const layer of stack) {
+        for (const capability of layer.nomosCapabilities?.capabilities ?? []) {
+          byAggregate.set(capability.aggregateId, capability);
+        }
+      }
+      if (byAggregate.size > 0) {
+        capabilities = {
+          v: 1,
+          capabilities: [...byAggregate.values()].sort((a, b) =>
+            a.aggregateId < b.aggregateId ? -1 : a.aggregateId > b.aggregateId ? 1 : 0,
+          ),
+        };
+      }
+    }
     // THE ATTRIBUTED-READS GATE (field_provenance.md): per-aggregate attributed-field
     // sets merged later-wins, SORTED keys (matching the composed emission). Omit-when-empty.
     let attributedGate: UsdLayer["nomosAttributedGate"];
@@ -1074,7 +1267,7 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         };
       }
     }
-return {
+    return {
       path,
       prims: [...prims.keys()].sort().map((p) => prims.get(p)!),
       ...(identityManifest !== undefined ? { nomosIdentityManifest: identityManifest } : {}),
@@ -1085,8 +1278,10 @@ return {
       ...(stableIds !== undefined ? { nomosStableIds: stableIds } : {}),
       ...(iface !== undefined ? { nomosInterface: iface } : {}),
       ...(readGate !== undefined ? { nomosReadGate: readGate } : {}),
+      ...(invariantGate !== undefined ? { nomosInvariantGate: invariantGate } : {}),
       ...(readVisibility !== undefined ? { nomosReadVisibility: readVisibility } : {}),
       ...(encryption !== undefined ? { nomosEncryption: encryption } : {}),
+      ...(capabilities !== undefined ? { nomosCapabilities: capabilities } : {}),
       ...(attributedGate !== undefined ? { nomosAttributedGate: attributedGate } : {}),
       ...(relations !== undefined ? { nomosRelations: relations } : {}),
       ...(relationNamespace !== undefined ? { nomosRelationNamespace: relationNamespace } : {}),
@@ -1118,15 +1313,21 @@ return {
 interface ParsedPrim {
   /** Sanitized prim path, e.g. `/Nomos/guestbook/GuestbookEntry`. */
   readonly path: string;
-  readonly attrs: Map<string, string | string[]>;
+  readonly attrs: Map<string, string | string[] | number | boolean>;
 }
 
 const ATTR_STRING = /^custom\s+string\s+([\w:]+)\s*=\s*"((?:[^"\\]|\\.)*)"$/;
 const ATTR_STRING_ARRAY = /^custom\s+string\[\]\s+([\w:]+)\s*=\s*\[(.*)\]$/;
+const ATTR_NUMBER = /^custom\s+(?:double|int64)\s+([\w:]+)\s*=\s*(-?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?)$/;
+const ATTR_BOOL = /^custom\s+bool\s+([\w:]+)\s*=\s*(true|false|0|1)$/;
 const PRIM_HEADER = /^(?:def|over|class)(?:\s+\w+)?\s+"([^"]+)"/;
 
 function unescapeUsda(s: string): string {
-  return s.replace(/\\(.)/g, "$1");
+  try {
+    return JSON.parse(`"${s}"`) as string;
+  } catch {
+    throw new Error("usd-layers: invalid escaped USDA string");
+  }
 }
 
 function parseStringArrayItems(inner: string): string[] {
@@ -1194,10 +1395,98 @@ function parseUsdaPrims(text: string): ParsedPrim[] {
       top.attrs.set(str[1]!, unescapeUsda(str[2]!));
       continue;
     }
+    const number = ATTR_NUMBER.exec(line);
+    if (number !== null) {
+      top.attrs.set(number[1]!, Number(number[2]!));
+      continue;
+    }
+    const bool = ATTR_BOOL.exec(line);
+    if (bool !== null) top.attrs.set(bool[1]!, bool[2] === "true" || bool[2] === "1");
   }
   return prims;
 }
 
+/** Decode one content-addressed native USD value tree immediately beneath `parentPath`. */
+function nativeValueAt(prims: readonly ParsedPrim[], parentPath: string, name: string): unknown | undefined {
+  const depth = (path: string) => path.split("/").length;
+  const parent = prims.find((prim) => prim.path === parentPath);
+  const hash = parent?.attrs.get(`nomos:value:${name}`);
+  if (hash === undefined) return undefined;
+  if (typeof hash !== "string" || !/^[0-9a-f]{64}$/.test(hash)) {
+    throw new Error(`usd-layers: native value '${name}' has an invalid content address`);
+  }
+  const rootPath = `${parentPath}/__nms_${primName(name)}_${hash}`;
+  const root = prims.find((prim) => prim.path === rootPath);
+  if (root === undefined) {
+    throw new Error(`usd-layers: native value '${name}' points to missing content '${hash}'`);
+  }
+  const descendants = prims.filter((prim) => prim.path === rootPath || prim.path.startsWith(`${rootPath}/`));
+  const directChildren = (path: string): ParsedPrim[] => descendants.filter((candidate) =>
+    candidate.path.startsWith(`${path}/`) && depth(candidate.path) === depth(path) + 1);
+  const decodeKey = (hex: string, path: string): string => {
+    if (!/^(?:[0-9a-f]{2})*$/.test(hex)) {
+      throw new Error(`usd-layers: native object child '${path}' has an invalid key`);
+    }
+    return Buffer.from(hex, "hex").toString("utf8");
+  };
+  type NativeEntry = { readonly index: number; readonly key?: string; readonly value: unknown };
+  const decode = (prim: ParsedPrim): unknown => {
+    const kind = prim.attrs.get("nomos:containerKind");
+    if (kind !== "scalar" && kind !== "array" && kind !== "object") {
+      throw new Error(`usd-layers: native value container '${prim.path}' has no valid kind`);
+    }
+    const entries: NativeEntry[] = [];
+    for (const [attr, value] of prim.attrs) {
+      const match = /^nomos:(sv|bv|nv|zv):i(\d{6})(?::k([0-9a-f]*))?$/.exec(attr);
+      if (match === null) continue;
+      const scalarKind = match[1]!;
+      const key = match[3] === undefined ? undefined : decodeKey(match[3], prim.path);
+      const scalar = scalarKind === "zv" ? null : value;
+      if ((scalarKind === "sv" && typeof scalar !== "string") ||
+          (scalarKind === "bv" && typeof scalar !== "boolean") ||
+          (scalarKind === "nv" && typeof scalar !== "number") ||
+          (scalarKind === "zv" && value !== true)) {
+        throw new Error(`usd-layers: native scalar '${attr}' has the wrong USD type`);
+      }
+      entries.push({ index: Number(match[2]!), ...(key === undefined ? {} : { key }), value: scalar });
+    }
+    for (const child of directChildren(prim.path)) {
+      const childName = child.path.slice(child.path.lastIndexOf("/") + 1);
+      const match = /^i(\d{6})(?:_k([0-9a-f]*))?$/.exec(childName);
+      if (match === null) {
+        throw new Error(`usd-layers: native child '${child.path}' has an invalid position`);
+      }
+      const key = match[2] === undefined ? undefined : decodeKey(match[2], child.path);
+      entries.push({ index: Number(match[1]!), ...(key === undefined ? {} : { key }), value: decode(child) });
+    }
+    entries.sort((a, b) => a.index - b.index);
+    if (entries.some((entry, index) => entry.index !== index)) {
+      throw new Error(`usd-layers: native value container '${prim.path}' has missing or duplicate positions`);
+    }
+    if (kind === "scalar") {
+      if (entries.length !== 1 || entries[0]!.key !== undefined) {
+        throw new Error(`usd-layers: native scalar container '${prim.path}' must contain exactly one unkeyed value`);
+      }
+      return entries[0]!.value;
+    }
+    if (kind === "array") {
+      if (entries.some((entry) => entry.key !== undefined)) {
+        throw new Error(`usd-layers: native array container '${prim.path}' contains an object key`);
+      }
+      return entries.map((entry) => entry.value);
+    }
+    {
+      const out: Record<string, unknown> = {};
+      for (const entry of entries) {
+        if (entry.key === undefined) throw new Error(`usd-layers: native object container '${prim.path}' contains an unkeyed value`);
+        out[entry.key] = entry.value;
+      }
+      return out;
+    }
+  };
+  return decode(root);
+}
+
 function attrString(prim: ParsedPrim, name: string): string {
   const v = prim.attrs.get(name);
   if (typeof v !== "string") {
@@ -1218,8 +1507,8 @@ function attrStringArray(prim: ParsedPrim, name: string): string[] {
  * Reconstruct the IR `UsdDocument` from usda text this module emitted — either ONE
  * module layer or a usdcat-FLATTENED stage. Domains are identified by their scope
  * prim (`nomos:kind = "domain"`); every child prim rebuilds from its `nomos:*`
- * attributes into the canonical prim shape (so the result is directly comparable —
- * `JSON.stringify`-byte-comparable — with `emitUsd` / `flattenLayeredUsd` output).
+ * attributes into the canonical prim shape (so canonicalJson comparison with
+ * `emitUsd` / `flattenLayeredUsd` compares law rather than USD formatting).
  */
 export function parseUsdaDocument(text: string): UsdDocument {
   const prims = parseUsdaPrims(text);
@@ -1229,8 +1518,10 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const stableIdsByDomain = new Map<string, UsdLayer["nomosStableIds"]>();
   const interfaceByDomain = new Map<string, UsdLayer["nomosInterface"]>();
   const readGateByDomain = new Map<string, UsdLayer["nomosReadGate"]>();
+  const invariantGateByDomain = new Map<string, UsdLayer["nomosInvariantGate"]>();
   const readVisibilityByDomain = new Map<string, UsdLayer["nomosReadVisibility"]>();
   const encryptionByDomain = new Map<string, UsdLayer["nomosEncryption"]>();
+  const capabilitiesByDomain = new Map<string, UsdLayer["nomosCapabilities"]>();
   const attributedGateByDomain = new Map<string, UsdLayer["nomosAttributedGate"]>();
   const relationsByDomain = new Map<string, UsdLayer["nomosRelations"]>();
   const relationGateByDomain = new Map<string, UsdLayer["nomosRelationGate"]>();
@@ -1252,120 +1543,24 @@ export function parseUsdaDocument(text: string): UsdDocument {
     if (p.attrs.get("nomos:kind") === "domain") {
       const domain = attrString(p, "nomos:domain");
       domainByScope.set(p.path, domain);
-      // Holon-owned manifests + gates: the hex-carried layer-level law keys.
-      const idHex = p.attrs.get("nomos:identityManifestHex");
-      if (typeof idHex === "string") {
-        identityManifestByDomain.set(domain, JSON.parse(unhexUtf8(idHex)) as UsdLayer["nomosIdentityManifest"]);
-      }
-      const rpHex = p.attrs.get("nomos:readProjectionHex");
-      if (typeof rpHex === "string") {
-        readProjectionByDomain.set(domain, JSON.parse(unhexUtf8(rpHex)) as UsdLayer["nomosReadProjection"]);
-      }
-      const sidHex = p.attrs.get("nomos:stableIdsHex");
-      if (typeof sidHex === "string") {
-        stableIdsByDomain.set(domain, JSON.parse(unhexUtf8(sidHex)) as UsdLayer["nomosStableIds"]);
-      }
-      // THE STRUCTURAL INTERFACE (#72): the on-ledger OFFER, hex-carried per domain layer.
-      const ifaceHex = p.attrs.get("nomos:interfaceHex");
-      if (typeof ifaceHex === "string") {
-        interfaceByDomain.set(domain, JSON.parse(unhexUtf8(ifaceHex)) as UsdLayer["nomosInterface"]);
-      }
-      const rgHex = p.attrs.get("nomos:readGateHex");
-      if (typeof rgHex === "string") {
-        readGateByDomain.set(domain, JSON.parse(unhexUtf8(rgHex)) as UsdLayer["nomosReadGate"]);
-      }
-      // THE READ-VISIBILITY GATE (slice 5.1): the hex-carried per-aggregate cap map.
-      const rvHex = p.attrs.get("nomos:readVisibilityHex");
-      if (typeof rvHex === "string") {
-        readVisibilityByDomain.set(domain, JSON.parse(unhexUtf8(rvHex)) as UsdLayer["nomosReadVisibility"]);
-      }
-      // THE ENCRYPTION GATE (slice 2): the hex-carried per-aggregate encrypted-field map.
-      const encHex = p.attrs.get("nomos:encryptionHex");
-      if (typeof encHex === "string") {
-        encryptionByDomain.set(domain, JSON.parse(unhexUtf8(encHex)) as UsdLayer["nomosEncryption"]);
-      }
-      // THE ATTRIBUTED-READS GATE (field_provenance.md): the hex-carried per-aggregate map.
-      const attrHex = p.attrs.get("nomos:attributedGateHex");
-      if (typeof attrHex === "string") {
-        attributedGateByDomain.set(domain, JSON.parse(unhexUtf8(attrHex)) as UsdLayer["nomosAttributedGate"]);
-      }
-      // THE RELATION SCHEMA (P1): the hex-carried per-type relation rewrite map.
-      const relHex = p.attrs.get("nomos:relationsHex");
-      if (typeof relHex === "string") {
-        relationsByDomain.set(domain, JSON.parse(unhexUtf8(relHex)) as UsdLayer["nomosRelations"]);
-      }
-      // THE RELATION GATE (P4): the hex-carried directiveId → {relation, object} map.
-      const relGateHex = p.attrs.get("nomos:relationGateHex");
-      if (typeof relGateHex === "string") {
-        relationGateByDomain.set(domain, JSON.parse(unhexUtf8(relGateHex)) as UsdLayer["nomosRelationGate"]);
-      }
-      // THE RELATION-NAMESPACE ERA KEY (relation-namespacing): the hex-carried qualified-type witness.
-      const relNsHex = p.attrs.get("nomos:relationNamespaceHex");
-      if (typeof relNsHex === "string") {
-        relationNamespaceByDomain.set(domain, JSON.parse(unhexUtf8(relNsHex)) as UsdLayer["nomosRelationNamespace"]);
-      }
-      // THE READ-PROJECTION-NAMESPACE ERA KEY: the hex-carried qualified-aggregate witness.
-      const rpNsHex = p.attrs.get("nomos:readProjectionNamespaceHex");
-      if (typeof rpNsHex === "string") {
-        readProjectionNamespaceByDomain.set(domain, JSON.parse(unhexUtf8(rpNsHex)) as UsdLayer["nomosReadProjectionNamespace"]);
-      }
-      // THE ATTESTATION GATE (home_holons §3/§5): the hex-carried attestation-authorized directive set.
-      const attGateHex = p.attrs.get("nomos:attestationGateHex");
-      if (typeof attGateHex === "string") {
-        attestationGateByDomain.set(domain, JSON.parse(unhexUtf8(attGateHex)) as UsdLayer["nomosAttestationGate"]);
-      }
-      // THE DELEGATED-AUTHORITY GATE (delegated_authority_births.md): the hex-carried delegation spec.
-      const delGateHex = p.attrs.get("nomos:delegationGateHex");
-      if (typeof delGateHex === "string") {
-        delegationGateByDomain.set(domain, JSON.parse(unhexUtf8(delGateHex)) as UsdLayer["nomosDelegationGate"]);
-      }
-      // THE ATTESTED-READ GATE (slice B): the hex-carried trust-edge declaration.
-      const attReadGateHex = p.attrs.get("nomos:attestedReadGateHex");
-      if (typeof attReadGateHex === "string") {
-        attestedReadGateByDomain.set(domain, JSON.parse(unhexUtf8(attReadGateHex)) as UsdLayer["nomosAttestedReadGate"]);
-      }
-      // THE BIRTH GATE (G3): the hex-carried `.births()` directive set.
-      const birthGateHex = p.attrs.get("nomos:birthGateHex");
-      if (typeof birthGateHex === "string") {
-        birthGateByDomain.set(domain, JSON.parse(unhexUtf8(birthGateHex)) as UsdLayer["nomosBirthGate"]);
-      }
-      // THE BIRTH-RECORD GATE (metered birth, A1): the hex-carried record declaration.
-      const birthRecordGateHex = p.attrs.get("nomos:birthRecordGateHex");
-      if (typeof birthRecordGateHex === "string") {
-        birthRecordGateByDomain.set(domain, JSON.parse(unhexUtf8(birthRecordGateHex)) as UsdLayer["nomosBirthRecordGate"]);
-      }
-      // THE PEER-SOVEREIGN ROOT-OF-TRUST: the hex-carried parent-attested-birth era marker.
-      const pabHex = p.attrs.get("nomos:parentAttestedBirthHex");
-      if (typeof pabHex === "string") {
-        parentAttestedBirthByDomain.set(domain, JSON.parse(unhexUtf8(pabHex)) as UsdLayer["nomosParentAttestedBirth"]);
-      }
-      // THE KEYLESS VERIFIED-FIRST-DEVICE GATE: the hex-carried era marker.
-      const vfeHex = p.attrs.get("nomos:verifiedFirstEnrollHex");
-      if (typeof vfeHex === "string") {
-        verifiedFirstEnrollByDomain.set(domain, JSON.parse(unhexUtf8(vfeHex)) as UsdLayer["nomosVerifiedFirstEnroll"]);
-      }
-      const ecgHex = p.attrs.get("nomos:eraCertGateHex");
-      if (typeof ecgHex === "string") {
-        eraCertGateByDomain.set(domain, JSON.parse(unhexUtf8(ecgHex)) as UsdLayer["nomosEraCertGate"]);
-      }
-      // FIRST-CLASS VALUE OBJECTS: the hex-carried descriptor set (descriptive, not a gate).
-      const voHex = p.attrs.get("nomos:valueObjectsHex");
-      if (typeof voHex === "string") {
-        valueObjectsByDomain.set(domain, JSON.parse(unhexUtf8(voHex)) as UsdLayer["nomosValueObjects"]);
-      }
-      const frHex = p.attrs.get("nomos:foreignRefsHex");
-      if (typeof frHex === "string") {
-        foreignRefsByDomain.set(domain, JSON.parse(unhexUtf8(frHex)) as UsdLayer["nomosForeignRefs"]);
-      }
-      // DOMAIN CONTRACTS: the hex-carried public DTO descriptor set (descriptive, not a gate).
-      const ctHex = p.attrs.get("nomos:contractsHex");
-      if (typeof ctHex === "string") {
-        contractsByDomain.set(domain, JSON.parse(unhexUtf8(ctHex)) as UsdLayer["nomosContracts"]);
-      }
-      const flowGateHex = p.attrs.get("nomos:flowGateHex");
-      if (typeof flowGateHex === "string") {
-        flowGateByDomain.set(domain, JSON.parse(unhexUtf8(flowGateHex)) as UsdLayer["nomosFlowGate"]);
-      }
+      // Structured law is native USD; no embedded serialization has an alternate vote.
+      const native = (name: string): unknown | undefined => nativeValueAt(prims, p.path, name);
+      const set = <T>(name: string, target: Map<string, T>): void => {
+        const value = native(name);
+        if (value !== undefined) target.set(domain, value as T);
+      };
+      set("identityManifest", identityManifestByDomain); set("readProjection", readProjectionByDomain);
+      set("stableIds", stableIdsByDomain); set("interface", interfaceByDomain); set("readGate", readGateByDomain);
+      set("invariantGate", invariantGateByDomain); set("readVisibility", readVisibilityByDomain);
+      set("encryption", encryptionByDomain); set("capabilities", capabilitiesByDomain);
+      set("attributedGate", attributedGateByDomain); set("relations", relationsByDomain);
+      set("relationGate", relationGateByDomain); set("relationNamespace", relationNamespaceByDomain);
+      set("readProjectionNamespace", readProjectionNamespaceByDomain); set("attestationGate", attestationGateByDomain);
+      set("delegationGate", delegationGateByDomain); set("attestedReadGate", attestedReadGateByDomain);
+      set("birthGate", birthGateByDomain); set("birthRecordGate", birthRecordGateByDomain);
+      set("parentAttestedBirth", parentAttestedBirthByDomain); set("verifiedFirstEnroll", verifiedFirstEnrollByDomain);
+      set("eraCertGate", eraCertGateByDomain); set("valueObjects", valueObjectsByDomain);
+      set("foreignRefs", foreignRefsByDomain); set("contracts", contractsByDomain); set("flowGate", flowGateByDomain);
     }
   }
 
@@ -1388,6 +1583,9 @@ export function parseUsdaDocument(text: string): UsdDocument {
   for (const p of prims) {
     const kind = p.attrs.get("nomos:kind");
     if (typeof kind !== "string" || kind === "domain") continue;
+    // A self-contained runtime package also carries the obscure framework-owned plan index at a
+    // separate root. It is USD, but it is not domain law and must not be projected into the IR.
+    if (!p.path.startsWith("/Nomos/")) continue;
     const scopePath = p.path.slice(0, p.path.lastIndexOf("/"));
     const domain = domainByScope.get(scopePath);
     if (domain === undefined) {
@@ -1401,21 +1599,18 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const schema: WireSchema = {};
       for (const [name, value] of p.attrs) {
         if (name.startsWith("nomos:driver:") && typeof value === "string") {
-          schema[name.slice("nomos:driver:".length)] = parseDriverToken(value);
+          schema[parseFieldToken(name.slice("nomos:driver:".length))] = parseDriverToken(value);
         }
       }
       b.prims.push({ kind: "aggregate", path: irPath, type: id, schema: sortedSchema(schema) });
     } else if (kind === "directive") {
       const reads = p.attrs.has("nomos:reads") ? attrStringArray(p, "nomos:reads") : undefined;
-      const emits = p.attrs.has("nomos:emitsHex")
-        ? (JSON.parse(unhexUtf8(attrString(p, "nomos:emitsHex"))) as Record<string, { max?: number }>)
-        : undefined;
-      const secondaryOutputs = p.attrs.has("nomos:secondaryOutputsHex")
-        ? (JSON.parse(unhexUtf8(attrString(p, "nomos:secondaryOutputsHex"))) as { target: string; marker: WireRefMode }[])
-        : undefined;
-      const payloadJsonSchema = p.attrs.has("nomos:payloadJsonSchemaHex")
-        ? (JSON.parse(unhexUtf8(attrString(p, "nomos:payloadJsonSchemaHex"))) as unknown)
-        : undefined;
+      const nativeEmits = nativeValueAt(prims, p.path, "emits");
+      const nativeSecondaryOutputs = nativeValueAt(prims, p.path, "secondaryOutputs");
+      const nativePayloadJsonSchema = nativeValueAt(prims, p.path, "payloadJsonSchema");
+      const emits = nativeEmits as Record<string, { max?: number }> | undefined;
+      const secondaryOutputs = nativeSecondaryOutputs as { target: string; marker: WireRefMode }[] | undefined;
+      const payloadJsonSchema = nativePayloadJsonSchema;
       b.prims.push({
         kind: "directive",
         path: irPath,
@@ -1434,18 +1629,20 @@ export function parseUsdaDocument(text: string): UsdDocument {
         returns: attrString(p, "nomos:returns"),
       });
     } else if (kind === "derived") {
+      const nativeReturns = nativeValueAt(prims, p.path, "returns");
       b.deriveds.push({
         id,
         of: attrString(p, "nomos:of"),
-        returns: JSON.parse(unhexUtf8(attrString(p, "nomos:returnsHex"))) as UsdDerived["returns"],
+        returns: nativeReturns as UsdDerived["returns"],
       });
     } else if (kind === "combined") {
+      const nativeReturns = nativeValueAt(prims, p.path, "returns");
       b.combineds.push({
         id,
         of: attrString(p, "nomos:of"),
         refField: attrString(p, "nomos:refField"),
         reads: attrString(p, "nomos:readsFrom"),
-        returns: JSON.parse(unhexUtf8(attrString(p, "nomos:returnsHex"))) as UsdCombined["returns"],
+        returns: nativeReturns as UsdCombined["returns"],
       });
     } else {
       throw new Error(`usd-layers: prim ${p.path} has unknown nomos:kind '${kind}'`);
@@ -1462,8 +1659,10 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const sids = stableIdsByDomain.get(domain);
       const iface = interfaceByDomain.get(domain);
       const rg = readGateByDomain.get(domain);
+      const invariantGate = invariantGateByDomain.get(domain);
       const rv = readVisibilityByDomain.get(domain);
       const enc = encryptionByDomain.get(domain);
+      const capabilities = capabilitiesByDomain.get(domain);
       const attrGate = attributedGateByDomain.get(domain);
       const rel = relationsByDomain.get(domain);
       const relGate = relationGateByDomain.get(domain);
@@ -1492,8 +1691,10 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(sids !== undefined ? { nomosStableIds: sids } : {}),
         ...(iface !== undefined ? { nomosInterface: iface } : {}),
         ...(rg !== undefined ? { nomosReadGate: rg } : {}),
+        ...(invariantGate !== undefined ? { nomosInvariantGate: invariantGate } : {}),
         ...(rv !== undefined ? { nomosReadVisibility: rv } : {}),
         ...(enc !== undefined ? { nomosEncryption: enc } : {}),
+        ...(capabilities !== undefined ? { nomosCapabilities: capabilities } : {}),
         ...(attrGate !== undefined ? { nomosAttributedGate: attrGate } : {}),
         ...(rel !== undefined ? { nomosRelations: rel } : {}),
         ...(relNs !== undefined ? { nomosRelationNamespace: relNs } : {}),