@githolon/dsl 0.31.1 → 0.33.0

package/src/fields.ts

@@ -72,6 +72,62 @@ export const evidenceRefSchema: z.ZodType<EvidenceRefValue> = z.object({
   storageClass: z.enum(["git", "external"]),
 });
 
+// ── VALUE OBJECTS (composable value objects — `value_object.ts`) ─────────────────────
+// The descriptor types live HERE (dependency-free) so `Field` can carry the metadata
+// without a `fields.ts → value_object.ts` cycle; `value_object.ts` re-exports them.
+
+/** The RFC 7946 geometry kinds a `geo.*` value object can declare (Point is the
+ *  spatial-index-blessed one; see `spatial.ts`). */
+export type GeometryKind = "Point" | "LineString" | "Polygon";
+
+/**
+ * One field of a value-object DESCRIPTOR — the canonical, JSON-schema-ish shape that
+ * rides the package IR (`nomosValueObjects`) and drives TS/Dart codegen. `optional`
+ * is PRESENT only when true (omit-when-false — descriptor bytes are deterministic).
+ * `array.items` is a nested descriptor WITHOUT `optional` (an array of optionals is
+ * not expressible — the v1 constrained set).
+ */
+export type ValueObjectFieldDescriptor =
+  | { readonly type: "string"; readonly optional?: true }
+  | { readonly type: "number"; readonly optional?: true }
+  | { readonly type: "boolean"; readonly optional?: true }
+  | { readonly type: "enum"; readonly values: readonly string[]; readonly optional?: true }
+  | { readonly type: "array"; readonly items: ValueObjectFieldDescriptor; readonly optional?: true }
+  /** A nested value object, referenced BY NAME (its own descriptor rides alongside). */
+  | { readonly type: "object"; readonly ref: string; readonly optional?: true }
+  /** A nested GEO value object (RFC 7946 geometry), referenced by name. */
+  | { readonly type: "geometry"; readonly ref: string; readonly geometry: GeometryKind; readonly optional?: true };
+
+/**
+ * The canonical descriptor of ONE named value object. A structural VO carries
+ * `fields` (keys SORTED — byte-determinism); a `geo.*` VO carries `geometry`
+ * instead (its shape is fixed by RFC 7946, not authored).
+ */
+export interface ValueObjectDescriptor {
+  readonly name: string;
+  readonly fields?: Readonly<Record<string, ValueObjectFieldDescriptor>>;
+  readonly geometry?: GeometryKind;
+}
+
+/**
+ * The value-object metadata a VO-typed `Field` carries (`ValueObject.field()` sets it).
+ * FRONTEND/IR-ONLY: it never enters the kernel wire `Schema` (driver-only — see
+ * `encodeKernelSchema`) nor the canonical manifest, so a VO field's domainHash is
+ * IDENTICAL to a hand-rolled `t.jsonObject()` field. The additive `nomosValueObjects`
+ * USD key (built by `composeDomainModule`/`usd.ts` FROM this metadata) is what makes
+ * the structure visible to tooling.
+ */
+export interface ValueObjectFieldMeta {
+  /** The VO's declared name (the generated TS interface / Dart class name). */
+  readonly name: string;
+  /** This VO's own canonical descriptor. */
+  readonly descriptor: ValueObjectDescriptor;
+  /** Every TRANSITIVELY nested VO's descriptor (self excluded), sorted by name. */
+  readonly dependencies: readonly ValueObjectDescriptor[];
+  /** Present iff this VO is a `geo.*` geometry (the spatial-index pairing check). */
+  readonly geometry?: GeometryKind;
+}
+
 export interface Field<T = unknown, K extends FieldKind = FieldKind> {
   /** The kind tag. `K` is the LITERAL kind so the query DSL can constrain `.ref`
    * to ONLY `kind:'ref'` fields at compile time (`t.ref` → `Field<string,'ref'>`).
@@ -113,6 +169,15 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
    * `encodeKernelSchema`) — so it changes NO hash (identical to `mapValueKind`/`isOptional`).
    */
   readonly jsonShape?: "object";
+  /**
+   * For a `json`-kind field lowered from a NAMED VALUE OBJECT (`ValueObject.field()`):
+   * the VO metadata (name + canonical descriptor + nested-VO dependencies). Drives the
+   * generated TS interface / Dart class and the additive `nomosValueObjects` USD key.
+   * FRONTEND/IR-ONLY — never in the kernel wire `Schema` (driver-only), so the field's
+   * canonical-manifest bytes are identical to a plain `t.jsonObject()` (see
+   * {@link ValueObjectFieldMeta}). `undefined` for every non-VO field.
+   */
+  readonly valueObject?: ValueObjectFieldMeta;
   /**
    * Whether a folded aggregate may LACK this field. A SCALAR field
    * (`string`/`int`/`enum`/`ref`/`json`) that a `.creates` directive does not
@@ -184,6 +249,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     isOptional?: boolean;
     mapValueKind?: FieldKind;
     jsonShape?: "object";
+    valueObject?: ValueObjectFieldMeta;
     encrypted?: true;
     meta?: true;
     facet?: FieldFacet;
@@ -201,6 +267,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     ...(extra.viaField !== undefined ? { viaField: extra.viaField } : {}),
     ...(extra.mapValueKind !== undefined ? { mapValueKind: extra.mapValueKind } : {}),
     ...(extra.jsonShape !== undefined ? { jsonShape: extra.jsonShape } : {}),
+    ...(extra.valueObject !== undefined ? { valueObject: extra.valueObject } : {}),
     ...(extra.encrypted ? { isEncrypted: true as const } : {}),
     ...(extra.meta ? { isMeta: true as const } : {}),
     merge(d: Driver) {
@@ -401,3 +468,20 @@ function refImpl(
   }
   return makeField<string, "ref">("ref", z.string(), Conflict, { refAggregateId: a.id });
 }
+
+/**
+ * INTERNAL (`value_object.ts` — `ValueObject.field()`): construct the JSON-OBJECT value
+ * leaf a named value object lowers to. Storage/merge-identical to `t.jsonObject()`
+ * (kind `"json"`, `jsonShape:"object"`, driver Lww — the whole VO replaces WHOLESALE;
+ * per-subfield merge is what aggregates/maps are for), PLUS the {@link
+ * ValueObjectFieldMeta} that names the VO for codegen + the `nomosValueObjects` IR key.
+ * The zod is the VO's TYPED object schema, so `set(handle, field, value)` and payload
+ * embedding validate the real structure. Not part of `t.*` — reach it via
+ * `valueObject(...)`/`geo.*`'s `.field()`.
+ */
+export function valueObjectField<T>(
+  zod: z.ZodType<T>,
+  valueObject: ValueObjectFieldMeta,
+): Field<T, "json"> {
+  return makeField<T, "json">("json", zod, Lww, { jsonShape: "object", valueObject });
+}

package/src/framework/domain_lifecycle.ts

@@ -28,6 +28,7 @@ export const DOMAIN_INSTALLATION_PHASES = [
   "Disabled",
   "Superseded",
   "Retiring",
+  "Retired",
   "Failed",
 ] as const;
 export type DomainInstallationPhase = (typeof DOMAIN_INSTALLATION_PHASES)[number];
@@ -48,6 +49,7 @@ export const DomainInstallation = aggregate("DomainInstallation", {
   "metadata.generation": t.int().merge(Lww),
   "status.phase": t.enum(DOMAIN_INSTALLATION_PHASES).merge(Lww),
   "status.observedGeneration": t.int().merge(Lww),
+  "status.supersededBy": t.string().merge(Lww).optional(),
   "status.conditions": t.map(t.json()).merge(MapOf(Lww)),
 });
 
@@ -77,6 +79,13 @@ export const installDomain = directive("installDomain")
       authorityScope: z.string().default("workspace/root"),
       dependencies: z.array(z.string()).default([]),
       supersedes: z.string().optional(),
+      // THE FRONTIER TRANSITION (install-lifecycle): `replaces` names a PRIOR install this
+      // deploy makes current UNEQUIVOCALLY — the prior install is flipped out of the served
+      // frontier (`Superseded`, or `Retired` when `retireReplaced`) and gets the reverse
+      // `status.supersededBy` edge to this install. Absent ⇒ install-BESIDE (backward-compat:
+      // byte-identical ops to the pre-lifecycle plan). `replaces` also sets `spec.supersedes`.
+      replaces: z.string().optional(),
+      retireReplaced: z.boolean().default(false),
       finalizers: z.array(z.string()).default([]),
     }),
   )
