@githolon/dsl 0.31.0 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/aggregate.ts

@@ -155,6 +155,17 @@ export interface AggregateHandle<
   readonly hasMany: HasManyFields<F>;
   /** Brand so a plain string is never accepted where a handle is required. */
   readonly __isAggregateHandle: true;
+  /**
+   * FRAMEWORK-SHARED brand (Dart-codegen hygiene). Set (by `framework/framework_aggregates.ts`)
+   * ONLY on the framework-owned aggregate singletons declared in `dsl/src/framework/` — most
+   * importantly `RelationTuple`, auto-added to EVERY relation-using domain. A branded aggregate's
+   * Dart surface (read-model class, typed-id class, by-id accessors) is emitted ONCE per package into
+   * a shared `nomos_framework.dart` file, NOT re-emitted in each domain's generated `.dart` — so a
+   * package barrel re-exporting several domains never gets a duplicate framework symbol (no hand-
+   * maintained `hide` clause). NOT hashed / NOT law: a pure frontend-codegen marker (like
+   * `readModelAggregates`). Identified by OBJECT IDENTITY (the branded singleton), so a tenant
+   * aggregate that merely SHARES a name is never misclassified. OMITTED on tenant aggregates. */
+  readonly framework?: true;
   /** Presence-only flag (hashed); OMITTED ENTIRELY when no invariant is declared. */
   readonly hasInvariant?: true;
   /** The executable body — ships in the engine bundle, NOT the manifest. */

package/src/codegen_dart.ts

