@githolon/dsl 0.2.1 → 0.2.2

package/src/usd_layers.ts

@@ -0,0 +1,722 @@
+// 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 BYTE-EQUALITY:
+ *
+ *       JSON.stringify(flattenLayeredUsd(layers)) === emitUsdJsonForModules([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).
+ *
+ * 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 byte-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. Layered emission is therefore OPT-IN and additive: the
+ * flattened `.package.usda` emission and its hash do not move by one byte.
+ *
+ * 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 hex): reached via `@githolon/dsl/usd-layers`, never
+ * the runtime barrel.
+ */
+import type { AggregateHandle } from "./aggregate.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";
+
+/** 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";
+
+// ── 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, '\\"')}"`;
+}
+
+/** 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"`, …); `MapOf` nests as `MapOf(<inner>)`. Readable on
+ * purpose — the usdcat/usdview tree is the visual proof, so the merge law 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;
+  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 (!/^[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}`;
+}
+
+/** 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;
+}
+
+// ── 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[],
+): EmittedModuleLayer[] {
+  if (modules.length === 0) {
+    throw new Error(`usd-layers: domain '${domain}' has no modules to layer`);
+  }
+  const out: EmittedModuleLayer[] = [];
+  const seenPaths = new Set<string>();
+  for (const m of modules) {
+    const doc = emitUsd([{ path: `/Nomos/${domain}`, module: m.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, m.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. Nested JSON (payload schema / emits / returns)
+ * rides hex-encoded so the round-trip is byte-faithful. 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,
+  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:${field} = ${usdaString(driverToken(driver))}`);
+      }
+      body.push(...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(
+          `${ind3}custom string nomos:emitsHex = ${usdaString(hexUtf8(JSON.stringify(prim.emits)))}`,
+        );
+      }
+      if (prim.payloadJsonSchema !== undefined) {
+        body.push(
+          `${ind3}custom string nomos:payloadJsonSchemaHex = ${usdaString(
+            hexUtf8(JSON.stringify(prim.payloadJsonSchema)),
+          )}`,
+        );
+      }
+    }
+    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)}`,
+      `${ind3}custom string nomos:returnsHex = ${usdaString(hexUtf8(JSON.stringify(d.returns)))}`,
+      `${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)}`,
+      `${ind3}custom string nomos:returnsHex = ${usdaString(hexUtf8(JSON.stringify(c.returns)))}`,
+      `${ind2}}`,
+      ``,
+    );
+  }
+  // Drop the trailing blank line inside the scope.
+  if (body[body.length - 1] === "") body.pop();
+
+  return [
+    `#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))}`,
+    `    {`,
+    `        custom string nomos:kind = "domain"`,
+    `        custom string nomos:domain = ${usdaString(domain)}`,
+    ``,
+    ...body,
+    `    }`,
+    `}`,
+    ``,
+  ].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[]): string {
+  const strongestFirst = [...sublayerRelPathsWeakToStrong].reverse();
+  return [
+    `#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.map(
+      (p, i) => `        @${p}@${i < strongestFirst.length - 1 ? "," : ""}`,
+    ),
+    `    ]`,
+    `)`,
+    ``,
+  ].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 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 } : {}),
+      ...(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)!);
+}
+
+/**
+ * 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));
+    return {
+      path,
+      prims: [...prims.keys()].sort().map((p) => prims.get(p)!),
+      ...(queries !== undefined ? { queries } : {}),
+      ...(deriveds !== undefined ? { deriveds } : {}),
+      ...(combineds !== undefined ? { combineds } : {}),
+    };
+  });
+
+  return { layers: 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[]>;
+}
+
+const ATTR_STRING = /^custom\s+string\s+([\w:]+)\s*=\s*"((?:[^"\\]|\\.)*)"$/;
+const ATTR_STRING_ARRAY = /^custom\s+string\[\]\s+([\w:]+)\s*=\s*\[(.*)\]$/;
+const PRIM_HEADER = /^(?:def|over|class)(?:\s+\w+)?\s+"([^"]+)"/;
+
+function unescapeUsda(s: string): string {
+  return s.replace(/\\(.)/g, "$1");
+}
+
+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;
+    }
+  }
+  return prims;
+}
+
+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 the result is directly comparable —
+ * `JSON.stringify`-byte-comparable — with `emitUsd` / `flattenLayeredUsd` output).
+ */
+export function parseUsdaDocument(text: string): UsdDocument {
+  const prims = parseUsdaPrims(text);
+  const domainByScope = new Map<string, string>();
+  for (const p of prims) {
+    if (p.attrs.get("nomos:kind") === "domain") {
+      domainByScope.set(p.path, attrString(p, "nomos:domain"));
+    }
+  }
+
+  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;
+    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[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 payloadJsonSchema = p.attrs.has("nomos:payloadJsonSchemaHex")
+        ? (JSON.parse(unhexUtf8(attrString(p, "nomos:payloadJsonSchemaHex"))) as unknown)
+        : undefined;
+      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 } : {}),
+        ...(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") {
+      b.deriveds.push({
+        id,
+        of: attrString(p, "nomos:of"),
+        returns: JSON.parse(unhexUtf8(attrString(p, "nomos:returnsHex"))) as UsdDerived["returns"],
+      });
+    } else if (kind === "combined") {
+      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"],
+      });
+    } 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)!;
+      return {
+        path: `/Nomos/${domain}`,
+        prims: [...b.prims].sort(byPath),
+        ...(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) } : {}),
+      };
+    })
+    .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";
+}