@@ -97,8 +106,18 @@ export const installDomain = directive("installDomain")
     if (p.dependencies.length > 0) {
       ops.push(addToSet(install, "spec.dependencies", p.dependencies));
     }
-    if (p.supersedes !== undefined) {
-      ops.push(set(install, "spec.supersedes", p.supersedes));
+    // The predecessor back-link: `supersedes` (explicit) or `replaces` (the actionable form).
+    const supersedes = p.supersedes ?? p.replaces;
+    if (supersedes !== undefined) {
+      ops.push(set(install, "spec.supersedes", supersedes));
+    }
+    // The transition on the PRIOR install: drop it from the served frontier + point it here.
+    if (p.replaces !== undefined) {
+      const replaced = domainInstallationInstance(p.replaces);
+      ops.push(
+        set(replaced, "status.phase", p.retireReplaced ? "Retired" : "Superseded"),
+      );
+      ops.push(set(replaced, "status.supersededBy", p.domainHash));
     }
     if (p.finalizers.length > 0) {
       ops.push(addToSet(install, "spec.finalizers", p.finalizers));

package/src/index.ts

@@ -40,6 +40,25 @@ export {
   secretField,
   publicField,
 } from "./fields.js";
+// FIRST-CLASS COMPOSABLE VALUE OBJECTS (`value_object.ts`): named, reusable, nestable
+// structured values — ONE definition yields the zod (payload validation), the TS type,
+// the generated Dart class, and the `nomosValueObjects` IR descriptor. A VO lowers to a
+// single Lww-class json-object leaf (wholesale-replace merge — no per-subfield merge).
+// `geo.*` are the RFC 7946 geometry VOs (pair `geo.point()` with `spatial(...)`).
+export {
+  valueObject,
+  geo,
+  type ValueObject,
+  type ValueObjectValue,
+  type OptionalValueObject,
+  type ValueObjectShapeEntry,
+  type ValueObjectDescriptor,
+  type ValueObjectFieldDescriptor,
+  type GeometryKind,
+  type GeoPointValue,
+  type GeoLineStringValue,
+  type GeoPolygonValue,
+} from "./value_object.js";
 export {
   type PrincipalEvidence,
   type AttributionPrincipal,

package/src/relation_composition.ts

@@ -0,0 +1,286 @@
+// 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}.
+//
+// COMPILE-TIME USD-LAYER COMPOSITION for SHARED (global) relation types + the
+// fail-closed DIVERGENCE GUARD.
+//
+// THE MODEL. When a package bundles multiple domains, each domain lowers its own
+// `relationType` decls into its own `UsdLayer.nomosRelations`. A NON-global type is
+// auto-qualified by its owning domain (`estate` → `estate__workspace`), so two
+// domains that each declare the same bare type NEVER collide — their qualified ids
+// differ, and they stay separate layers. A `.asGlobal()` type (a kernel-coupled
+// framework type, e.g. governance/read-visibility `workspace`) stays a BARE shared
+// name, so MULTIPLE domains that each contribute to one global type land on the SAME
+// canonical id. That cross-domain merge USED to happen only at the KERNEL (runtime
+// `merge_layers`, a blunt per-type last-wins that SILENTLY DROPS the losing layer's
+// relations — the bug that broke co2's `createSite`). We move it to COMPILE time, in
+// TS, using USD's composition MODEL (LIVRPS sublayer strength):
+//
+//   * COMPOSE (deliverable #1): for each SHARED global type, UNION the relations
+//     across the contributing domains — a prim-set union, so EVERY domain's relations
+//     survive (nothing is dropped). The composed union is written back into every
+//     contributing layer so the downstream kernel merge (union OR last-wins) yields
+//     the full union regardless of its policy. This is idempotent and byte-stable.
+//
+//   * GUARD (deliverable #2): when two or more domains declare the SAME relation on a
+//     SHARED global type with DIVERGENT rewrites (co2's `workspace.admin`: `self()` in
+//     estate/platform vs `union(self, computed(creator))` in home), REFUSE AT COMPILE
+//     with a scalpel message naming the type, the relation, and each domain's rewrite.
+//     Single-owner relations and byte-identical agreeing opinions PASS (union). This
+//     turns the kernel's blunt `None` / "no-relation-schema" into a precise compile
+//     refusal — the era rule ("the law is the era") is preserved because a package with
+//     no shared global type composes to itself, byte-identical.
+//
+// SUBLAYER STRENGTH ORDER (documented, deliverable #1): the package's domain order is
+// WEAK → STRONG (Nomos module-fold notation — later wins), which maps onto USD
+// `subLayers` STRONGEST-FIRST by reversal (the same left-biased monoid, opposite list
+// notation — the convention `usd_layers.ts::layeredRootUsda` already records). For a
+// NON-divergent shared type the union is order-INDEPENDENT (every domain's opinion on a
+// given relation is identical, so which layer "wins" is immaterial); order matters ONLY
+// to the visualization flatten, never to the composed IR.
+
+import type { UsdLayer } from "./usd.js";
+
+/** A single relation's definition as it rides in `nomosRelations` (`{rewrite, allowed}`). */
+type RelDef = NonNullable<UsdLayer["nomosRelations"]>["types"][string]["relations"][string];
+/** One relation TYPE's spec (`{relations, caps?}`). */
+type RelSpec = NonNullable<UsdLayer["nomosRelations"]>["types"][string];
+
+/** Strip the `/Nomos/` prim-scope prefix to recover the owning domain key from a layer path. */
+export function domainOfLayerPath(path: string): string {
+  return path.startsWith("/Nomos/") ? path.slice("/Nomos/".length) : path;
+}
+
+/**
+ * Render a rewrite AST to the author-facing surface syntax (`self()` / `computed(x)` /
+ * `union(...)` / `via(t, c)` / …) — the readable form the scalpel message + the layered
+ * `.usda` provenance attr carry. A `null`/absent rewrite is a pure-direct relation (`this`).
+ */
+export function renderRewrite(rw: unknown): string {
+  if (rw === null || rw === undefined) return "this";
+  const r = rw as { kind?: string; [k: string]: unknown };
+  switch (r.kind) {
+    case "this":
+      return "self()";
+    case "computed":
+      return `computed(${String(r.relation)})`;
+    case "ttu":
+      return `${r.all ? "viaAll" : "via"}(${String(r.tupleset)}, ${String(r.computed)})`;
+    case "union":
+      return `union(${(r.children as unknown[]).map(renderRewrite).join(", ")})`;
+    case "intersection":
+      return `intersection(${(r.children as unknown[]).map(renderRewrite).join(", ")})`;
+    case "exclusion":
+      return `exclusion(${renderRewrite(r.base)}, ${renderRewrite(r.subtract)})`;
+    default:
+      return JSON.stringify(rw);
+  }
+}
+
+/** A per-relation divergence, gathered for the scalpel message. */
+interface RelationConflict {
+  readonly type: string;
+  readonly relation: string;
+  /** Each contributing domain's opinion, in package (weak→strong) order. */
+  readonly opinions: { readonly domain: string; readonly rewrite: string }[];
+}
+
+/** Format the accumulated divergences into the fail-closed refusal (mirrors `failclosed_check.py`). */
+function scalpelMessage(conflicts: readonly RelationConflict[]): string {
+  const lines: string[] = [
+    `Refusing to compose the package: shared relation type(s) carry DIVERGENT rewrites across ` +
+      `domains — the composed flatten would SILENTLY take the strongest layer's opinion (LIVRPS ` +
+      `last-wins), so this is a fail-closed compile refusal, not a silent pick.`,
+    ``,
+  ];
+  for (const c of conflicts) {
+    lines.push(`  relation type "${c.type}" relation "${c.relation}" — ${c.opinions.length} divergent opinions:`);
+    const w = Math.max(...c.opinions.map((o) => o.domain.length));
+    for (const o of c.opinions) lines.push(`      · ${o.domain.padEnd(w)}  ${o.rewrite}`);
+  }
+  lines.push(
+    ``,
+    `Fix: give the type ONE canonical definition of each divergent relation (the domains must ` +
+      `agree, byte-for-byte), or use DISTINCT / domain-qualified relation types (drop \`.asGlobal()\` ` +
+      `so each domain's type auto-qualifies and never shares an id).`,
+  );
+  return lines.join("\n");
+}
+
+/**
+ * Compose the SHARED (global, bare-id) relation types across a package's layers — UNION the
+ * relations per shared type, GUARD divergent rewrites fail-closed, and write the union back into
+ * every contributing layer. Non-shared (single-owner / auto-qualified) types are untouched, so a
+ * package with no shared global type returns byte-identical layers (the era rule). Deterministic:
+ * sorted keys, sorted diagnostics.
+ *
+ * @throws a scalpel `Error` naming the type, relation, and each domain's rewrite on any divergence.
+ */
+export function composeSharedRelationTypes(layers: readonly UsdLayer[]): UsdLayer[] {
+  // type id → the layers (domains) that contribute it, in package (weak→strong) order.
+  const contributors = new Map<string, { domain: string; spec: RelSpec }[]>();
+  for (const layer of layers) {
+    const rels = layer.nomosRelations;
+    if (rels === undefined) continue;
+    for (const [type, spec] of Object.entries(rels.types)) {
+      const arr = contributors.get(type) ?? [];
+      arr.push({ domain: domainOfLayerPath(layer.path), spec });
+      contributors.set(type, arr);
+    }
+  }
+
+  const composed = new Map<string, RelSpec>();
+  const conflicts: RelationConflict[] = [];
+  for (const type of [...contributors.keys()].sort()) {
+    const contribs = contributors.get(type)!;
+    // A type contributed by ONE domain is single-owner — nothing to compose (untouched).
+    if (contribs.length < 2) continue;
+
+    // caps must agree across the contributing domains (a divergent bound is a hard error).
+    let caps: RelSpec["caps"];
+    for (const c of contribs) {
+      if (c.spec.caps === undefined) continue;
+      if (caps === undefined) caps = c.spec.caps;
+      else if (caps.maxDepth !== c.spec.caps.maxDepth || caps.maxFanout !== c.spec.caps.maxFanout) {
+        throw new Error(
+          `Refusing to compose the package: shared relation type "${type}" is declared with ` +
+            `CONFLICTING caps across domains (${contribs.map((x) => x.domain).join(", ")}). Give the ` +
+            `type one canonical \`caps\`.`,
+        );
+      }
+    }
+
+    // Gather every domain's opinion on each relation (in package order).
+    const opinions = new Map<string, { domain: string; def: RelDef }[]>();
+    for (const c of contribs) {
+      for (const [rel, def] of Object.entries(c.spec.relations)) {
+        const arr = opinions.get(rel) ?? [];
+        arr.push({ domain: c.domain, def });
+        opinions.set(rel, arr);
+      }
+    }
+
+    const unioned: Record<string, RelDef> = {};
+    for (const rel of [...opinions.keys()].sort()) {
+      const ops = opinions.get(rel)!;
+      const distinct = new Set(ops.map((o) => JSON.stringify(o.def)));
+      if (distinct.size > 1) {
+        conflicts.push({
+          type,
+          relation: rel,
+          opinions: ops.map((o) => ({ domain: o.domain, rewrite: renderRewrite((o.def as { rewrite: unknown }).rewrite) })),
+        });
+      } else {
+        unioned[rel] = ops[0]!.def; // agreeing opinions / single-owner relation — keep it
+      }
+    }
+    // Sorted relation keys (byte-determinism against the per-layer emission).
+    const relations: Record<string, RelDef> = {};
+    for (const k of Object.keys(unioned).sort()) relations[k] = unioned[k]!;
+    composed.set(type, { relations, ...(caps !== undefined ? { caps } : {}) });
+  }
+
+  if (conflicts.length > 0) throw new Error(scalpelMessage(conflicts));
+  if (composed.size === 0) return [...layers]; // nothing shared — byte-identical (era rule)
+
+  // Write the composed union back into every contributing layer, keeping type keys sorted.
+  return layers.map((layer) => {
+    const rels = layer.nomosRelations;
+    if (rels === undefined) return layer;
+    let touched = false;
+    const merged: Record<string, RelSpec> = {};
+    for (const [type, spec] of Object.entries(rels.types)) {
+      const c = composed.get(type);
+      if (c !== undefined) {
+        merged[type] = c;
+        touched = true;
+      } else {
+        merged[type] = spec;
+      }
+    }
+    if (!touched) return layer;
+    const sorted: Record<string, RelSpec> = {};
+    for (const k of Object.keys(merged).sort()) sorted[k] = merged[k]!;
+    return { ...layer, nomosRelations: { v: 1 as const, types: sorted } };
+  });
+}
+
+// ── the REAL layered `.usda` emission (deliverable #3 — for usdview / usdcat --flatten) ──────────
+
+/** One domain's contribution to the layered relation emission: its bare-id relation types. */
+export interface RelationLayerInput {
+  readonly domain: string;
+  /** The domain's `nomosRelations.types` (UNCOMPOSED — the layers ARE the sublayers usdcat composes). */
+  readonly types: Record<string, RelSpec>;
+}
+
+/** `"a"` → escaped USDA string literal (minimal — relation/rewrite tokens are `[A-Za-z0-9_.,()]`). */
+function usda(s: string): string {
+  return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * Emit ONE domain's relation opinions as a real `.usda` sublayer: `def "<Type>" { def "<relation>"
+ * { custom string nomos:rewrite = "…"; custom string nomos:from = "<domain>" } }`. Structured so
+ * `usdcat --flatten` composes the relation prims across sublayers (a stronger layer's `nomos:rewrite`
+ * wins; the relation SET is the union). Deterministic: types + relations sorted.
+ */
+export function emitRelationSublayerUsda(input: RelationLayerInput): string {
+  const lines: string[] = [`#usda 1.0`, `(`, `    doc = "Nomos relation layer — domain ${input.domain}"`, `)`, ``];
+  for (const type of Object.keys(input.types).sort()) {
+    lines.push(`def ${usda(type)}`, `{`);
+    const relations = input.types[type]!.relations;
+    for (const rel of Object.keys(relations).sort()) {
+      const def = relations[rel]! as { rewrite: unknown };
+      lines.push(
+        `    def ${usda(rel)}`,
+        `    {`,
+        `        custom string nomos:rewrite = ${usda(renderRewrite(def.rewrite))}`,
+        `        custom string nomos:from = ${usda(input.domain)}`,
+        `    }`,
+      );
+    }
+    lines.push(`}`, ``);
+  }
+  return lines.join("\n");
+}
+
+/** The result of {@link emitLayeredRelationUsda}: a root document + one sublayer file per domain. */
+export interface LayeredRelationEmit {
+  /** The root `.usda` (`subLayers = [...]`, STRONGEST-FIRST) that usdcat --flatten composes. */
+  readonly root: string;
+  /** Per-domain sublayer files (`name` is a bare filename; write beside the root). */
+  readonly files: { readonly name: string; readonly text: string }[];
+}
+
+/**
+ * Emit a REAL layered relation `.usda` set: one sublayer per domain (its relation opinions as prims)
+ * + a root with `subLayers` STRONGEST-FIRST, so `usdcat --flatten <root>` composes the package's
+ * shared relation types. `inputs` are in package order (WEAK → STRONG); the root reverses them to
+ * strongest-first (the documented convention). Deterministic (sorted within each layer, stable file
+ * names). Additive build artifact — never feeds the package hash.
+ */
+export function emitLayeredRelationUsda(inputs: readonly RelationLayerInput[], packageName: string): LayeredRelationEmit {
+  const safe = (s: string) => s.replace(/[^A-Za-z0-9._-]/g, "_");
+  const files = inputs.map((input) => ({
+    name: `${safe(input.domain)}.usda`,
+    text: emitRelationSublayerUsda(input),
+  }));
+  // subLayers is STRONGEST-FIRST → reverse the weak→strong package order.
+  const strongestFirst = [...files].reverse();
+  const root = [
+    `#usda 1.0`,
+    `(`,
+    `    doc = """Nomos relation-composition layers for package ${packageName}. subLayers are`,
+    `STRONGEST-FIRST (USD layer-stack order); the Nomos domain list composes weak→strong (later`,
+    `wins). \`usdcat --flatten\` composes the shared relation types; the compiler's TS composition`,
+    `(composeSharedRelationTypes) is the fail-closed guard layered on top."""`,
+    `    subLayers = [`,
+    ...strongestFirst.map((f, i) => `        @./${f.name}@${i < strongestFirst.length - 1 ? "," : ""}`),
+    `    ]`,
+    `)`,
+    ``,
+  ].join("\n");
+  return { root, files };
+}

package/src/usd.ts

@@ -44,6 +44,7 @@ import type { DomainModule } from "./codegen_dart.js";
 import { domainInterface } from "./shape_compat.js";
 import { relationType, user, key, anyUser, qualifiedTypeId, qualifyRelationType } from "./relation_schema.js";
 import { harvestPrincipalFlows } from "./wire_encode.js";
+import { composeSharedRelationTypes } from "./relation_composition.js";
 
 /** The referential marker of a directive prim (kernel `RefMode` wire string). */
 export type RefMode = WireRefMode;
@@ -463,6 +464,19 @@ export interface UsdLayer {
       readonly reason: string | null;
     }[];
   };
+  /**
+   * FIRST-CLASS VALUE OBJECTS (`value_object.ts`) — the canonical descriptors of every
+   * named value object this layer's aggregates carry (deduped, SORTED by name, nested
+   * VOs included), so tooling/visualizers SEE the structure a VO field stores. PURELY
+   * DESCRIPTIVE: the kernel reads no gate off it (a VO field folds exactly like a
+   * `t.jsonObject()` leaf — one wholesale-replace json value). OMITTED for VO-free law
+   * (byte-identical hash — the era rule); declaring a VO moves the PACKAGE hash only
+   * (the canonical manifest/domainHash is untouched — the VO is not wire law).
+   */
+  readonly nomosValueObjects?: {
+    readonly v: 1;
+    readonly valueObjects: readonly import("./fields.js").ValueObjectDescriptor[];
+  };
 }
 
 /** The reserved variant name declaring a set's DEFAULT (USD has a default variant). */
