@githolon/dsl 0.102.4 → 0.103.0

package/src/usd_layers.ts

@@ -1,1776 +0,0 @@
-// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
-// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
-// wasm32-wasip1 artifact {kernel · projection · embedded
-// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
-// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
-// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
-
-/**
- * USD LAYERED EMISSION + the flatten-equivalence fold — the composability spike.
- *
- * THE THESIS (the monoid homomorphism): Nomos's module fold and USD's layer stack
- * are the SAME non-commutative monoid. `composeDomainModule` spread-merges a
- * domain's ordered module list (later wins — a left-biased fold over export bags);
- * a USD layer stack resolves the strongest opinion per attribute (stronger layer
- * wins — a left-biased fold over opinion maps). This module makes the
- * correspondence MECHANICAL:
- *
- *   * `emitLayeredDomain` lowers each authored MODULE into its own `UsdLayer`
- *     (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 CANONICAL LAW EQUALITY:
- *
- *       canonicalJson(flattenLayeredUsd(layers)) === canonicalJson(emitUsd([composed]))
- *
- *     i.e. Φ(fold_modules(A, B)) == fold_layers(Φ(A), Φ(B)) — flatten-after-lower
- *     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
- * silent about it), while the module fold replaces a re-exported declaration
- * WHOLESALE. The two coincide exactly when every re-declaration is TOTAL over its
- * attribute set — which the DSL guarantees structurally for aggregates
- * (`aggregate()` takes the full field record; there is no partial declaration) and
- * 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 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
- * left-biased fold (order is meaning — the layer stack); STATE merge is the
- * 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. 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
- * typed MONOTONIC governance lane (`mergeUsdPrim`, fail-closed rules) — a
- * different, stricter composition than the opinion fold here, on purpose: a tenant
- * 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 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";
-import type { WireDriver, WireRefMode, WireSchema } from "./wire.js";
-import {
-  emitUsd,
-  type UsdCombined,
-  type UsdDerived,
-  type UsdDocument,
-  type UsdLayer,
-  type UsdPrim,
-  type UsdQuery,
-} from "./usd.js";
-import { composeSharedRelationTypes } from "./relation_composition.js";
-import { withBusinessCorrectionLayer } from "./framework/business_corrections.js";
-
-/** The layer-file format marker (customLayerData `nomos:format`). */
-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";
-
-/** Append generated lines without turning a large law into function arguments. */
-function appendLines(target: string[], lines: readonly string[]): void {
-  for (const line of lines) target.push(line);
-}
-
-// ── small codecs ───────────────────────────────────────────────────────────────────
-
-/** Escape a string for a double-quoted usda string literal. */
-export function usdaString(s: string): string {
-  return JSON.stringify(s);
-}
-
-/** A usda `string[]` literal. */
-export function usdaStringArray(items: readonly string[]): string {
-  return `[${items.map(usdaString).join(", ")}]`;
-}
-
-/**
- * A `WireDriver` as a READABLE usda token: unit drivers are their bare serde
- * string (`"Lww"`, `"AddWins"`, `"LwwCausal"`, …); `MapOf` nests as `MapOf(<inner>)`;
- * the EXPLICIT TIME-AUTHORITY `LwwBy` carries its principal as `LwwBy(<principal>)`.
- * Readable on purpose — the usdcat/usdview tree is the visual proof, so the merge law
- * (and the time-authority) of every field must be legible in it (hex would bury the point).
- */
-export function driverToken(driver: WireDriver): string {
-  if (typeof driver === "string") return driver;
-  if ("LwwBy" in driver) return `LwwBy(${driver.LwwBy})`;
-  // `Surfaced(<inner>)` — the user-resolvable posture stays legible in the tree too.
-  if ("Surfaced" in driver) return `Surfaced(${driverToken(driver.Surfaced)})`;
-  // `Attributed(<inner>)` — attributed reads (field_provenance.md), legible in the tree.
-  if ("Attributed" in driver) return `Attributed(${driverToken(driver.Attributed)})`;
-  return `MapOf(${driverToken(driver.MapOf)})`;
-}
-
-/** Inverse of {@link driverToken} — fail-closed on a malformed token. */
-export function parseDriverToken(token: string): WireDriver {
-  if (token.startsWith("MapOf(") && token.endsWith(")")) {
-    return { MapOf: parseDriverToken(token.slice("MapOf(".length, -1)) };
-  }
-  if (token.startsWith("Surfaced(") && token.endsWith(")")) {
-    return { Surfaced: parseDriverToken(token.slice("Surfaced(".length, -1)) };
-  }
-  if (token.startsWith("Attributed(") && token.endsWith(")")) {
-    return { Attributed: parseDriverToken(token.slice("Attributed(".length, -1)) };
-  }
-  // `LwwBy(<principal>)` — the principal is an opaque non-empty string (uids carry
-  // hyphens, so it is NOT the bare-identifier shape the unit-driver branch validates).
-  if (token.startsWith("LwwBy(") && token.endsWith(")")) {
-    const principal = token.slice("LwwBy(".length, -1);
-    if (principal.length === 0) {
-      throw new Error(`usd-layers: LwwBy driver token names no time-authority principal`);
-    }
-    return { LwwBy: principal };
-  }
-  if (!/^[A-Za-z][A-Za-z0-9]*$/.test(token)) {
-    throw new Error(`usd-layers: malformed driver token '${token}'`);
-  }
-  return token as WireDriver;
-}
-
-/** A valid USD prim-name identifier for an arbitrary id (raw id rides `nomos:id`). */
-export function primName(id: string): string {
-  const sanitized = id.replace(/[^A-Za-z0-9_]/g, "_");
-  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("");
-        appendLines(lines, emitContainer(identity.replace(/:/g, "_"), child, `${at}    `));
-      } else {
-        lines.push(scalarLine(child, identity, `${at}    `));
-      }
-    });
-    lines.push(`${at}}`);
-    return lines;
-  };
-  const rootName = `__nms_${primName(name)}_${hash}`;
-  const lines = [`${indent}custom string nomos:value:${name} = ${usdaString(hash)}`, ""];
-  appendLines(lines, emitContainer(rootName, value, indent));
-  return lines;
-}
-
-/** Field→driver map with keys sorted (the canonical schema shape `manifest.ts` emits). */
-function sortedSchema(schema: WireSchema): WireSchema {
-  const out: WireSchema = {};
-  for (const k of Object.keys(schema).sort()) out[k] = schema[k]!;
-  return out;
-}
-
-function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string): string[] {
-  const attrs = [
-    `${indent}custom string nomos:kind = "domain"`,
-    `${indent}custom string nomos:domain = ${usdaString(domain)}`,
-  ];
-  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) continue;
-    attrs.push("");
-    appendLines(attrs, nativeValueLines(name, value, indent));
-  }
-  return attrs;
-}
-
-// ── per-module layer emission ────────────────────────────────────────────────────────
-
-/** One authored module of a domain's ordered module list (weak → strong). */
-export interface LayeredModuleInput {
-  /** The layer stem (artifact basename) — usually the module file's basename. */
-  readonly name: string;
-  /** The module lowered ALONE (its own aggregates/directives/declared reads). */
-  readonly module: DomainModule;
-}
-
-/** One emitted module layer: the IR layer + its standalone `.usda` text. */
-export interface EmittedModuleLayer {
-  readonly name: string;
-  /** The module's `UsdLayer` (path = `/Nomos/<domain>`) — the layer JSON artifact. */
-  readonly layer: UsdLayer;
-  /** Real usda text standard USD tooling opens (usdcat/usdview/pxr). */
-  readonly usda: string;
-}
-
-/**
- * Lower ONE domain's ordered module list into per-module USD layers (weak → strong,
- * module order). Each module goes through the SAME `emitUsd` lowering the canonical
- * single-doc emission uses — Φ is one function, applied per module instead of once
- * over the composed module. Prim paths already defined by a WEAKER module of the
- * same stack are emitted with the USD `over` specifier (the stronger layer's
- * opinions compose over the weaker definition); first definitions are `def`s.
- */
-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`);
-  }
-  // 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()) {
-    const module = normalizedModules[index]!;
-    const doc = emitUsd([{ path: `/Nomos/${domain}`, module }]);
-    const layer = doc.layers[0]!;
-    const overPaths = new Set<string>();
-    for (const prim of layer.prims) {
-      if (seenPaths.has(prim.path)) overPaths.add(prim.path);
-    }
-    out.push({
-      name: m.name,
-      layer,
-      usda: usdaLayerText(domain, m.name, layer, module, overPaths),
-    });
-    for (const prim of layer.prims) seenPaths.add(prim.path);
-  }
-  return out;
-}
-
-/** The ref/hasMany decoration for one aggregate (USD relationships — visual arcs). */
-function relationLines(
-  domainScope: string,
-  agg: AggregateHandle | undefined,
-  indent: string,
-): string[] {
-  if (agg === undefined) return [];
-  const lines: string[] = [];
-  for (const [name, field] of Object.entries(agg.fields as Record<string, Field>).sort(
-    ([a], [b]) => (a < b ? -1 : a > b ? 1 : 0),
-  )) {
-    if (field.kind === "ref" && field.refAggregateId !== undefined) {
-      lines.push(
-        `${indent}custom rel nomos:ref:${name} = <${domainScope}/${primName(field.refAggregateId)}>`,
-      );
-    }
-  }
-  for (const [name, field] of Object.entries(agg.hasMany as Record<string, Field>).sort(
-    ([a], [b]) => (a < b ? -1 : a > b ? 1 : 0),
-  )) {
-    if (field.refAggregateId !== undefined) {
-      lines.push(
-        `${indent}custom rel nomos:hasMany:${name} = <${domainScope}/${primName(field.refAggregateId)}>`,
-      );
-      if (field.viaField !== undefined) {
-        lines.push(
-          `${indent}custom string nomos:hasMany:${name}:via = ${usdaString(field.viaField)}`,
-        );
-      }
-    }
-  }
-  return lines;
-}
-
-/**
- * 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. 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.
- */
-export function usdaLayerText(
-  domain: string,
-  moduleName: string,
-  layer: UsdLayer,
-  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);
-
-  const ind2 = "        ";
-  const ind3 = "            ";
-  const body: string[] = [];
-
-  for (const prim of layer.prims) {
-    const id = prim.path.slice(prim.path.lastIndexOf("/") + 1);
-    const spec = overPaths.has(prim.path) ? "over" : "def";
-    body.push(`${ind2}${spec} ${usdaString(primName(id))}`, `${ind2}{`);
-    if (prim.kind === "aggregate") {
-      body.push(
-        `${ind3}custom string nomos:kind = "aggregate"`,
-        `${ind3}custom string nomos:id = ${usdaString(prim.type)}`,
-      );
-      for (const [field, driver] of Object.entries(prim.schema)) {
-        body.push(`${ind3}custom string nomos:driver:${fieldToken(field)} = ${usdaString(driverToken(driver))}`);
-      }
-      appendLines(body, relationLines(domainScope, aggById.get(prim.type), ind3));
-    } else {
-      body.push(
-        `${ind3}custom string nomos:kind = "directive"`,
-        `${ind3}custom string nomos:id = ${usdaString(id)}`,
-        `${ind3}custom string nomos:target = ${usdaString(prim.target)}`,
-        `${ind3}custom string nomos:marker = ${usdaString(prim.marker)}`,
-        `${ind3}custom string[] nomos:requires = ${usdaStringArray(prim.requires)}`,
-      );
-      if (prim.reads !== undefined) {
-        body.push(`${ind3}custom string[] nomos:reads = ${usdaStringArray(prim.reads)}`);
-      }
-      if (prim.emits !== undefined) {
-        body.push("");
-        appendLines(body, nativeValueLines("emits", prim.emits, ind3));
-      }
-      if (prim.secondaryOutputs !== undefined) {
-        body.push("");
-        appendLines(body, nativeValueLines("secondaryOutputs", prim.secondaryOutputs, ind3));
-      }
-      if (prim.payloadJsonSchema !== undefined) {
-        body.push("");
-        appendLines(body, nativeValueLines("payloadJsonSchema", prim.payloadJsonSchema, ind3));
-      }
-    }
-    body.push(`${ind2}}`, ``);
-  }
-
-  for (const q of layer.queries ?? []) {
-    body.push(
-      `${ind2}def ${usdaString(primName(q.id))}`,
-      `${ind2}{`,
-      `${ind3}custom string nomos:kind = "query"`,
-      `${ind3}custom string nomos:id = ${usdaString(q.id)}`,
-      `${ind3}custom string[] nomos:key = ${usdaStringArray(q.key)}`,
-      `${ind3}custom string nomos:returns = ${usdaString(q.returns)}`,
-      `${ind2}}`,
-      ``,
-    );
-  }
-  for (const d of layer.deriveds ?? []) {
-    body.push(
-      `${ind2}def ${usdaString(primName(d.id))}`,
-      `${ind2}{`,
-      `${ind3}custom string nomos:kind = "derived"`,
-      `${ind3}custom string nomos:id = ${usdaString(d.id)}`,
-      `${ind3}custom string nomos:of = ${usdaString(d.of)}`,
-      ``,
-    );
-    appendLines(body, nativeValueLines("returns", d.returns, ind3));
-    body.push(
-      `${ind2}}`,
-      ``,
-    );
-  }
-  for (const c of layer.combineds ?? []) {
-    body.push(
-      `${ind2}def ${usdaString(primName(c.id))}`,
-      `${ind2}{`,
-      `${ind3}custom string nomos:kind = "combined"`,
-      `${ind3}custom string nomos:id = ${usdaString(c.id)}`,
-      `${ind3}custom string nomos:of = ${usdaString(c.of)}`,
-      `${ind3}custom string nomos:refField = ${usdaString(c.refField)}`,
-      `${ind3}custom string nomos:readsFrom = ${usdaString(c.reads)}`,
-      ``,
-    );
-    appendLines(body, nativeValueLines("returns", c.returns, ind3));
-    body.push(
-      `${ind2}}`,
-      ``,
-    );
-  }
-  // Drop the trailing blank line inside the scope.
-  if (body[body.length - 1] === "") body.pop();
-
-  const lines = [
-    `#usda 1.0`,
-    `(`,
-    `    customLayerData = {`,
-    `        string "nomos:format" = ${usdaString(NOMOS_USD_LAYER_FORMAT)}`,
-    `        string "nomos:domain" = ${usdaString(domain)}`,
-    `        string "nomos:module" = ${usdaString(moduleName)}`,
-    `    }`,
-    `)`,
-    ``,
-    `def Scope "Nomos"`,
-    `{`,
-    `    def Scope ${usdaString(primName(domain))}`,
-    `    {`,
-  ];
-  // Stable ids + holon-owned manifests: native layer-level law values.
-  appendLines(lines, domainLayerAttrLines(domain, layer, "        "));
-  lines.push(``);
-  appendLines(lines, body);
-  lines.push(
-    `    }`,
-    `}`,
-    ``,
-  );
-  return lines.join("\n");
-}
-
-/**
- * The layered ROOT document: a `#usda 1.0` whose subLayers stack the module layers.
- * INPUT order is Nomos module order (weak → strong, later wins); USD's subLayers
- * list is STRONGEST-FIRST, so the list is emitted REVERSED. Same monoid, opposite
- * notation — the reversal IS the correspondence, recorded in the doc string.
- */
-export function layeredRootUsda(
-  sublayerRelPathsWeakToStrong: readonly string[],
-  composed?: UsdDocument,
-): string {
-  const strongestFirst = [...sublayerRelPathsWeakToStrong].reverse();
-  const composedDomainOpinions: string[] = [];
-  if (composed !== undefined && composed.layers.length > 0) {
-    composedDomainOpinions.push(``, `over "Nomos"`, `{`);
-    for (const layer of composed.layers) {
-      const domain = layer.path.slice(layer.path.lastIndexOf("/") + 1);
-      composedDomainOpinions.push(`    over ${usdaString(primName(domain))}`, `    {`);
-      appendLines(composedDomainOpinions, domainLayerAttrLines(domain, layer, "        "));
-      composedDomainOpinions.push(`    }`);
-    }
-    composedDomainOpinions.push(`}`, ``);
-  }
-  const lines = [
-    `#usda 1.0`,
-    `(`,
-    `    doc = """Nomos layered domain package. subLayers are STRONGEST-FIRST (USD layer-stack`,
-    `order); the Nomos module list composes weak-to-strong (later wins) — the same`,
-    `left-biased fold, opposite list notation. Flattening this stage (usdcat --flatten)`,
-    `yields the SAME effective law as the flattened .package.usda emission."""`,
-    `    customLayerData = {`,
-    `        string "nomos:format" = ${usdaString(NOMOS_USD_LAYERED_PACKAGE_FORMAT)}`,
-    `    }`,
-    `    subLayers = [`,
-  ];
-  strongestFirst.forEach((p, index) => {
-    lines.push(`        @${p}@${index < strongestFirst.length - 1 ? "," : ""}`);
-  });
-  lines.push(
-    `    ]`,
-    `)`,
-  );
-  appendLines(lines, composedDomainOpinions);
-  lines.push(``);
-  return lines.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`);
-    appendLines(domainBlocks, lines.slice(start, end + 1));
-    domainBlocks.push("");
-  }
-  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(`    }`, `}`);
-
-  const lines = [
-    `#usda 1.0`,
-    `(`,
-    `    customLayerData = {`,
-    `        string "nomos:format" = ${usdaString(NOMOS_USD_PLAN_PACKAGE_FORMAT)}`,
-    `    }`,
-    `)`,
-    ``,
-    `def Scope "Nomos"`,
-    `{`,
-  ];
-  appendLines(lines, domainBlocks);
-  lines.push(
-    `}`,
-    ``,
-  );
-  appendLines(lines, runtime);
-  lines.push(``);
-  return lines.join("\n");
-}
-
-// ── the ordered opinion-map fold (flatten) ───────────────────────────────────────────
-
-/** Strongest-opinion-per-attribute merge of two prims at one path (over = stronger). */
-function foldOpinionPrim(base: UsdPrim, over: UsdPrim): UsdPrim {
-  if (base.kind !== over.kind) {
-    throw new Error(
-      `usd-layers: opinion fold conflict at ${over.path}: a ${over.kind} prim cannot ` +
-        `override a ${base.kind} prim (structural conflict, fail-closed).`,
-    );
-  }
-  if (base.kind === "aggregate" && over.kind === "aggregate") {
-    // Per-attribute: the stronger layer's field opinions win; weaker fields show
-    // through. (Coincides with the module fold's wholesale replacement exactly when
-    // the redeclaration is total — which `aggregate()` makes structural.)
-    return {
-      kind: "aggregate",
-      path: over.path,
-      type: over.type,
-      schema: sortedSchema({ ...base.schema, ...over.schema }),
-    };
-  }
-  if (base.kind === "directive" && over.kind === "directive") {
-    // Per-attribute show-through, rebuilt in the canonical prim key order so the
-    // flattened bytes match `encodeModuleToPrims` exactly.
-    const reads = over.reads ?? base.reads;
-    const emits = over.emits ?? base.emits;
-    const secondaryOutputs = over.secondaryOutputs ?? base.secondaryOutputs;
-    const payloadJsonSchema = over.payloadJsonSchema ?? base.payloadJsonSchema;
-    return {
-      kind: "directive",
-      path: over.path,
-      target: over.target,
-      marker: over.marker,
-      requires: over.requires,
-      ...(reads !== undefined ? { reads } : {}),
-      ...(emits !== undefined ? { emits } : {}),
-      ...(secondaryOutputs !== undefined ? { secondaryOutputs } : {}),
-      ...(payloadJsonSchema !== undefined ? { payloadJsonSchema } : {}),
-    };
-  }
-  throw new Error(`usd-layers: unhandled prim kind at ${over.path}.`);
-}
-
-/** Fold id-keyed layer read declarations (later layer wins per id), sorted by id. */
-function foldById<T extends { readonly id: string }>(
-  lists: readonly (readonly T[] | undefined)[],
-): T[] | undefined {
-  const byId = new Map<string, T>();
-  for (const list of lists) for (const item of list ?? []) byId.set(item.id, item);
-  if (byId.size === 0) return undefined;
-  return [...byId.keys()].sort().map((id) => byId.get(id)!);
-}
-
-function foldByKey<T>(
-  lists: readonly (readonly T[] | undefined)[],
-  keyOf: (item: T) => string,
-): T[] | undefined {
-  const byKey = new Map<string, T>();
-  for (const list of lists) for (const item of list ?? []) byKey.set(keyOf(item), item);
-  if (byKey.size === 0) return undefined;
-  return [...byKey.keys()].sort().map((key) => byKey.get(key)!);
-}
-
-function foldRecord<T>(
-  records: readonly (Readonly<Record<string, T>> | undefined)[],
-): Record<string, T> | undefined {
-  const byKey = new Map<string, T>();
-  for (const record of records) {
-    if (record === undefined) continue;
-    for (const [key, value] of Object.entries(record)) byKey.set(key, value);
-  }
-  if (byKey.size === 0) return undefined;
-  const out: Record<string, T> = {};
-  for (const key of [...byKey.keys()].sort()) out[key] = byKey.get(key)!;
-  return out;
-}
-
-function foldIdentityManifest(
-  stack: readonly UsdLayer[],
-  stableIds: UsdLayer["nomosStableIds"],
-): UsdLayer["nomosIdentityManifest"] {
-  const manifests = stack
-    .map((l) => l.nomosIdentityManifest)
-    .filter((m): m is NonNullable<UsdLayer["nomosIdentityManifest"]> => m !== undefined);
-  if (manifests.length === 0) return undefined;
-  const domain = manifests[manifests.length - 1]!.domain;
-  const workspaceInvariants = foldById(manifests.map((m) => m.workspaceInvariants));
-  const queries = foldById(manifests.map((m) => m.queries));
-  const counts = foldById(manifests.map((m) => m.counts));
-  const spatials = foldById(manifests.map((m) => m.spatials));
-  const sums = foldById(manifests.map((m) => m.sums));
-  const deriveds = foldById(manifests.map((m) => m.deriveds));
-  const combineds = foldById(manifests.map((m) => m.combineds));
-  const mins = foldById(manifests.map((m) => m.mins));
-  const maxes = foldById(manifests.map((m) => m.maxes));
-  const orderedReads = foldById(manifests.map((m) => m.orderedReads));
-  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,
-    directives: foldById(manifests.map((m) => m.directives)) ?? [],
-    ...(stableIds !== undefined ? { stableIds } : {}),
-    ...(workspaceInvariants !== undefined ? { workspaceInvariants } : {}),
-    ...(queries !== undefined ? { queries } : {}),
-    ...(counts !== undefined ? { counts } : {}),
-    ...(spatials !== undefined ? { spatials } : {}),
-    ...(sums !== undefined ? { sums } : {}),
-    ...(deriveds !== undefined ? { deriveds } : {}),
-    ...(combineds !== undefined ? { combineds } : {}),
-    ...(mins !== undefined ? { mins } : {}),
-    ...(maxes !== undefined ? { maxes } : {}),
-    ...(orderedReads !== undefined ? { orderedReads } : {}),
-    ...(workspaceTypes !== undefined ? { workspaceTypes } : {}),
-    ...(homes !== undefined ? { homes } : {}),
-    ...(routes !== undefined ? { routes } : {}),
-  };
-}
-
-function foldReadProjection(stack: readonly UsdLayer[]): UsdLayer["nomosReadProjection"] {
-  const projections = stack
-    .map((l) => l.nomosReadProjection)
-    .filter((p): p is NonNullable<UsdLayer["nomosReadProjection"]> => p !== undefined);
-  if (projections.length === 0) return undefined;
-  const aggregateFieldKinds = foldRecord(projections.map((p) => p.aggregateFieldKinds)) ?? {};
-  const sums = foldById(projections.map((p) => p.sums));
-  const mins = foldById(projections.map((p) => p.mins));
-  const maxes = foldById(projections.map((p) => p.maxes));
-  const orderedReads = foldById(projections.map((p) => p.orderedReads));
-  return {
-    aggregateFieldKinds,
-    queries: foldById(projections.map((p) => p.queries)) ?? [],
-    counts: foldById(projections.map((p) => p.counts)) ?? [],
-    spatials: foldById(projections.map((p) => p.spatials)) ?? [],
-    deriveds: foldById(projections.map((p) => p.deriveds)) ?? [],
-    combineds: foldById(projections.map((p) => p.combineds)) ?? [],
-    ...(sums !== undefined ? { sums } : {}),
-    ...(mins !== undefined ? { mins } : {}),
-    ...(maxes !== undefined ? { maxes } : {}),
-    ...(orderedReads !== undefined ? { orderedReads } : {}),
-  };
-}
-
-/**
- * THE ORDERED OPINION-MAP FOLD: flatten module layers (weak → strong within each
- * stage path) into the effective single-layer-per-domain document. Strongest
- * opinion per attribute; layer-level read declarations fold by id (later wins).
- * Output layers/prims sorted by path — the SAME canonical shape `emitUsd` emits, so
- * `JSON.stringify(flattenLayeredUsd(layers))` is directly byte-comparable with
- * `emitUsdJsonForModules([composedModule, ...])`. THAT byte-equality is the
- * homomorphism: flatten-after-lower == lower-after-compose.
- */
-export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
-  const groups = new Map<string, UsdLayer[]>();
-  for (const layer of layers) {
-    const group = groups.get(layer.path);
-    if (group === undefined) groups.set(layer.path, [layer]);
-    else group.push(layer);
-  }
-
-  const out: UsdLayer[] = [...groups.keys()].sort().map((path) => {
-    const stack = groups.get(path)!;
-    const prims = new Map<string, UsdPrim>();
-    for (const layer of stack) {
-      for (const prim of layer.prims) {
-        const existing = prims.get(prim.path);
-        prims.set(prim.path, existing === undefined ? prim : foldOpinionPrim(existing, prim));
-      }
-    }
-    const queries = foldById<UsdQuery>(stack.map((l) => l.queries));
-    const deriveds = foldById<UsdDerived>(stack.map((l) => l.deriveds));
-    const combineds = foldById<UsdCombined>(stack.map((l) => l.combineds));
-    // STABLE IDS (#58): fold per-module stableIds — domain sid from the latest
-    // declaring layer (they coincide by construction: one domain, one mint scope),
-    // aggregates merged later-wins per CURRENT name, SORTED keys (byte-determinism
-    // against the composed emission's sorted-aggregate insertion order).
-    let stableIds: UsdLayer["nomosStableIds"];
-    {
-      const aggs = new Map<string, NonNullable<UsdLayer["nomosStableIds"]>["aggregates"][string]>();
-      let domainSid: string | undefined;
-      for (const l of stack) {
-        if (l.nomosStableIds === undefined) continue;
-        domainSid = l.nomosStableIds.domain;
-        for (const [name, a] of Object.entries(l.nomosStableIds.aggregates)) aggs.set(name, a);
-      }
-      if (domainSid !== undefined) {
-        const aggregates: NonNullable<UsdLayer["nomosStableIds"]>["aggregates"] = {};
-        for (const k of [...aggs.keys()].sort()) aggregates[k] = aggs.get(k)!;
-        stableIds = { v: 1, domain: domainSid, aggregates };
-      }
-    }
-    // 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) {
-        if (l.nomosInterface === undefined) continue;
-        domainI = l.nomosInterface.domain;
-        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 } : {}),
-        };
-      }
-    }
-    const identityManifest = foldIdentityManifest(stack, stableIds);
-    const readProjection = foldReadProjection(stack);
-    // The captured-read gate (#58): queries + per-directive read sets merged
-    // later-wins, SORTED keys (matching the composed emission).
-    let readGate: UsdLayer["nomosReadGate"];
-    {
-      const q = new Map<string, { key: string[]; returns: string }>();
-      const d = new Map<string, string[]>();
-      for (const l of stack) {
-        if (l.nomosReadGate === undefined) continue;
-        for (const [id, spec] of Object.entries(l.nomosReadGate.queries)) q.set(id, spec);
-        for (const [id, reads] of Object.entries(l.nomosReadGate.directives)) d.set(id, reads);
-      }
-      if (d.size > 0) {
-        const queriesRec: Record<string, { key: string[]; returns: string }> = {};
-        for (const k of [...q.keys()].sort()) queriesRec[k] = q.get(k)!;
-        const directivesRec: Record<string, string[]> = {};
-        for (const k of [...d.keys()].sort()) directivesRec[k] = d.get(k)!;
-        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"];
-    {
-      const a = new Map<string, { requires: string }>();
-      for (const l of stack) {
-        if (l.nomosReadVisibility === undefined) continue;
-        for (const [type, spec] of Object.entries(l.nomosReadVisibility.aggregates)) a.set(type, spec);
-      }
-      if (a.size > 0) {
-        const aggregatesRec: Record<string, { requires: string }> = {};
-        for (const k of [...a.keys()].sort()) aggregatesRec[k] = a.get(k)!;
-        readVisibility = { v: 1, aggregates: aggregatesRec };
-      }
-    }
-    // The encryption gate (slice 2): per-aggregate encrypted-field sets merged later-wins,
-    // SORTED keys (matching the composed emission). Omit-when-empty.
-    let encryption: UsdLayer["nomosEncryption"];
-    {
-      const a = new Map<string, { scope: string; fields: string[]; delegatable: false }>();
-      for (const l of stack) {
-        if (l.nomosEncryption === undefined) continue;
-        for (const [type, spec] of Object.entries(l.nomosEncryption.aggregates)) a.set(type, spec);
-      }
-      if (a.size > 0) {
-        const aggregatesRec: Record<string, { scope: string; fields: string[]; delegatable: false }> = {};
-        for (const k of [...a.keys()].sort()) aggregatesRec[k] = a.get(k)!;
-        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"];
-    {
-      const a = new Map<string, string[]>();
-      for (const l of stack) {
-        if (l.nomosAttributedGate === undefined) continue;
-        for (const [type, fields] of Object.entries(l.nomosAttributedGate.aggregates)) a.set(type, fields);
-      }
-      if (a.size > 0) {
-        const aggregatesRec: Record<string, string[]> = {};
-        for (const k of [...a.keys()].sort()) aggregatesRec[k] = a.get(k)!;
-        attributedGate = { v: 1, aggregates: aggregatesRec };
-      }
-    }
-    // THE RELATION SCHEMA (P1): per-type relation defs merged later-wins across the stack,
-    // SORTED keys (matching the composed emission). Omit-when-empty (the nomosRelations era rule).
-    let relations: UsdLayer["nomosRelations"];
-    {
-      const t = new Map<string, NonNullable<UsdLayer["nomosRelations"]>["types"][string]>();
-      for (const l of stack) {
-        if (l.nomosRelations === undefined) continue;
-        for (const [type, spec] of Object.entries(l.nomosRelations.types)) {
-          // RELATION-NAMESPACING SAFETY: after qualification, two domains' same bare type key under
-          // DISTINCT ids (`estate__workspace` vs `home__workspace`) and never reach here as the same key.
-          // A collision on the SAME canonical id can now only be a genuinely SHARED id (two layers
-          // contributing the same global type, or a future cross-domain shared type). Silent last-wins
-          // would DROP one layer's relations — so a collision on a key whose spec DIFFERS is a HARD ERROR
-          // (loud, not last-wins). An identical re-contribution (framework dedup) is fine.
-          const prior = t.get(type);
-          if (prior !== undefined && JSON.stringify(prior) !== JSON.stringify(spec)) {
-            throw new Error(
-              `nomosRelations: relation type "${type}" is contributed with DIFFERING definitions by two ` +
-                `layers — the qualified ids collide. A shared relation type must be identical across ` +
-                `domains (or namespaced per-domain). Refusing to silently last-wins.`,
-            );
-          }
-          t.set(type, spec);
-        }
-      }
-      if (t.size > 0) {
-        const typesRec: NonNullable<UsdLayer["nomosRelations"]>["types"] = {};
-        for (const k of [...t.keys()].sort()) typesRec[k] = t.get(k)!;
-        relations = { v: 1, types: typesRec };
-      }
-    }
-    // THE RELATION-NAMESPACE ERA KEY (relation-namespacing): the SORTED union of every layer's qualified
-    // type ids. Present iff ANY layer namespaced ≥1 type; omit-when-empty (byte-identical for global-only
-    // / relation-free packages). `delimiter` is the ratified colon-free `"__"`.
-    let relationNamespace: UsdLayer["nomosRelationNamespace"];
-    {
-      const ns = new Set<string>();
-      for (const l of stack) {
-        if (l.nomosRelationNamespace === undefined) continue;
-        for (const id of l.nomosRelationNamespace.types) ns.add(id);
-      }
-      if (ns.size > 0) relationNamespace = { v: 1, delimiter: "__", types: [...ns].sort() };
-    }
-    // THE READ-PROJECTION NAMESPACE ERA KEY (read-projection namespacing): the SORTED union of every
-    // layer's qualified aggregate type names. Present iff ANY layer namespaced >=1 aggregate;
-    // omit-when-empty (byte-identical for global-only packages). Delimiter is the ratified "__".
-    let readProjectionNamespace: UsdLayer["nomosReadProjectionNamespace"];
-    {
-      const ns = new Set<string>();
-      for (const l of stack) {
-        if (l.nomosReadProjectionNamespace === undefined) continue;
-        for (const id of l.nomosReadProjectionNamespace.types) ns.add(id);
-      }
-      if (ns.size > 0) readProjectionNamespace = { v: 1, delimiter: READ_PROJECTION_DELIMITER, types: [...ns].sort() };
-    }
-    // THE RELATION GATE (P4): directiveId → {relation, object} merged later-wins, SORTED. Omit-when-empty.
-    let relationGate: UsdLayer["nomosRelationGate"];
-    {
-      const r = new Map<string, { relation: string; object: string }>();
-      for (const l of stack) {
-        if (l.nomosRelationGate === undefined) continue;
-        for (const [dir, spec] of Object.entries(l.nomosRelationGate.requires)) r.set(dir, spec);
-      }
-      if (r.size > 0) {
-        const requiresRec: Record<string, { relation: string; object: string }> = {};
-        for (const k of [...r.keys()].sort()) requiresRec[k] = r.get(k)!;
-        relationGate = { v: 1, requires: requiresRec };
-      }
-    }
-    // THE ATTESTATION GATE (home_holons §3/§5): directiveId → owner-source merged later-wins across layers,
-    // SORTED keys. Omit-when-empty (era rule).
-    let attestationGate: UsdLayer["nomosAttestationGate"];
-    {
-      type AttSrc = NonNullable<UsdLayer["nomosAttestationGate"]>["directives"][string];
-      const a = new Map<string, AttSrc>();
-      for (const l of stack) {
-        if (l.nomosAttestationGate === undefined) continue;
-        for (const [id, src] of Object.entries(l.nomosAttestationGate.directives)) a.set(id, src);
-      }
-      if (a.size > 0) {
-        const rec: Record<string, AttSrc> = {};
-        for (const k of [...a.keys()].sort()) rec[k] = a.get(k)!;
-        attestationGate = { v: 1, directives: rec };
-      }
-    }
-    // THE DELEGATED-AUTHORITY GATE (delegated_authority_births.md): directiveId → delegation spec merged
-    // later-wins across layers, SORTED keys. Omit-when-empty (era rule).
-    let delegationGate: UsdLayer["nomosDelegationGate"];
-    {
-      type DelSrc = NonNullable<UsdLayer["nomosDelegationGate"]>["directives"][string];
-      const a = new Map<string, DelSrc>();
-      for (const l of stack) {
-        if (l.nomosDelegationGate === undefined) continue;
-        for (const [id, src] of Object.entries(l.nomosDelegationGate.directives)) a.set(id, src);
-      }
-      if (a.size > 0) {
-        const rec: Record<string, DelSrc> = {};
-        for (const k of [...a.keys()].sort()) rec[k] = a.get(k)!;
-        delegationGate = { v: 1, directives: rec };
-      }
-    }
-    // THE ATTESTED-READ GATE (slice B): sources + per-directive edges merged later-wins across
-    // layers, SORTED keys (matching the composed emission). Omit-when-empty (era rule).
-    let attestedReadGate: UsdLayer["nomosAttestedReadGate"];
-    {
-      type Gate = NonNullable<UsdLayer["nomosAttestedReadGate"]>;
-      type SrcSpec = Gate["sources"][string];
-      type PolSpec = NonNullable<Gate["policies"]>[string];
-      type EdgeList = Gate["directives"][string];
-      const srcs = new Map<string, SrcSpec>();
-      const pols = new Map<string, PolSpec>();
-      const dirs = new Map<string, EdgeList>();
-      for (const l of stack) {
-        if (l.nomosAttestedReadGate === undefined) continue;
-        for (const [ws, spec] of Object.entries(l.nomosAttestedReadGate.sources)) srcs.set(ws, spec);
-        for (const [id, spec] of Object.entries(l.nomosAttestedReadGate.policies ?? {})) pols.set(id, spec);
-        for (const [id, edges] of Object.entries(l.nomosAttestedReadGate.directives)) dirs.set(id, edges);
-      }
-      if (dirs.size > 0) {
-        const sourcesRec: Record<string, SrcSpec> = {};
-        for (const k of [...srcs.keys()].sort()) sourcesRec[k] = srcs.get(k)!;
-        const policiesRec: Record<string, PolSpec> = {};
-        for (const k of [...pols.keys()].sort()) policiesRec[k] = pols.get(k)!;
-        const directivesRec: Record<string, EdgeList> = {};
-        for (const k of [...dirs.keys()].sort()) directivesRec[k] = dirs.get(k)!;
-        attestedReadGate = {
-          v: 1,
-          sources: sourcesRec,
-          ...(Object.keys(policiesRec).length > 0 ? { policies: policiesRec } : {}),
-          directives: directivesRec,
-        };
-      }
-    }
-    // THE BIRTH GATE (G3): the SORTED union of every layer's `.births()` directive ids. Omit-when-empty
-    // (era rule). The set is the contract; order is incidental (sorted for byte-determinism).
-    let birthGate: UsdLayer["nomosBirthGate"];
-    {
-      const b = new Set<string>();
-      for (const l of stack) {
-        if (l.nomosBirthGate === undefined) continue;
-        for (const id of l.nomosBirthGate.directives) b.add(id);
-      }
-      if (b.size > 0) birthGate = { v: 1, directives: [...b].sort() };
-    }
-    // THE BIRTH-RECORD GATE (metered birth, A1): present iff ANY layer declares it (once declared,
-    // declared). Carry the FIRST layer's aggregate/prefix verbatim (the framework constants — do NOT
-    // reconstruct). Omit-when-absent (era rule).
-    let birthRecordGate: UsdLayer["nomosBirthRecordGate"];
-    for (const l of stack) {
-      if (l.nomosBirthRecordGate !== undefined) {
-        birthRecordGate = l.nomosBirthRecordGate;
-        break;
-      }
-    }
-    // THE PEER-SOVEREIGN ROOT-OF-TRUST: the era key is present iff ANY layer declares it (once required,
-    // required). Carry the FIRST layer's declared owner/cert locators verbatim (preserve them — do NOT
-    // reconstruct {v:1}, which would drop the locators the kernel reads). Omit-when-absent (era rule).
-    let parentAttestedBirth: UsdLayer["nomosParentAttestedBirth"];
-    for (const l of stack) {
-      if (l.nomosParentAttestedBirth !== undefined) {
-        parentAttestedBirth = l.nomosParentAttestedBirth;
-        break;
-      }
-    }
-    // THE KEYLESS VERIFIED-FIRST-DEVICE GATE: directiveId → payload field mapping, merged later-wins across
-    // layers, SORTED keys (mirrors the attestation gate). Omit-when-empty (era rule).
-    let verifiedFirstEnroll: UsdLayer["nomosVerifiedFirstEnroll"];
-    {
-      type VfeSrc = NonNullable<UsdLayer["nomosVerifiedFirstEnroll"]>["directives"][string];
-      const v = new Map<string, VfeSrc>();
-      for (const l of stack) {
-        if (l.nomosVerifiedFirstEnroll === undefined) continue;
-        for (const [id, src] of Object.entries(l.nomosVerifiedFirstEnroll.directives)) v.set(id, src);
-      }
-      if (v.size > 0) {
-        const rec: Record<string, VfeSrc> = {};
-        for (const k of [...v.keys()].sort()) rec[k] = v.get(k)!;
-        verifiedFirstEnroll = { v: 1, directives: rec };
-      }
-    }
-    // LAWFUL RECOVERY: the single `nomosEraCertGate` (later-wins across the stack — one certifyEra verb).
-    let eraCertGate: UsdLayer["nomosEraCertGate"];
-    for (const l of stack) {
-      if (l.nomosEraCertGate !== undefined) eraCertGate = l.nomosEraCertGate;
-    }
-    // FIRST-CLASS VALUE OBJECTS (+ the VO↔field usage pointers): descriptors merged
-    // later-wins per NAME, usages later-wins per (aggregate, field), both SORTED —
-    // so the layered fold stays byte-homomorphic with `emitUsd`'s composed emission.
-    // Omit-when-empty (the era rule); `usages` omitted when none (0.33.0 tolerance).
-    let valueObjects: UsdLayer["nomosValueObjects"];
-    {
-      type VoDesc = NonNullable<UsdLayer["nomosValueObjects"]>["valueObjects"][number];
-      type VoUse = NonNullable<NonNullable<UsdLayer["nomosValueObjects"]>["usages"]>[number];
-      const byName = new Map<string, VoDesc>();
-      const byField = new Map<string, VoUse>();
-      for (const l of stack) {
-        if (l.nomosValueObjects === undefined) continue;
-        for (const d of l.nomosValueObjects.valueObjects) byName.set(d.name, d);
-        for (const u of l.nomosValueObjects.usages ?? []) byField.set(`${u.aggregate}\u0000${u.field}`, u);
-      }
-      if (byName.size > 0) {
-        const descs = [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-        const uses = [...byField.values()].sort((a, b) =>
-          a.aggregate !== b.aggregate ? (a.aggregate < b.aggregate ? -1 : 1) : a.field < b.field ? -1 : a.field > b.field ? 1 : 0,
-        );
-        valueObjects = { v: 1, valueObjects: descs, ...(uses.length > 0 ? { usages: uses } : {}) };
-      }
-    }
-        let foreignRefs: UsdLayer["nomosForeignRefs"];
-    for (const l of stack) { if (l.nomosForeignRefs !== undefined) foreignRefs = l.nomosForeignRefs; }
-    // DOMAIN CONTRACTS: union the per-layer contract descriptors by id (later-wins on the shape),
-    // sorted by id — byte-identical to the composed emit (which sorts contracts by id). implementedBy
-    // is unioned across layers so a contract declared in one module and implemented in a same-layer
-    // aggregate stays intact. Omit-when-empty.
-    let contracts: UsdLayer["nomosContracts"];
-    {
-      type C = NonNullable<UsdLayer["nomosContracts"]>["contracts"][number];
-      const byId = new Map<string, C>();
-      const implById = new Map<string, Set<string>>();
-      for (const l of stack) {
-        if (l.nomosContracts === undefined) continue;
-        for (const c of l.nomosContracts.contracts) {
-          byId.set(c.id, c);
-          const s = implById.get(c.id) ?? new Set<string>();
-          for (const a of c.implementedBy) s.add(a);
-          implById.set(c.id, s);
-        }
-      }
-      if (byId.size > 0) {
-        contracts = {
-          v: 1,
-          contracts: [...byId.keys()].sort().map((id) => ({
-            ...byId.get(id)!,
-            implementedBy: [...(implById.get(id) ?? [])].sort(),
-          })),
-        };
-      }
-    }
-    // THE FLOW GATE: a stronger directive replaces the weaker declaration wholesale, so its
-    // harvested endorsement flows must do the same (including replacing them with none). Other
-    // flow rows union by their stable site. Both halves retain emitUsd's canonical sort order.
-    let flowGate: UsdLayer["nomosFlowGate"];
-    {
-      type Endorse = NonNullable<NonNullable<UsdLayer["nomosFlowGate"]>["endorse"]>[number];
-      type Declassify = NonNullable<NonNullable<UsdLayer["nomosFlowGate"]>["declassify"]>[number];
-      const endorseByDirective = new Map<string, Endorse[]>();
-      const declassifyBySite = new Map<string, Declassify>();
-      for (const layer of stack) {
-        const touchedDirectives = new Set(
-          layer.nomosIdentityManifest?.directives.map((directive) => directive.id) ?? [],
-        );
-        for (const directiveId of touchedDirectives) endorseByDirective.delete(directiveId);
-        for (const row of layer.nomosFlowGate?.endorse ?? []) {
-          const rows = endorseByDirective.get(row.directiveId) ?? [];
-          rows.push(row);
-          endorseByDirective.set(row.directiveId, rows);
-        }
-        for (const row of layer.nomosFlowGate?.declassify ?? []) declassifyBySite.set(row.site, row);
-      }
-      const declassify = [...declassifyBySite.values()].sort((a, b) =>
-        a.site < b.site ? -1 : a.site > b.site ? 1 : 0,
-      );
-      const endorse = [...endorseByDirective.values()].flat().sort((a, b) =>
-        a.directiveId !== b.directiveId ? (a.directiveId < b.directiveId ? -1 : 1)
-          : a.sink !== b.sink ? (a.sink < b.sink ? -1 : 1)
-            : a.facet < b.facet ? -1 : a.facet > b.facet ? 1 : 0,
-      );
-      if (declassify.length > 0 || endorse.length > 0) {
-        flowGate = {
-          v: 1,
-          ...(declassify.length > 0 ? { declassify } : {}),
-          ...(endorse.length > 0 ? { endorse } : {}),
-        };
-      }
-    }
-    return {
-      path,
-      prims: [...prims.keys()].sort().map((p) => prims.get(p)!),
-      ...(identityManifest !== undefined ? { nomosIdentityManifest: identityManifest } : {}),
-      ...(readProjection !== undefined ? { nomosReadProjection: readProjection } : {}),
-      ...(queries !== undefined ? { queries } : {}),
-      ...(deriveds !== undefined ? { deriveds } : {}),
-      ...(combineds !== undefined ? { combineds } : {}),
-      ...(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 } : {}),
-      ...(readProjectionNamespace !== undefined ? { nomosReadProjectionNamespace: readProjectionNamespace } : {}),
-      ...(relationGate !== undefined ? { nomosRelationGate: relationGate } : {}),
-      ...(attestationGate !== undefined ? { nomosAttestationGate: attestationGate } : {}),
-      ...(delegationGate !== undefined ? { nomosDelegationGate: delegationGate } : {}),
-      ...(attestedReadGate !== undefined ? { nomosAttestedReadGate: attestedReadGate } : {}),
-      ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),
-      ...(birthRecordGate !== undefined ? { nomosBirthRecordGate: birthRecordGate } : {}),
-      ...(parentAttestedBirth !== undefined ? { nomosParentAttestedBirth: parentAttestedBirth } : {}),
-      ...(verifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll: verifiedFirstEnroll } : {}),
-      ...(eraCertGate !== undefined ? { nomosEraCertGate: eraCertGate } : {}),
-      ...(valueObjects !== undefined ? { nomosValueObjects: valueObjects } : {}),
-      ...(foreignRefs !== undefined ? { nomosForeignRefs: foreignRefs } : {}),
-      ...(contracts !== undefined ? { nomosContracts: contracts } : {}),
-      ...(flowGate !== undefined ? { nomosFlowGate: flowGate } : {}),
-    };
-  });
-
-  // Apply the SAME cross-layer shared-relation composition + guard the composed emission
-  // (`usd.ts::emitUsd`) applies, so the layered fold stays byte-homomorphic with it (a divergent
-  // shared global type refuses identically on both paths).
-  return { layers: composeSharedRelationTypes(out) };
-}
-
-// ── usda → IR (the round-trip parser for the pxr/usdcat conformance lane) ──────────
-
-interface ParsedPrim {
-  /** Sanitized prim path, e.g. `/Nomos/guestbook/GuestbookEntry`. */
-  readonly path: 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 {
-  try {
-    return JSON.parse(`"${s}"`) as string;
-  } catch {
-    throw new Error("usd-layers: invalid escaped USDA string");
-  }
-}
-
-function parseStringArrayItems(inner: string): string[] {
-  const items: string[] = [];
-  const re = /"((?:[^"\\]|\\.)*)"/g;
-  let m: RegExpExecArray | null;
-  while ((m = re.exec(inner)) !== null) items.push(unescapeUsda(m[1]!));
-  return items;
-}
-
-/**
- * A deliberately SMALL usda reader for the documents THIS module emits (and their
- * usdcat-flattened images): prim tree + `custom string` / `custom string[]`
- * attributes. Relationships and unknown lines are ignored (decoration). Not a
- * general USD parser — the conformance lane's inverse image, nothing more.
- */
-function parseUsdaPrims(text: string): ParsedPrim[] {
-  const prims: ParsedPrim[] = [];
-  const stack: ParsedPrim[] = [];
-  let pending: string | undefined;
-  let inLayerMeta = false;
-
-  for (const raw of text.split("\n")) {
-    const line = raw.trim();
-    if (stack.length === 0 && pending === undefined) {
-      if (line === "(") {
-        inLayerMeta = true;
-        continue;
-      }
-      if (inLayerMeta) {
-        if (line === ")") inLayerMeta = false;
-        continue;
-      }
-    }
-    const header = PRIM_HEADER.exec(line);
-    if (header !== null) {
-      pending = header[1]!;
-      // Same-line `{` (not emitted here, but tolerated).
-      if (!line.endsWith("{")) continue;
-    }
-    if (line === "{" || (header !== null && line.endsWith("{"))) {
-      const parentPath = stack.length > 0 ? stack[stack.length - 1]!.path : "";
-      const prim: ParsedPrim = {
-        path: `${parentPath}/${pending ?? "?"}`,
-        attrs: new Map(),
-      };
-      pending = undefined;
-      stack.push(prim);
-      prims.push(prim);
-      continue;
-    }
-    if (line === "}") {
-      stack.pop();
-      continue;
-    }
-    if (stack.length === 0) continue;
-    const top = stack[stack.length - 1]!;
-    const arr = ATTR_STRING_ARRAY.exec(line);
-    if (arr !== null) {
-      top.attrs.set(arr[1]!, parseStringArrayItems(arr[2]!));
-      continue;
-    }
-    const str = ATTR_STRING.exec(line);
-    if (str !== null) {
-      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") {
-    throw new Error(`usd-layers: prim ${prim.path} is missing string attribute ${name}`);
-  }
-  return v;
-}
-
-function attrStringArray(prim: ParsedPrim, name: string): string[] {
-  const v = prim.attrs.get(name);
-  if (!Array.isArray(v)) {
-    throw new Error(`usd-layers: prim ${prim.path} is missing string[] attribute ${name}`);
-  }
-  return v;
-}
-
-/**
- * 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 canonicalJson comparison with
- * `emitUsd` / `flattenLayeredUsd` compares law rather than USD formatting).
- */
-export function parseUsdaDocument(text: string): UsdDocument {
-  const prims = parseUsdaPrims(text);
-  const domainByScope = new Map<string, string>();
-  const identityManifestByDomain = new Map<string, UsdLayer["nomosIdentityManifest"]>();
-  const readProjectionByDomain = new Map<string, UsdLayer["nomosReadProjection"]>();
-  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"]>();
-  const relationNamespaceByDomain = new Map<string, UsdLayer["nomosRelationNamespace"]>();
-  const readProjectionNamespaceByDomain = new Map<string, UsdLayer["nomosReadProjectionNamespace"]>();
-  const attestationGateByDomain = new Map<string, UsdLayer["nomosAttestationGate"]>();
-  const delegationGateByDomain = new Map<string, UsdLayer["nomosDelegationGate"]>();
-  const attestedReadGateByDomain = new Map<string, UsdLayer["nomosAttestedReadGate"]>();
-  const birthGateByDomain = new Map<string, UsdLayer["nomosBirthGate"]>();
-  const birthRecordGateByDomain = new Map<string, UsdLayer["nomosBirthRecordGate"]>();
-  const parentAttestedBirthByDomain = new Map<string, UsdLayer["nomosParentAttestedBirth"]>();
-  const verifiedFirstEnrollByDomain = new Map<string, UsdLayer["nomosVerifiedFirstEnroll"]>();
-  const eraCertGateByDomain = new Map<string, UsdLayer["nomosEraCertGate"]>();
-  const valueObjectsByDomain = new Map<string, UsdLayer["nomosValueObjects"]>();
-  const foreignRefsByDomain = new Map<string, UsdLayer["nomosForeignRefs"]>();
-  const contractsByDomain = new Map<string, UsdLayer["nomosContracts"]>();
-  const flowGateByDomain = new Map<string, UsdLayer["nomosFlowGate"]>();
-  for (const p of prims) {
-    if (p.attrs.get("nomos:kind") === "domain") {
-      const domain = attrString(p, "nomos:domain");
-      domainByScope.set(p.path, domain);
-      // 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);
-    }
-  }
-
-  interface Bucket {
-    prims: UsdPrim[];
-    queries: UsdQuery[];
-    deriveds: UsdDerived[];
-    combineds: UsdCombined[];
-  }
-  const buckets = new Map<string, Bucket>();
-  const bucketFor = (domain: string): Bucket => {
-    let b = buckets.get(domain);
-    if (b === undefined) {
-      b = { prims: [], queries: [], deriveds: [], combineds: [] };
-      buckets.set(domain, b);
-    }
-    return b;
-  };
-
-  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) {
-      throw new Error(`usd-layers: prim ${p.path} has no enclosing nomos domain scope`);
-    }
-    const b = bucketFor(domain);
-    const id = attrString(p, "nomos:id");
-    const irPath = `/Nomos/${domain}/${id}`;
-
-    if (kind === "aggregate") {
-      const schema: WireSchema = {};
-      for (const [name, value] of p.attrs) {
-        if (name.startsWith("nomos:driver:") && typeof value === "string") {
-          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 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,
-        target: attrString(p, "nomos:target"),
-        marker: attrString(p, "nomos:marker") as WireRefMode,
-        requires: attrStringArray(p, "nomos:requires"),
-        ...(reads !== undefined ? { reads } : {}),
-        ...(emits !== undefined ? { emits } : {}),
-        ...(secondaryOutputs !== undefined ? { secondaryOutputs } : {}),
-        ...(payloadJsonSchema !== undefined ? { payloadJsonSchema } : {}),
-      });
-    } else if (kind === "query") {
-      b.queries.push({
-        id,
-        key: attrStringArray(p, "nomos:key"),
-        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: 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: nativeReturns as UsdCombined["returns"],
-      });
-    } else {
-      throw new Error(`usd-layers: prim ${p.path} has unknown nomos:kind '${kind}'`);
-    }
-  }
-
-  const byId = <T extends { id: string }>(a: T, b: T) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
-  const byPath = (a: UsdPrim, b: UsdPrim) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
-  const layers: UsdLayer[] = [...buckets.keys()]
-    .map((domain) => {
-      const b = buckets.get(domain)!;
-      const identity = identityManifestByDomain.get(domain);
-      const readProjection = readProjectionByDomain.get(domain);
-      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);
-      const relNs = relationNamespaceByDomain.get(domain);
-      const rpNs = readProjectionNamespaceByDomain.get(domain);
-      const attGate = attestationGateByDomain.get(domain);
-      const delGate = delegationGateByDomain.get(domain);
-      const attReadGate = attestedReadGateByDomain.get(domain);
-      const birthGate = birthGateByDomain.get(domain);
-      const birthRecordGate = birthRecordGateByDomain.get(domain);
-      const parentAttestedBirth = parentAttestedBirthByDomain.get(domain);
-      const verifiedFirstEnroll = verifiedFirstEnrollByDomain.get(domain);
-      const eraCertGate = eraCertGateByDomain.get(domain);
-      const valueObjects = valueObjectsByDomain.get(domain);
-      const foreignRefs2 = foreignRefsByDomain.get(domain);
-      const contracts2 = contractsByDomain.get(domain);
-      const flowGate2 = flowGateByDomain.get(domain);
-      return {
-        path: `/Nomos/${domain}`,
-        prims: [...b.prims].sort(byPath),
-        ...(identity !== undefined ? { nomosIdentityManifest: identity } : {}),
-        ...(readProjection !== undefined ? { nomosReadProjection: readProjection } : {}),
-        ...(b.queries.length > 0 ? { queries: [...b.queries].sort(byId) } : {}),
-        ...(b.deriveds.length > 0 ? { deriveds: [...b.deriveds].sort(byId) } : {}),
-        ...(b.combineds.length > 0 ? { combineds: [...b.combineds].sort(byId) } : {}),
-        ...(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 } : {}),
-        ...(rpNs !== undefined ? { nomosReadProjectionNamespace: rpNs } : {}),
-        ...(relGate !== undefined ? { nomosRelationGate: relGate } : {}),
-        ...(attGate !== undefined ? { nomosAttestationGate: attGate } : {}),
-        ...(delGate !== undefined ? { nomosDelegationGate: delGate } : {}),
-        ...(attReadGate !== undefined ? { nomosAttestedReadGate: attReadGate } : {}),
-        ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),
-        ...(birthRecordGate !== undefined ? { nomosBirthRecordGate: birthRecordGate } : {}),
-        ...(parentAttestedBirth !== undefined ? { nomosParentAttestedBirth: parentAttestedBirth } : {}),
-        ...(verifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll: verifiedFirstEnroll } : {}),
-        ...(eraCertGate !== undefined ? { nomosEraCertGate: eraCertGate } : {}),
-        ...(valueObjects !== undefined ? { nomosValueObjects: valueObjects } : {}),
-      ...(foreignRefs2 !== undefined ? { nomosForeignRefs: foreignRefs2 } : {}),
-      ...(contracts2 !== undefined ? { nomosContracts: contracts2 } : {}),
-      ...(flowGate2 !== undefined ? { nomosFlowGate: flowGate2 } : {}),
-      };
-    })
-    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
-  return { layers };
-}
-
-// ── the honest TS-rendered tree (usdcat-equivalent visual) ──────────────────────────
-
-/**
- * The usdcat-equivalent prim tree as plain text — the visual proof for environments
- * without USD tooling (and the muted-layer diff's render). Honest about what it is:
- * a rendering of the IR document, not a pxr traversal.
- */
-export function renderUsdTree(doc: UsdDocument): string {
-  const lines: string[] = [];
-  for (const layer of doc.layers) {
-    lines.push(layer.path);
-    for (const prim of layer.prims) {
-      const name = prim.path.slice(prim.path.lastIndexOf("/") + 1);
-      if (prim.kind === "aggregate") {
-        lines.push(`  ${name}  [aggregate]`);
-        for (const [field, driver] of Object.entries(prim.schema)) {
-          lines.push(`    .${field} : ${driverToken(driver)}`);
-        }
-      } else {
-        const reads = prim.reads !== undefined ? `  reads [${prim.reads.join(", ")}]` : "";
-        lines.push(
-          `  ${name}  [directive]  ${prim.marker} -> ${prim.target}  requires [${prim.requires.join(", ")}]${reads}`,
-        );
-      }
-    }
-    for (const q of layer.queries ?? []) {
-      lines.push(`  ${q.id}  [query]  key (${q.key.join(", ")}) -> ${q.returns}`);
-    }
-    for (const d of layer.deriveds ?? []) {
-      lines.push(`  ${d.id}  [derived]  of ${d.of} -> ${d.returns.type}${d.returns.nullable ? "?" : ""}`);
-    }
-    for (const c of layer.combineds ?? []) {
-      lines.push(
-        `  ${c.id}  [combined]  of ${c.of} via .${c.refField} reads ${c.reads} -> ${c.returns.type}${c.returns.nullable ? "?" : ""}`,
-      );
-    }
-  }
-  return lines.join("\n") + "\n";
-}