@@ -1168,8 +1168,8 @@ function emitEvidenceRefClass(): string {
 
 /** True when ANY aggregate field in the module is `t.evidence()` — gates emitting the
  * shared [emitEvidenceRefClass] once. */
-function moduleUsesEvidence(mod: DomainModule): boolean {
-  return mod.aggregates.some((a) =>
+function moduleUsesEvidence(aggregates: readonly AggregateHandle[]): boolean {
+  return aggregates.some((a) =>
     Object.values(a.fields as Record<string, Field>).some((f) => f.kind === "evidence"),
   );
 }
@@ -2300,14 +2300,21 @@ function emitMintedCreates(
   directives: AnyDirective[],
   domainName: string,
   enumDartTypes: Map<string, string>,
+  /** Aggregate ids whose typed-id CLASS is emitted in the shared `nomos_framework.dart` (imported
+   *  here), so it must NOT be re-declared. Minting FACTORIES still emit and reference the imported
+   *  class. Empty = emit every id class locally (the single-domain / shared-file path). */
+  skipIdClassFor: ReadonlySet<string> = new Set(),
 ): string {
   const blocks: string[] = [];
 
   // (1) A typed id class per aggregate. Dedup by the typed-id class NAME: two wire
   // types never collide on a name (the name is a pure function of the type), and a
   // domain that re-exports a framework aggregate must not emit its id class twice.
+  // Framework-shared aggregates are emitted ONCE in the package's `nomos_framework.dart`,
+  // so their id class is SKIPPED here (referenced via import).
   const emittedIdClasses = new Set<string>();
   for (const agg of aggregates) {
+    if (skipIdClassFor.has(agg.id)) continue;
     const cls = typedIdClassForAggregateType(agg.id);
     if (emittedIdClasses.has(cls)) continue;
     emittedIdClasses.add(cls);
@@ -2565,12 +2572,49 @@ export interface DomainModule {
   dartRefImports?: DartRefImport[];
 }
 
+/** Options controlling FRAMEWORK-SHARED aggregate deduplication (Dart-codegen hygiene). */
+export interface GenerateDartDomainOptions {
+  /**
+   * Aggregate ids whose Dart surface (projection class, read model, typed-id class, by-id accessors)
+   * is emitted ONCE per package in the shared `nomos_framework.dart` and MUST NOT be re-emitted here —
+   * this domain REFERENCES them via {@link frameworkImportUri}. Empty/absent ⇒ emit everything locally
+   * (the legacy single-file behaviour; byte-identical to before this option existed).
+   */
+  readonly skipAggregateIds?: ReadonlySet<string>;
+  /**
+   * Framework-shared DIRECTIVE ids whose generated payload class (+ minted-create factory) is emitted
+   * ONCE per package in the shared file and MUST NOT be re-emitted here. The domain still OFFERS them
+   * (the client offer methods stay per-domain); only the payload TYPE moves to the shared file.
+   */
+  readonly skipDirectiveIds?: ReadonlySet<string>;
+  /**
+   * Framework-shared QUERY ids whose top-level `watch<Q>`/`read<Q>` accessors are emitted ONCE per
+   * package in the shared file and MUST NOT be re-emitted here. The client's per-domain query methods
+   * stay (they reference the shared read models via the framework import).
+   */
+  readonly skipQueryIds?: ReadonlySet<string>;
+  /**
+   * Relative import of the shared framework file (e.g. `nomos_framework.dart`). Added as an ordinary
+   * `import` so skipped framework symbols resolve. Omit when nothing is skipped.
+   */
+  readonly frameworkImportUri?: string;
+}
+
 /** Generate the full Dart source for one domain module. */
-export function generateDartDomain(mod: DomainModule): string {
+export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOptions = {}): string {
   const domainKey = mod.domain ?? mod.name;
+  const skipAggregateIds = opts.skipAggregateIds ?? new Set<string>();
+  const skipDirectiveIds = opts.skipDirectiveIds ?? new Set<string>();
+  const skipQueryIds = opts.skipQueryIds ?? new Set<string>();
+  // The symbols whose Dart surface this file EMITS (framework-shared ones live in the shared file).
+  const localAggregates = mod.aggregates.filter((a) => !skipAggregateIds.has(a.id));
+  const localDirectives = mod.directives.filter((d) => !skipDirectiveIds.has(d.id));
+  const localQueries = (mod.queries ?? []).filter((q) => !skipQueryIds.has(q.id));
+  // Enums are collected from the LOCALLY-emitted symbols only — a framework directive/aggregate's
+  // enums ride the shared `nomos_framework.dart`, so a domain that skips them emits no dangling enum.
   const { dartTypes, decls } = collectEnums(
-    mod.aggregates,
-    mod.directives,
+    localAggregates,
+    localDirectives,
     domainKey,
   );
   const refIdClassForAggregate = refIdClassResolver(mod);
@@ -2583,7 +2627,7 @@ export function generateDartDomain(mod: DomainModule): string {
   );
   const enumBlock = decls.join("\n\n");
   const permissionVocabularyBlock = emitPermissionVocabulary(mod.permissionVocabulary);
-  const aggBlock = mod.aggregates
+  const aggBlock = localAggregates
     .map((a) =>
       emitAggregate(
         a,
@@ -2593,7 +2637,7 @@ export function generateDartDomain(mod: DomainModule): string {
       ),
     )
     .join("\n\n");
-  const dirBlock = mod.directives
+  const dirBlock = localDirectives
     .map((d) => emitDirective(d, domainKey, dartTypes))
     .join("\n\n");
 
@@ -2602,7 +2646,9 @@ export function generateDartDomain(mod: DomainModule): string {
   // ref fields name their target's typed id), plus a top-level `create…` factory that
   // mints THROUGH the kernel (no raw id) for every `.creates` directive carrying a
   // `mintSeed` + an own-id field.
-  const mintedBlock = emitMintedCreates(mod.aggregates, mod.directives, domainKey, dartTypes);
+  // Minted-create factories for framework directives (if any) live in the shared file — pass only the
+  // LOCAL directives here; framework typed-id classes are likewise skipped (referenced via import).
+  const mintedBlock = emitMintedCreates(mod.aggregates, localDirectives, domainKey, dartTypes, skipAggregateIds);
 
   // PROVIDER SDK (the symmetric twin of the peer payload classes): for each declared
   // `impureCapability` capability, a typed Obligation/Result/Failure + handler typedef + dispatcher.
@@ -2635,7 +2681,7 @@ export function generateDartDomain(mod: DomainModule): string {
     list.push(c);
     combinedsByType.set(c.of, list);
   }
-  const readModelBlock = mod.aggregates
+  const readModelBlock = localAggregates
     .filter((a) => readModelTypes.has(a.id))
     .map((a) =>
       emitReadModel(
@@ -2657,7 +2703,7 @@ export function generateDartDomain(mod: DomainModule): string {
   // §5 claim that "codegen already emits count reads" was wrong; this is the actual
   // first emission. The predicate is baked into the maintained counter and is
   // INVISIBLE to the generated accessor (worldview law).
-  const queryReads = (mod.queries ?? [])
+  const queryReads = localQueries
     .map((q) =>
       emitQueryReads(
         q,
@@ -2731,7 +2777,9 @@ export function generateDartDomain(mod: DomainModule): string {
     )
     .join("\n\n");
   const orderedReadBlock = (mod.orderedReads ?? []).map(emitOrderedReads).join("\n\n");
-  const byIdReads = mod.aggregates.map(emitAggregateByIdReads).join("\n\n");
+  // By-id accessors for framework-shared aggregates live in `nomos_framework.dart` (emitted once);
+  // this domain references them via the framework import.
+  const byIdReads = localAggregates.map(emitAggregateByIdReads).join("\n\n");
   const readBlock = [queryReads, countReads, sumReads, minReads, maxReads, existsReads, orderedReadBlock, byIdReads]
     .filter((s) => s !== "")
     .join("\n\n");
@@ -2739,7 +2787,7 @@ export function generateDartDomain(mod: DomainModule): string {
   // `_mapEq` is only referenced by aggregate `==`/`hashCode` for MAP fields. Emit it
   // ONLY when some aggregate has a map field, else a map-less domain trips an
   // unused-element lint.
-  const hasMapField = mod.aggregates.some((a) =>
+  const hasMapField = localAggregates.some((a) =>
     Object.values(a.fields as Record<string, Field>).some((f) => f.kind === "map"),
   );
   const helperBlock = hasMapField
@@ -2771,6 +2819,9 @@ export function generateDartDomain(mod: DomainModule): string {
     // out of nomos_client into the co-located tenant package). The framework barrel
     // re-exports wire/dispatch/subscriptions/provider, so one import covers them all.
     `import 'package:nomos_client/nomos_client.dart';`,
+    // FRAMEWORK-SHARED aggregates (RelationTuple, …) are emitted ONCE per package in the shared
+    // file; import it so this domain's read accessors / ref-id fields resolve those symbols.
+    ...(opts.frameworkImportUri !== undefined ? [`import '${opts.frameworkImportUri}';`] : []),
     ...(mod.dartImports ?? []).map(dartImportLine),
     ``,
     `// ---- enums ----`,
@@ -2783,7 +2834,7 @@ export function generateDartDomain(mod: DomainModule): string {
           ``,
         ]
       : []),
-    ...(moduleUsesEvidence(mod)
+    ...(moduleUsesEvidence(localAggregates)
       ? [
           `// ---- evidence (content-addressed EvidenceRef; evidence.md §9.2) ----`,
           emitEvidenceRefClass(),

package/src/codegen_dart_client.ts

@@ -99,6 +99,14 @@ export interface DartBridgeClientOptions {
   readonly interface?: unknown;
   /** Where the bridge/runtime support types are imported from. */
   readonly supportImport?: "vendored" | "package";
+  /**
+   * Relative import of the shared `nomos_framework.dart` (framework-shared aggregate types, emitted
+   * ONCE per package). When present the client IMPORTS it (its by-id accessors reference framework
+   * read models) and RE-EXPORTS it, so a package barrel re-exporting several domain clients surfaces
+   * the framework types EXACTLY ONCE (Dart de-dups re-exports of the SAME library) — no `hide` needed.
+   * Omit for a package with no framework-shared aggregates.
+   */
+  readonly frameworkImportUri?: string;
 }
 
 /** Generate the `<name>.client.dart` async bridge client for one domain module. */
@@ -245,9 +253,13 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     ...(opts.interface !== undefined ? [`import 'dart:convert';`, ``] : []),
     `import '${supportImport}';`,
     `import '${mod.name}.dart';`,
+    // Framework-shared aggregate types (RelationTupleReadModel, …) live in the ONE shared file — import
+    // them (the by-id accessors reference them) and re-export them (once per package, Dart de-dups).
+    ...(opts.frameworkImportUri !== undefined ? [`import '${opts.frameworkImportUri}';`] : []),
     `// Re-export the sibling types (read models + payloads + the bridge runtime) so ONE import of this`,
     `// client file gives an app the whole typed surface.`,
     `export '${mod.name}.dart';`,
+    ...(opts.frameworkImportUri !== undefined ? [`export '${opts.frameworkImportUri}';`] : []),
     `export '${supportImport}' show NomosBridge, BridgeTransport, NomosBridgeError, MissingOfferAuthority, kWebviewBridgeVersion;`,
     ``,
     `/// sha256 of the deployed \`.package.usda\` — the installed law this client offers under.`,

package/src/compile_package_main.ts

@@ -61,6 +61,11 @@ import {
   type PermissionVocabulary,
 } from "./codegen_dart.js";
 import { generateDartBridgeClient } from "./codegen_dart_client.js";
+import {
+  isFrameworkAggregate,
+  isFrameworkDirective,
+  isFrameworkQuery,
+} from "./framework/framework_aggregates.js";
 import { finishCount, type AnyCount } from "./count.js";
 import type { QueryDecl } from "./query.js";
 import type { SpatialDecl } from "./spatial.js";
@@ -108,7 +113,8 @@ import {
   type InferredRename,
   type StableIds,
 } from "./stable_ids.js";
-import type { UsdLayer } from "./usd.js";
+import { emitUsd, type UsdLayer } from "./usd.js";
+import { emitLayeredRelationUsda, type RelationLayerInput } from "./relation_composition.js";
 import { generateTsClient, tsClientFactoryName } from "./codegen_ts.js";
 import { generateOpenApiFragment, mergeOpenApiFragments } from "./codegen_openapi.js";
 import { domainInterface, type DomainInterface } from "./shape_compat.js";
@@ -387,35 +393,108 @@ function emitDart(
     removeVendoredDartSupport(dartOut);
   }
 
-  // 2. one generated file per composed domain — the TYPES (`<name>.dart`) + the async bridge
-  //    CLIENT (`<name>.client.dart`, the Flutter sibling of `<name>.client.ts`).
-  const written: string[] = [];
+  // 2. FRAMEWORK-SHARED symbol dedup (Dart-codegen hygiene). Framework-owned symbols fold into MANY
+  //    domains, so their generated Dart would be DEFINED once per domain — a package barrel re-exporting
+  //    ≥2 domains then COLLIDES (the historical `hide RelationTuple, EnrollDelegationPayload,
+  //    readSignerDelegationByUser, …` band-aid). THREE kinds are deduped, each identified by the
+  //    framework BRAND (object identity, so a tenant symbol that merely shares a name is never
+  //    misclassified) and emitted EXACTLY ONCE into `nomos_framework.dart`:
+  //      • AGGREGATES — read-model class, typed-id class, by-id accessors (`RelationTuple` auto-added
+  //        to every relation-using domain, `SignerDelegation`/`KeyScope`/… re-exported verbatim);
+  //      • DIRECTIVES — the generated payload class (relate/signer/enroll family). The domain still
+  //        OFFERS them (client offer methods stay per-domain); only the payload TYPE moves to the shared file;
+  //      • QUERIES — the top-level `watch<Q>`/`read<Q>` accessors.
+  //    Per-domain files SKIP each and IMPORT the shared file; clients RE-EXPORT it (Dart de-dups the
+  //    same-library re-export). So a barrel over all domains needs NO `hide` clause.
+  type ModDirective = DomainModule["directives"][number];
+  type ModQuery = NonNullable<DomainModule["queries"]>[number];
+  const frameworkAggById = new Map<string, AggregateHandle>();
+  const frameworkDirById = new Map<string, ModDirective>();
+  const frameworkQueryById = new Map<string, ModQuery>();
   for (const mod of modules) {
-    // Default the read-model allowlist to EVERY aggregate when the domain didn't pin one, so
-    // `<name>.dart` carries a read model per aggregate — the bridge client imports them. A domain
-    // that pins `readModelAggregates` keeps its choice (byte-identical to before this default).
-    const modForDart: DomainModule =
-      mod.readModelAggregates === undefined
-        ? { ...mod, readModelAggregates: mod.aggregates.map((a) => a.id) }
-        : mod;
-    const src = generateDartDomain(modForDart);
+    for (const a of mod.aggregates) if (isFrameworkAggregate(a)) frameworkAggById.set(a.id, a);
+    for (const d of mod.directives) if (isFrameworkDirective(d)) frameworkDirById.set(d.id, d);
+    for (const q of mod.queries ?? []) if (isFrameworkQuery(q)) frameworkQueryById.set(q.id, q);
+  }
+  const frameworkAggs = [...frameworkAggById.values()];
+  const frameworkDirs = [...frameworkDirById.values()];
+  const frameworkQueries = [...frameworkQueryById.values()];
+  const frameworkAggIds: ReadonlySet<string> = new Set(frameworkAggById.keys());
+  const frameworkDirIds: ReadonlySet<string> = new Set(frameworkDirById.keys());
+  const frameworkQueryIds: ReadonlySet<string> = new Set(frameworkQueryById.keys());
+  const hasFrameworkSymbols =
+    frameworkAggs.length > 0 || frameworkDirs.length > 0 || frameworkQueries.length > 0;
+  const FRAMEWORK_FILE = "nomos_framework";
+  const frameworkImportUri = hasFrameworkSymbols ? `${FRAMEWORK_FILE}.dart` : undefined;
+
+  const written: string[] = [];
+
+  const writeGenerated = (fileBase: string, src: string): string => {
     if (!src.includes(DART_PACKAGE_IMPORT)) {
       fail(
-        `generated Dart for domain '${mod.name}' does not carry the expected support import (${DART_PACKAGE_IMPORT}) — codegen_dart header drifted; fix the rewrite in compile_package_main.ts`,
+        `generated Dart for '${fileBase}' does not carry the expected support import (${DART_PACKAGE_IMPORT}) — codegen_dart header drifted; fix the rewrite in compile_package_main.ts`,
       );
     }
-    const p = path.join(dartOut, `${mod.name}.dart`);
+    const p = path.join(dartOut, `${fileBase}.dart`);
     writeFileSync(
       p,
       supportImport === "vendored" ? src.replace(DART_PACKAGE_IMPORT, DART_RELATIVE_IMPORT) : src,
       "utf8",
     );
     written.push(p);
+    return p;
+  };
+
+  // 2a. the shared framework file — the framework aggregates + directives + queries, ONCE. Its own
+  //     surface is emitted in full (no skip). Imported by every domain that folds any framework symbol.
+  if (hasFrameworkSymbols) {
+    const frameworkMod: DomainModule = {
+      name: FRAMEWORK_FILE,
+      domain: FRAMEWORK_FILE,
+      aggregates: frameworkAggs,
+      directives: frameworkDirs,
+      readModelAggregates: frameworkAggs.map((a) => a.id),
+      ...(frameworkQueries.length > 0 ? { queries: frameworkQueries } : {}),
+    };
+    writeGenerated(FRAMEWORK_FILE, generateDartDomain(frameworkMod));
+  }
+
+  // 2b. one generated file per composed domain — the TYPES (`<name>.dart`) + the async bridge
+  //     CLIENT (`<name>.client.dart`, the Flutter sibling of `<name>.client.ts`).
+  for (const mod of modules) {
+    // Default the read-model allowlist to EVERY aggregate when the domain didn't pin one, so
+    // `<name>.dart` carries a read model per aggregate — the bridge client imports them. A domain
+    // that pins `readModelAggregates` keeps its choice (byte-identical to before this default).
+    const modForDart: DomainModule =
+      mod.readModelAggregates === undefined
+        ? { ...mod, readModelAggregates: mod.aggregates.map((a) => a.id) }
+        : mod;
+    // Skip framework symbols this domain folds (they live in the shared file); reference them via the
+    // framework import. Only pass the import when this domain actually folds a framework symbol.
+    const domainFwAggIds = new Set(
+      modForDart.aggregates.filter((a) => frameworkAggIds.has(a.id)).map((a) => a.id),
+    );
+    const domainFwDirIds = new Set(
+      modForDart.directives.filter((d) => frameworkDirIds.has(d.id)).map((d) => d.id),
+    );
+    const domainFwQueryIds = new Set(
+      (modForDart.queries ?? []).filter((q) => frameworkQueryIds.has(q.id)).map((q) => q.id),
+    );
+    const foldsFramework = domainFwAggIds.size > 0 || domainFwDirIds.size > 0 || domainFwQueryIds.size > 0;
+    const domainFrameworkImport = foldsFramework ? frameworkImportUri : undefined;
+    const src = generateDartDomain(modForDart, {
+      skipAggregateIds: domainFwAggIds,
+      skipDirectiveIds: domainFwDirIds,
+      skipQueryIds: domainFwQueryIds,
+      ...(domainFrameworkImport !== undefined ? { frameworkImportUri: domainFrameworkImport } : {}),
+    });
+    writeGenerated(mod.name, src);
 
     const clientSrc = generateDartBridgeClient(modForDart, {
       domainHash,
       interface: packageInterface[modForDart.domain ?? modForDart.name],
       supportImport,
+      ...(domainFrameworkImport !== undefined ? { frameworkImportUri: domainFrameworkImport } : {}),
     });
     const cp = path.join(dartOut, `${mod.name}.client.dart`);
     writeFileSync(cp, clientSrc, "utf8");
@@ -1237,6 +1316,31 @@ async function main(): Promise<void> {
   writeFileSync(pkgPath, text, "utf8");
   const domainHash = sha256HexUtf8(text);
 
+  // ── 2a. the REAL layered RELATION `.usda` set — an additive, deterministic visualization +
+  //        cross-check artifact (usdview / `usdcat --flatten`). One sublayer per domain carrying its
+  //        relation opinions as PRIMS + a root with `subLayers` STRONGEST-FIRST; usdcat composes the
+  //        shared relation types, the compiler's `composeSharedRelationTypes` is the fail-closed guard
+  //        on top. Emitted iff ANY domain declares a relation type. Never feeds the package hash.
+  {
+    const relInputs: RelationLayerInput[] = [];
+    for (const mod of domainModules) {
+      // Per-domain UNCOMPOSED relation types: emit the single module alone (single-domain ⇒ no shared
+      // type ⇒ its own decls, un-unioned — the layers ARE the sublayers usdcat will compose).
+      const one = emitUsd([{ path: `/Nomos/${mod.domain ?? mod.name}`, module: mod }]);
+      const types = one.layers[0]?.nomosRelations?.types;
+      if (types !== undefined && Object.keys(types).length > 0) {
+        relInputs.push({ domain: mod.domain ?? mod.name, types });
+      }
+    }
+    if (relInputs.length > 0) {
+      const emit = emitLayeredRelationUsda(relInputs, cfg.name);
+      const relDir = path.join(outDir, `${cfg.name}.relation-layers`);
+      mkdirSync(relDir, { recursive: true });
+      for (const f of emit.files) writeFileSync(path.join(relDir, f.name), f.text, "utf8");
+      writeFileSync(path.join(relDir, "root.usda"), emit.root, "utf8");
+    }
+  }
+
   // ── 2b. opt-in LAYERED emission — additive artifacts ONLY (the flattened package
   //        above and its domainHash are already written and do not move). The
   //        homomorphism is ASSERTED fail-closed on every layered compile: the

package/src/directive.ts

@@ -71,6 +71,16 @@ export interface Directive<P = unknown> {
   readonly aggregateId: string;
   readonly payloadSchema: z.ZodType<P>;
   readonly plan: (payload: P, ctx: Ports) => PlannedOp[];
+  /**
+   * FRAMEWORK-SHARED brand (Dart-codegen hygiene). Set (by `framework/framework_aggregates.ts`) ONLY on
+   * the framework-owned directive singletons declared in `dsl/src/framework/` (the relate/signer/enroll
+   * family — `relateSubject`, `enrollDelegation`, `advanceSignerEpoch`, …) which fold into MANY domains.
+   * A branded directive's generated Dart PAYLOAD TYPE (`EnrollDelegationPayload`, …) + any minted-create
+   * factory is emitted ONCE per package into the shared `nomos_framework.dart`, NOT re-emitted in each
+   * domain's `.dart` — so a package barrel re-exporting several domains never gets a duplicate payload
+   * class (no hand-maintained `hide` clause). NOT hashed / NOT law: a pure frontend-codegen marker.
+   * Identified by OBJECT IDENTITY, so a tenant directive that merely shares a name is never misclassified. */
+  readonly framework?: true;
   /**
    * Human-readable description of what this directive does — the SINGLE source of
    * the hover-doc text codegen emits onto each generated payload class + ctor (so

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/framework/framework_aggregates.ts

@@ -0,0 +1,138 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth. ⇒ ONE Nomos GitHolon wasm.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * THE FRAMEWORK-SYMBOL REGISTRY (Dart-codegen hygiene).
+ *
+ * Some DSL symbols are FRAMEWORK-owned + framework-SHARED: they are declared once in
+ * `dsl/src/framework/` and folded into MANY tenant domains. Three kinds collide in generated Dart:
+ *
+ *   • AGGREGATES — `RelationTuple` (auto-added to EVERY relation-using domain), plus `SignerDelegation`,
+ *     `KeyScope`, `WrappedKey`, `HomeOwner`, `WorkspaceSelf`, … re-exported verbatim so their events fold.
+ *     Each emits a read-model class + typed-id class + by-id accessors → `RelationTupleReadModel`,
+ *     `SignerDelegationId`, `watchSignerDelegationById`, … DEFINED per domain.
+ *   • DIRECTIVES — the relate/signer/enroll family (`relateSubject`, `enrollDelegation`,
+ *     `advanceSignerEpoch`, …) fold into many domains; each emits a payload class → `EnrollDelegationPayload`
+ *     DEFINED per domain.
+ *   • QUERIES — `signerDelegationByUser`, `relationTuplesByObject`, … emit top-level `watch<Q>`/`read<Q>`
+ *     accessors → `readSignerDelegationByUser`, `watchSignerDelegationByUser` DEFINED per domain.
+ *
+ * A package barrel re-exporting ≥2 domains COLLIDES on every such symbol — the historical band-aid was a
+ * hand-maintained `hide RelationTuple, EnrollDelegationPayload, readSignerDelegationByUser, …` clause on
+ * the tenant barrel. The fix: BRAND the framework SINGLETONS here (once, at module load) so the codegen
+ * emits their Dart surface EXACTLY ONCE per package (into the shared `nomos_framework.dart`) and SKIPS
+ * re-emitting them in each domain. Identification is by OBJECT IDENTITY (the brand rides the branded
+ * singleton), so a tenant symbol that merely SHARES a name is NEVER misclassified.
+ *
+ * FRONTEND CODEGEN ONLY — the brand is never hashed and never enters the USD IR / read manifest / law
+ * (identical guarantee to `readModelAggregates`). Deterministic: the registry is derived from the actual
+ * framework exports, not a hand-kept string list.
+ */
+import type { AggregateHandle } from "../aggregate.js";
+import type { Directive } from "../directive.js";
+import type { QueryDecl } from "../query.js";
+import * as disclosure from "./disclosure.js";
+import * as domainLifecycle from "./domain_lifecycle.js";
+import * as encryptionIdentity from "./encryption_identity.js";
+import * as encryptionScope from "./encryption_scope.js";
+import * as genesis from "./genesis.js";
+import * as home from "./home.js";
+import * as identity from "./identity.js";
+import * as relations from "./relations.js";
+import * as repair from "./repair.js";
+import * as signingIdentity from "./signing_identity.js";
+import * as workspaces from "./workspaces.js";
+
+// Every framework module that DECLARES aggregate / directive / query singletons. Namespace imports so
+// the registry is derived from the real exports (no hand-kept id list to drift).
+const FRAMEWORK_NAMESPACES: ReadonlyArray<Record<string, unknown>> = [
+  disclosure,
+  domainLifecycle,
+  encryptionIdentity,
+  encryptionScope,
+  genesis,
+  home,
+  identity,
+  relations,
+  repair,
+  signingIdentity,
+  workspaces,
+];
+
+function isAggregateHandle(v: unknown): v is AggregateHandle {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    (v as { __isAggregateHandle?: unknown }).__isAggregateHandle === true
+  );
+}
+
+// A finished Directive duck-type ({id, plan, aggregateId}) — the SAME shape `directivesOf` discovers.
+function isDirective(v: unknown): v is Directive {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    typeof (v as { id?: unknown }).id === "string" &&
+    typeof (v as { plan?: unknown }).plan === "function" &&
+    typeof (v as { aggregateId?: unknown }).aggregateId === "string"
+  );
+}
+
+// A finished QueryDecl duck-type ({id, key:[], returns:""}). Distinct from the un-keyed builder
+// (`KeylessQuery.key` is a FUNCTION); here `key` is an array and `returns` a string.
+function isQueryDecl(v: unknown): v is QueryDecl {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    typeof (v as { id?: unknown }).id === "string" &&
+    Array.isArray((v as { key?: unknown }).key) &&
+    typeof (v as { returns?: unknown }).returns === "string"
+  );
+}
+
+const aggregateIds = new Set<string>();
+const directiveIds = new Set<string>();
+const queryIds = new Set<string>();
+
+// Brand every framework singleton at module load. Mutating the readonly `framework` slot on the
+// singleton is intentional: the branded object IS the one that flows through composition
+// (`composeDomainModule` keeps the discovered aggregate/directive/query object references; a tenant
+// re-exports the framework singleton verbatim), so the brand rides object identity everywhere.
+for (const ns of FRAMEWORK_NAMESPACES) {
+  for (const v of Object.values(ns)) {
+    if (isAggregateHandle(v)) {
+      (v as { framework?: true }).framework = true;
+      aggregateIds.add(v.id);
+    } else if (isDirective(v)) {
+      (v as { framework?: true }).framework = true;
+      directiveIds.add(v.id);
+    } else if (isQueryDecl(v)) {
+      (v as { framework?: true }).framework = true;
+      queryIds.add(v.id);
+    }
+  }
+}
+
+export const FRAMEWORK_AGGREGATE_IDS: ReadonlySet<string> = aggregateIds;
+export const FRAMEWORK_DIRECTIVE_IDS: ReadonlySet<string> = directiveIds;
+export const FRAMEWORK_QUERY_IDS: ReadonlySet<string> = queryIds;
+
+/**
+ * TRUE iff this aggregate is a framework-shared singleton whose Dart surface is emitted ONCE per
+ * package (in `nomos_framework.dart`). By the BRAND (object identity) — a tenant aggregate that
+ * happens to share an id is NOT a framework aggregate.
+ */
+export function isFrameworkAggregate(agg: Pick<AggregateHandle, "framework">): boolean {
+  return agg.framework === true;
+}
+
+/** TRUE iff this directive is a framework-shared singleton (its payload class lives in the shared file). */
+export function isFrameworkDirective(d: Pick<Directive, "framework">): boolean {
+  return d.framework === true;
+}
+
+/** TRUE iff this query is a framework-shared singleton (its accessors live in the shared file). */
+export function isFrameworkQuery(q: Pick<QueryDecl, "framework">): boolean {
+  return q.framework === true;
+}

package/src/query.ts

@@ -67,6 +67,16 @@ export interface QueryDecl {
   readonly key: string[];
   /** The aggregate TYPE id the query returns, e.g. `SampleThingAggregate`. */
   readonly returns: string;
+  /**
+   * FRAMEWORK-SHARED brand (Dart-codegen hygiene). Set (by `framework/framework_aggregates.ts`) ONLY on
+   * the framework-owned query singletons declared in `dsl/src/framework/` (`signerDelegationByUser`,
+   * `relationTuplesByObject`, …) which fold into MANY domains. A branded query's generated top-level
+   * `watch<Q>`/`read<Q>` accessors are emitted ONCE per package into the shared `nomos_framework.dart`,
+   * NOT re-emitted in each domain's `.dart` — so a package barrel re-exporting several domains never gets
+   * duplicate accessors (no hand-maintained `hide` clause). NOT hashed / NOT law: a pure frontend-codegen
+   * marker (never enters the read manifest / USD IR). Identified by OBJECT IDENTITY, so a tenant query
+   * that merely shares a name is never misclassified. */
+  readonly framework?: true;
 }
 
 /**

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;
@@ -1060,7 +1061,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";
@@ -865,7 +866,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) ──────────