@@ -994,6 +1008,13 @@ export function emitUsd(
       // conversion's declared flow {directiveId, sink, facet, reason}. Hashed into nomosFlowGate +
       // witnessed fail-closed at runtime (Slice B). Omit-when-empty (a principal-free domain is
       // byte-identical). SORTED for determinism.
+      // FIRST-CLASS VALUE OBJECTS: the module's collected descriptors (composeDomainModule
+      // dedupes + sorts them). Omit-when-empty (era rule — VO-free law is byte-identical).
+      const moduleValueObjects = (l.module as { valueObjects?: readonly import("./fields.js").ValueObjectDescriptor[] }).valueObjects;
+      const nomosValueObjects =
+        moduleValueObjects !== undefined && moduleValueObjects.length > 0
+          ? { v: 1 as const, valueObjects: [...moduleValueObjects] }
+          : undefined;
       const flowEndorse = [...l.module.directives]
         .flatMap((d) => harvestPrincipalFlows(d as never).map((f) => ({ directiveId: d.id, sink: f.sink, facet: f.facet, reason: f.reason })))
         .sort((a, b) =>
@@ -1039,6 +1060,7 @@ export function emitUsd(
         ...(nomosBirthGate !== undefined ? { nomosBirthGate } : {}),
         ...(nomosParentAttestedBirth !== undefined ? { nomosParentAttestedBirth } : {}),
         ...(nomosVerifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll } : {}),
+        ...(nomosValueObjects !== undefined ? { nomosValueObjects } : {}),
         ...(Object.keys(visAggregates).length > 0
           ? { nomosReadVisibility: { v: 1 as const, aggregates: visAggregates } }
           : {}),
@@ -1060,7 +1082,11 @@ export function emitUsd(
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
-  return { layers: out };
+  // COMPILE-TIME COMPOSITION + fail-closed GUARD for SHARED (global) relation types across the
+  // package's per-domain layers: UNION every domain's relations on a shared bare-id type (so nothing
+  // is silently dropped) and REFUSE on a divergent shared rewrite (the scalpel). Non-shared /
+  // auto-qualified types are untouched → a package with no shared global type is byte-identical.
+  return { layers: composeSharedRelationTypes(out) };
 }
 
 /** Two aggregate prims at the same path are identical iff same type + same schema. */

package/src/usd_layers.ts

@@ -70,6 +70,7 @@ import {
   type UsdPrim,
   type UsdQuery,
 } from "./usd.js";
+import { composeSharedRelationTypes } from "./relation_composition.js";
 
 /** The layer-file format marker (customLayerData `nomos:format`). */
 export const NOMOS_USD_LAYER_FORMAT = "nomos.usd-layer.v1";
@@ -189,6 +190,9 @@ function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string):
     ...(layer.nomosVerifiedFirstEnroll !== undefined
       ? [`${indent}custom string nomos:verifiedFirstEnrollHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosVerifiedFirstEnroll)))}`]
       : []),
+    ...(layer.nomosValueObjects !== undefined
+      ? [`${indent}custom string nomos:valueObjectsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosValueObjects)))}`]
+      : []),
   ];
 }
 
@@ -865,7 +869,10 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
     };
   });
 
-  return { layers: out };
+  // 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) ──────────
@@ -993,6 +1000,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const birthGateByDomain = new Map<string, UsdLayer["nomosBirthGate"]>();
   const parentAttestedBirthByDomain = new Map<string, UsdLayer["nomosParentAttestedBirth"]>();
   const verifiedFirstEnrollByDomain = new Map<string, UsdLayer["nomosVerifiedFirstEnroll"]>();
+  const valueObjectsByDomain = new Map<string, UsdLayer["nomosValueObjects"]>();
   for (const p of prims) {
     if (p.attrs.get("nomos:kind") === "domain") {
       const domain = attrString(p, "nomos:domain");
@@ -1064,6 +1072,11 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof vfeHex === "string") {
         verifiedFirstEnrollByDomain.set(domain, JSON.parse(unhexUtf8(vfeHex)) as UsdLayer["nomosVerifiedFirstEnroll"]);
       }
+      // FIRST-CLASS VALUE OBJECTS: the hex-carried descriptor set (descriptive, not a gate).
+      const voHex = p.attrs.get("nomos:valueObjectsHex");
+      if (typeof voHex === "string") {
+        valueObjectsByDomain.set(domain, JSON.parse(unhexUtf8(voHex)) as UsdLayer["nomosValueObjects"]);
+      }
     }
   }
 
@@ -1165,6 +1178,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const birthGate = birthGateByDomain.get(domain);
       const parentAttestedBirth = parentAttestedBirthByDomain.get(domain);
       const verifiedFirstEnroll = verifiedFirstEnrollByDomain.get(domain);
+      const valueObjects = valueObjectsByDomain.get(domain);
       return {
         path: `/Nomos/${domain}`,
         prims: [...b.prims].sort(byPath),
@@ -1185,6 +1199,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),
         ...(parentAttestedBirth !== undefined ? { nomosParentAttestedBirth: parentAttestedBirth } : {}),
         ...(verifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll: verifiedFirstEnroll } : {}),
+        ...(valueObjects !== undefined ? { nomosValueObjects: valueObjects } : {}),
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));