@githolon/dsl 0.29.0 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.29.0",
+  "version": "0.30.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/codegen_proof.ts

@@ -45,6 +45,7 @@ import type { RelationTypeDecl, Rewrite } from "./relation_schema.js";
 import { finishCount } from "./count.js";
 import { mintedCreateField } from "./workspace_routing.js";
 import { deterministicPorts } from "./ctx.js";
+import { __setDispatchDomain } from "./framework/relations.js";
 import { __resetBirths, __drainBirths } from "./births.js";
 import { __resetAuthoring, __drainAuthoring } from "./authoring.js";
 import { __resetReads, __drainReads } from "./read.js";
@@ -696,13 +697,17 @@ export function resolveGrantableBaseRelations(
 export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstrapLeg | undefined {
   const domain = mod.domain ?? mod.name;
   const directives = mod.directives as Directive<unknown>[];
-  const gated = directives.find(
-    (d) =>
-      d?.requiresRelationGate !== undefined &&
-      typeof d.payloadSchema === "object" &&
-      d.birthsChild !== true &&
-      d.attestationAuthorizedGate === undefined,
-  );
+  const isGatedProvable = (d: Directive<unknown> | undefined): boolean =>
+    d?.requiresRelationGate !== undefined &&
+    typeof d.payloadSchema === "object" &&
+    d.birthsChild !== true &&
+    d.attestationAuthorizedGate === undefined;
+  // PREFER a gated `.creates` as the bootstrap target: a gated create is exactly the shape excluded from the
+  // naive standalone-create leg (isStandaloneCreate), so the bootstrap leg is its ONLY positive proof — seed
+  // authority, then prove the CREATE is admitted. When no gated create exists, fall back to any gated write
+  // (a gated `.mutates`/`.ensures`), so an un-created gated law is still proven.
+  const gated = directives.find((d) => isGatedProvable(d) && d.marker === "creates")
+    ?? directives.find((d) => isGatedProvable(d));
   if (gated === undefined) return undefined;
   const relation = gated.requiresRelationGate!.relation;
 
@@ -935,9 +940,15 @@ function withBirthProbeGlobals<T>(run: () => T): T {
       return h.toString(16).padStart(8, "0").repeat(8);
     },
   };
+  // RELATION-NAMESPACING: a probed seed plan may build a relation OBJECT TOKEN (`selfWorkspace()`),
+  // which qualifies its type by the dispatching domain. The proof generator's STATIC probe reads the
+  // relation name + subject entry key off the drained ops (never the object string), so a sentinel
+  // dispatch domain is enough to let the token resolve without throwing — no real domain is needed.
+  __setDispatchDomain("proof");
   try {
     return run();
   } finally {
+    __setDispatchDomain(undefined);
     if (had && prior !== undefined) g.nomos = prior; else delete g.nomos;
   }
 }
@@ -1185,13 +1196,17 @@ export interface ProofLegs {
  *  The SINGLE source of the create-leg selection — `generateTsProof` (the .mts marker) and
  *  `proofLegsIndex` (the per-domain index) both call this, so the offline lane proves any domain the
  *  same way the generated proof proves its primary one. */
-/** A `.creates` directive the proof can DRIVE from a synthesized sample offline: not a `.births()` (a birth
- *  is the child-birth lane), not ATTESTATION-AUTHORIZED (needs a signed §3 quote no synthesizer can produce —
- *  e.g. the home law's `recordShare`). Those are NOT standalone-provable offline; the domain proves via its
- *  child-birth leg / compile-valid instead. */
+/** A `.creates` directive the proof can DRIVE from a synthesized sample offline WITH NO SEEDED AUTHORITY: not
+ *  a `.births()` (a birth is the child-birth lane), not ATTESTATION-AUTHORIZED (needs a signed §3 quote no
+ *  synthesizer can produce — e.g. the home law's `recordShare`), and NOT AUTHZ-GATED (`.requires(R)` — a
+ *  gated create dispatched with no seeded authority is REFUSED at the gate; its metadata already says it
+ *  needs authority, so the naive standalone leg must not touch it — it is proven POSITIVELY by the
+ *  relation-bootstrap leg / the born-child genesis instead). Those are NOT standalone-provable offline; the
+ *  domain proves via its bootstrap / child-birth / compile-valid legs instead. */
 function isStandaloneCreate(d: Directive<unknown> | undefined): boolean {
   return d?.marker === "creates" && typeof d.payloadSchema === "object"
-    && d.birthsChild !== true && d.attestationAuthorizedGate === undefined;
+    && d.birthsChild !== true && d.attestationAuthorizedGate === undefined
+    && d.requiresRelationGate === undefined;
 }
 
 export function proofLegsForModule(mod: DomainModule): ProofLegs | null {
@@ -1545,19 +1560,94 @@ function generateBirthOnlyProof(
   return out.join("\n");
 }
 
+/**
+ * THE BOOTSTRAP-ONLY PROOF (gated-create isolation): a package whose ONLY creating write is AUTHZ-GATED
+ * (`.creates(...).requires(R)` — co2's estate `createSite`). It has no ungated standalone create to dispatch
+ * naively (that would be REFUSED at the gate with no seeded authority) and no `.births()` genesis. So the
+ * proof deploys the law, connects, and drives the RELATION-BOOTSTRAP leg as its primary write: seed authority
+ * (layers 1-3), THEN prove the gated create is ADMITTED — the ordering (seed BEFORE the gated dispatch) is
+ * correct by construction. If authority genuinely can't be seeded, the leg emits the loud diagnostic (never a
+ * false green). The offline runner proves the same leg locally (`githolon proof`); this `.mts` is `--live`.
+ */
+function generateBootstrapOnlyProof(
+  mod: DomainModule,
+  opts: TsProofOptions,
+  primaryLegs: ProofLegs,
+): string {
+  const domain = mod.domain ?? mod.name;
+  const factory = tsClientFactoryName(domain);
+  const hashConst = tsHashConstName(opts.packageName);
+  const rb = primaryLegs.relationBootstrap;
+  if (rb === undefined) {
+    // Only reached defensively — the caller gates on relationBootstrap !== undefined.
+    throw new Error(`domain '${domain}' has a gated create but no relation-bootstrap leg to prove it (no seedable authority)`);
+  }
+  const slug =
+    opts.packageName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 24) || "domain";
+  const legsMarker = JSON.stringify(primaryLegs);
+  let step = 0;
+  const n = () => ++step;
+  const out: string[] = [];
+  out.push(
+    `// AUTO-GENERATED by nomos-compile — the RUNNABLE PROOF for package "${opts.packageName}",`,
+    `// synthesized from the domain's OWN law. This package's ONLY creating write is AUTHZ-GATED`,
+    `// (\`${domain}/${rb.gatedDirectiveId}\` .requires("${rb.relation}")), so the proof SEEDS authority first,`,
+    `// then proves the gated create is admitted — never a naive dispatch the gate would refuse. Reshape the`,
+    `// law, recompile, and this proof reshapes itself — no test rewriting. Run it:`,
+    `//`,
+    `//   npx githolon proof        (offline legs on a local holon)`,
+    `//   npx githolon proof --live (or: npx tsx build/${opts.packageName}.proof.mts — the full cloud loop)`,
+    `//`,
+    `// Regenerated on every compile; do not edit.`,
+    `// @nomos-proof-legs ${legsMarker}`,
+    `import { readFileSync } from "node:fs";`,
+    `import { connect, encodeIntentOfferBytes } from "@githolon/client";`,
+    `import { ${factory}, ${hashConst} } from "./${opts.packageName}.client.ts";`,
+    `void connect; void encodeIntentOfferBytes; void ${factory};`,
+    ``,
+    `const CLOUD = (process.env.NOMOS_CLOUD || "https://nomos.captainapp.co.uk").replace(/\\/+$/, "");`,
+    `const WS = process.env.NOMOS_WS || ${JSON.stringify(slug + "-proof-")} + Math.random().toString(36).slice(2, 8);`,
+    ``,
+    ...v2IdentityAndCleanupPreamble(opts, hashConst, n),
+    ``,
+    `// ${n()}. connect + bind the GENERATED typed client (the relation-bootstrap leg drives it with an actor)`,
+    `const holon = await connect({ cloud: CLOUD, workspace: WS, clientId: "proof-1" });`,
+    `ok(\`web client connected — ${factory} bound (replica \${holon.replica.slice(0, 6)}…)\`);`,
+    ``,
+    // The SAME relation-bootstrap emitter the standalone proof uses — seed authority, then prove the GATED
+    // CREATE is admitted (layers 1-3; a speculative seed-path degrades to a diagnostic, never a false green).
+    ...relationSeedLegLines(rb, factory, n),
+    `console.log(\`\\nALL GREEN — generated proof for "${opts.packageName}": deploy → seed authority → gated create ${rb.gatedDirectiveId} admitted (\${WS})\`);`,
+    ``,
+    ...v2CatchFinally(),
+    ``,
+  );
+  return out.join("\n");
+}
+
 export function generateTsProof(modules: readonly DomainModule[], opts: TsProofOptions): string {
-  // PRIMARY-DOMAIN SELECTION: the live `.mts` drives a STANDALONE create when the package has one (the full
-  // deploy → write → query → sync → cloud loop). A BIRTH-ONLY package (every `.creates` is also a `.births()`
-  // — the home/estate composable shape) has no standalone create to drive, so the primary becomes the first
-  // `.births()` domain and the live `.mts` drives the birth as its primary write. Either way, the marker =
-  // the primary domain's FULL legs (so the offline runner + the index never describe different directives).
+  // PRIMARY-DOMAIN SELECTION: the live `.mts` drives a STANDALONE (ungated) create when the package has one
+  // (the full deploy → write → query → sync → cloud loop). Else a BIRTH package (`.births()`) drives the
+  // birth. Else a GATED-CREATE package — whose only creating write `.requires(R)` (co2's estate `createSite`)
+  // — drives the RELATION-BOOTSTRAP leg as its primary write: seed authority, THEN the gated create is
+  // admitted (never a naive first dispatch that the gate would refuse). Either way, the marker = the primary
+  // domain's FULL legs (so the offline runner + the index never describe different directives).
   const hasStandaloneCreate = (m: DomainModule): boolean =>
     (m.directives as Directive<unknown>[]).some((d) => isStandaloneCreate(d));
   const hasBirth = (m: DomainModule): boolean => birthDirectiveOf(m) !== undefined;
-  const mod = modules.find(hasStandaloneCreate) ?? modules.find(hasBirth);
+  const isBootstrapProvable = (m: DomainModule): boolean => {
+    try { return discoverRelationBootstrapLeg(m) !== undefined; } catch { return false; }
+  };
+  const mod = modules.find(hasStandaloneCreate) ?? modules.find(hasBirth) ?? modules.find(isBootstrapProvable);
   if (mod === undefined) {
+    // No provable creating write anywhere. If a GATED create exists but its authority can't be seeded, surface
+    // the loud bootstrap diagnostic (never a false green); else the generic "add a .creates" remedy.
+    const gapMod = modules.find((m) => diagnoseRelationBootstrapGap(m) !== undefined);
+    const gap = gapMod !== undefined ? diagnoseRelationBootstrapGap(gapMod) : undefined;
     throw new Error(
-      `no .creates directive in any domain — a generated proof needs one creating write (or a .births() birth directive); add a directive(...).creates(...) (test/e2e.mts remains the hand-authored lane)`,
+      gap !== undefined
+        ? `no proof could be synthesized: ${gap}`
+        : `no .creates directive in any domain — a generated proof needs one creating write (or a .births() birth directive); add a directive(...).creates(...) (test/e2e.mts remains the hand-authored lane)`,
     );
   }
   const domain = mod.domain ?? mod.name;
@@ -1565,18 +1655,24 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   const hashConst = tsHashConstName(opts.packageName);
   // THE MARKER (since 0.5.0) + the per-domain index are ONE synthesis (`legsForDomain`) — the proof body, its
   // marker, and the index can never describe different directives. The primary domain's legs carry whichever
-  // of standalone / child-birth it has.
+  // of standalone / child-birth / relation-bootstrap it has.
   const primaryLegs = legsForDomain(mod, modules);
   const childBirth = primaryLegs.childBirth;
 
-  // The standalone-create lane (when the primary has one). A birth-only primary skips this — its primary
-  // write is the child-birth leg below.
-  const createDir = (mod.directives as Directive<unknown>[]).find(
-    (d) => d?.marker === "creates" && typeof d.payloadSchema === "object" && d.birthsChild !== true,
-  );
+  // The standalone-create lane needs an UNGATED create (isStandaloneCreate — never a gated/birth/attestation
+  // create, which the gate would refuse dispatched with no seeded authority). Absent one, the primary write
+  // is the birth leg (a `.births()` domain) or the relation-bootstrap leg (a gated-create domain).
+  const createDir = (mod.directives as Directive<unknown>[]).find((d) => isStandaloneCreate(d));
   if (createDir === undefined) {
-    // BIRTH-ONLY PRIMARY: emit a birth-shaped proof (no standalone create/query/count/concurrency legs).
-    return generateBirthOnlyProof(mod, modules, opts, primaryLegs);
+    // BIRTH-ONLY PRIMARY: emit a birth-shaped proof (the birth replays genesis, seating authority, then the
+    // born child self-validates — a gated child-domain create is proven INSIDE the born child context).
+    if (primaryLegs.childBirth !== undefined) return generateBirthOnlyProof(mod, modules, opts, primaryLegs);
+    // BOOTSTRAP-ONLY PRIMARY: the only creating write is GATED — deploy, then seed authority + prove the
+    // gated create is admitted (the relation-bootstrap leg is its ONLY positive proof).
+    if (primaryLegs.relationBootstrap !== undefined) return generateBootstrapOnlyProof(mod, opts, primaryLegs);
+    // A gated create with no seedable authority: loud diagnostic (compile skips the proof, law still ships).
+    const gap = diagnoseRelationBootstrapGap(mod);
+    throw new Error(gap !== undefined ? `no proof could be synthesized for '${domain}': ${gap}` : `domain '${domain}' has no provable creating write`);
   }
   const agg = (mod.aggregates as AggregateHandle[]).find((a) => a.id === createDir.aggregateId);
   if (agg === undefined) {

package/src/engine_entry.ts

@@ -53,7 +53,8 @@
  */
 import { executeDirectiveToIntent } from "./wire_encode.js";
 import { expandCapabilityExports } from "./capability_exports.js";
-import { RelationTuple } from "./framework/relations.js";
+import { RelationTuple, __setDispatchContext } from "./framework/relations.js";
+import { isRelationTypeDecl } from "./relation_schema.js";
 import { synthesizePreconditionInvariants } from "./precondition.js";
 import { generateOpenApiFragment, mergeOpenApiFragments, type OpenApiDoc } from "./codegen_openapi.js";
 import type { QueryDecl } from "./query.js";
@@ -263,6 +264,12 @@ interface DomainSlice {
   aggInvariants: Map<string, AggregateInvariantFn>;
   /** workspace-invariant id → its declaration (#266 — `reads`/`assert` bodies ship HERE). */
   wsInvariants: Map<string, WorkspaceInvariantDecl>;
+  /**
+   * RELATION-NAMESPACING classification: `<type>#<relation>` for every LOCAL (non-`.asGlobal()`) authored
+   * relation this domain declares — the set a bare `writeTuple` object auto-qualifies against. A GLOBAL
+   * type's relations (governance/signer/read-visibility) are EXCLUDED so their bare objects stay bare.
+   */
+  qualifiableRelations: Set<string>;
 }
 
 /** Build one domain's slice from its merged module exports (the original scans). */
@@ -370,7 +377,18 @@ function buildDomainSlice(mod: DomainModuleExports): DomainSlice {
     for (const w of synthesizePreconditionInvariants(directive)) wsInvariants.set(w.id, w);
   }
 
-  return { registry, deriveds, combineds, invariants, aggInvariants, wsInvariants };
+  // ── RELATION-NAMESPACING classification — the LOCAL non-global `(type,relation)` set (by shape) ──
+  // A bare `writeTuple({object:"<type>:<id>", relation})` auto-qualifies iff `<type>#<relation>` is here.
+  // Global types (`.asGlobal()` — governance `workspace`, signer `identity`) are excluded so their bare
+  // objects stay bare; the synthesized read-visibility `workspace` caps are never authored relationTypes,
+  // so they are absent here too (their bare grants stay bare — the read gate hardcodes `workspace:self`).
+  const qualifiableRelations = new Set<string>();
+  for (const v of Object.values(mod)) {
+    if (!isRelationTypeDecl(v) || v.global === true) continue;
+    for (const rel of v.relations.keys()) qualifiableRelations.add(`${v.type}#${rel}`);
+  }
+
+  return { registry, deriveds, combineds, invariants, aggInvariants, wsInvariants, qualifiableRelations };
 }
 
 /**
@@ -797,7 +815,20 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
       throw new Error(`engine plan: no directive registered for (${domain}, ${directiveId})`);
     }
     const ctx = portsFromHost(job.capturedPorts?.principal);
-    const wire = executeDirectiveToIntent(entry.directive, entry.agg, intent.payload as never, ctx);
+    // RELATION-NAMESPACING: publish the dispatching domain + its LOCAL non-global `(type,relation)`
+    // classification, so a plan's `writeTuple` object lands on the SAME qualified id the compiler wrote
+    // onto the `.requires(R)` gate — a bare `"workspace:self"` for a local relation AUTO-QUALIFIES to
+    // `<domain>__workspace:self`; a global/read-visibility/unknown relation's bare object stays bare; a
+    // token qualifies explicitly. (`module.domain` === `intent.domain`.) Synchronous plan execution ⇒
+    // cleared in the `finally`.
+    const slice = sliceOf(domain)!;
+    __setDispatchContext({ domain, qualifiable: slice.qualifiableRelations });
+    let wire: ReturnType<typeof executeDirectiveToIntent>;
+    try {
+      wire = executeDirectiveToIntent(entry.directive, entry.agg, intent.payload as never, ctx);
+    } finally {
+      __setDispatchContext(undefined);
+    }
     // Emit {events, strikes} ONLY when a strike is present, else the bare event array —
     // so every strikes-free directive canonicalizes byte-identically to the pre-strikeout contract.
     // The OBSERVED ENDORSE footprint (Slice B) rides the object form too — TRANSIENT (the gate reads

package/src/framework/relations.ts

@@ -47,6 +47,73 @@ import { directive } from "../directive.js";
 import { set, setEntry, withMarker, type PlannedOp } from "../ops.js";
 import { query } from "../query.js";
 import { endorsementOf, type AttributionPrincipal, type EndorsedAuthority } from "../principal_evidence.js";
+import { isRelationObjectToken, qualifyRelationType, type RelationObjectToken } from "../relation_schema.js";
+
+// ─────────────────────────────── the dispatch context (relation-namespacing) ───────────────────────────────
+//
+// The engine entry publishes the DISPATCHING domain + its own relation-schema classification around each
+// plan dispatch (`engine_entry.ts::plan`), so a `writeTuple` object lands on the SAME qualified id the
+// compiler wrote onto the `.requires(R)` gate — WITHOUT the author naming a domain. Single-threaded
+// synchronous dispatch ⇒ no re-entrancy; cleared in a `finally`.
+//
+// THE DISAMBIGUATION (the maintainer's rule — the natural bare-string code must be correct): a bare
+// `writeTuple({ object:"workspace:self", relation:R })` is classified by the `(type, relation)` pair
+// against the dispatching domain's OWN schema:
+//   - `(type, R)` is a LOCAL (non-`.asGlobal()`) authored relation of this domain  → AUTO-QUALIFY the
+//     object type to `<domain>__<type>` (it matches the qualified gate object by construction).
+//   - `(type, R)` is a GLOBAL type's relation (governance/signer/read-visibility)   → leave BARE.
+//   - `(type, R)` matches NOTHING in this domain's schema (unknown / per-record)     → leave BARE (passthrough).
+// A relation OBJECT TOKEN (`selfWorkspace()`/`selfObject(decl)`) is the OPTIONAL explicit sugar — it ALWAYS
+// qualifies its type by the dispatching domain (the author's explicit intent), no classification needed.
+
+interface DispatchContext {
+  /** The dispatching domain key — the qualifier (`module.domain === intent.domain`). */
+  readonly domain: string;
+  /** `<type>#<relation>` for every LOCAL non-global authored relation of this domain — the qualify set. */
+  readonly qualifiable: ReadonlySet<string>;
+}
+
+const EMPTY_QUALIFIABLE: ReadonlySet<string> = new Set<string>();
+let _ctx: DispatchContext | undefined;
+
+/** Engine-entry hook: publish the dispatching domain + its qualifiable `(type,relation)` classification. */
+export function __setDispatchContext(ctx: DispatchContext | undefined): void {
+  _ctx = ctx;
+}
+
+/**
+ * Engine-entry / probe hook: set only the dispatching domain (no schema classification). Used where the
+ * classification is unavailable (the proof generator's static plan probe): a token still resolves, and a
+ * bare string stays bare (the probe reads the relation/subject off the ops, never the object string).
+ */
+export function __setDispatchDomain(domain: string | undefined): void {
+  _ctx = domain === undefined ? undefined : { domain, qualifiable: EMPTY_QUALIFIABLE };
+}
+
+/** Resolve a `writeTuple`/`removeTuple` object for a given relation (token → qualify; string → classify). */
+function resolveTupleObject(object: string | RelationObjectToken, relation: string): string {
+  // A TOKEN is explicit sugar — always qualify its type by the dispatching domain.
+  if (typeof object !== "string") {
+    if (!isRelationObjectToken(object)) {
+      throw new Error(`writeTuple: object must be a string or a relation object token; got ${JSON.stringify(object)}`);
+    }
+    if (_ctx === undefined || _ctx.domain === "") {
+      throw new Error(
+        "writeTuple: a relation object token was used outside a plan dispatch (no dispatching domain to " +
+          "qualify by). Tokens (selfWorkspace()/selfObject()) resolve only inside a directive plan.",
+      );
+    }
+    return `${qualifyRelationType(_ctx.domain, object.type)}:${object.id}`;
+  }
+  // A PLAIN STRING is classified by `(type, relation)` against the dispatching domain's schema.
+  const colon = object.indexOf(":");
+  if (colon < 0 || _ctx === undefined) return object; // malformed / no context ⇒ verbatim
+  const type = object.slice(0, colon);
+  if (_ctx.qualifiable.has(`${type}#${relation}`)) {
+    return `${qualifyRelationType(_ctx.domain, type)}${object.slice(colon)}`;
+  }
+  return object; // global / unknown / per-record ⇒ BARE
+}
 
 /** Tuple subject lifecycle — the same vocabulary the kernel read drops a non-active leaf by. */
 export const RELATION_STATUSES = ["active", "revoked"] as const;
@@ -139,7 +206,13 @@ function compact(obj: Record<string, unknown>): RelationSubjectLeaf {
 }
 
 interface WriteTupleInput {
-  object: string;
+  /**
+   * The tuple OBJECT `<type>:<id>`. A plain STRING passes through verbatim (the bare lane — a global
+   * `workspace:self`, a read-visibility grant, an already-qualified literal). A relation OBJECT TOKEN
+   * (`selfWorkspace()`/`selfObject(decl)`/`objectOf(decl,id)`) qualifies its type by the dispatching
+   * domain at plan runtime — so a seed for a NAMESPACED tenant type matches its qualified gate object.
+   */
+  object: string | RelationObjectToken;
   relation: string;
   /**
    * THE AUTHORITY SINK (the endorse model — security_model.md): who is granted the relation. A plain
@@ -166,7 +239,11 @@ function lowerTuple(
     revokedAt?: string | undefined;
   },
 ): PlannedOp[] {
-  const rt = instance(RelationTuple, relationTupleInstanceId(p.object, p.relation));
+  // Resolve the object ONCE (token → qualified string, or a plain string verbatim) and use it for BOTH
+  // the deterministic aggregate id AND the stored `object` field, so the tuple's reltuple id matches the
+  // qualified gate object's (`identity/src/relations.rs::reltuple_id`).
+  const object = resolveTupleObject(p.object, p.relation);
+  const rt = instance(RelationTuple, relationTupleInstanceId(object, p.relation));
   // MATERIALISE PrincipalEvidence subjects/grantedBy → the raw principal (the endorse model). The
   // subject's endorsement is recorded on the setEntry op so the discovery harvest lifts it into
   // nomosFlowGate.endorse; grantedBy is free attribution (materialised, not gated).
@@ -192,7 +269,7 @@ function lowerTuple(
   return [
     // upsert the aggregate head (first relate creates it); without this the referential
     // gate would reject a setEntry on an absent id.
-    withMarker(set(rt, "object", p.object), "ensures"),
+    withMarker(set(rt, "object", object), "ensures"),
     set(rt, "relation", p.relation),
     subjectE ? { ...subjectEntry, endorsement: { facet: subjectE.facet, reason: subjectE.reason } } : subjectEntry,
   ];

package/src/framework/signing_identity.ts

@@ -63,10 +63,16 @@ import {
  * (`allow: [key()]`, never a userset/wildcard: a `key:*` would let any key claim to author
  * as anyone). A workspace that admits signed authorship composes this into its law.
  */
-export const identityRelations = relationType("identity").relation("signer", {
-  rewrite: self(),
-  allow: [key()],
-});
+export const identityRelations = relationType("identity")
+  // GLOBAL (un-namespaced) — relation-namespacing opt-out. The kernel hardcodes bare
+  // `identity:<principal>` (`executor::signer_object`) for captured-principal signer verification, so
+  // this type MUST stay bare (qualifying it would need a Rust change). `signerObject()` writes the bare
+  // string object; no token, no migration.
+  .asGlobal()
+  .relation("signer", {
+    rewrite: self(),
+    allow: [key()],
+  });
 
 /** The Zanzibar OBJECT for a principal's signer relation — `identity:<principal>` (the gate mirrors
  *  this as `executor::signer_object`; the subject is `key:<sha256hex(pubkey)>`). */

package/src/framework/workspaces.ts

@@ -156,6 +156,13 @@ export const workspaceSelfWriteOnce = workspaceInvariant("WorkspaceSelfWriteOnce
 // born platform with no name plumbing. (A pure tenant runs no governance ⇒ no schema ⇒ the gate is
 // inert there; an un-backfilled workspace with no admin tuple refuses fail-closed.)
 export const workspaceRelations = relationType("workspace")
+  // GLOBAL (un-namespaced) — relation-namespacing opt-out. The kernel/host address this governance type
+  // by its BARE name (`workspace:self#admin`, the operated-probe `expand(workspace:root, admin)`), so it
+  // MUST stay bare (qualifying it would need a Rust change). grantAdmin/grantCreation write bare
+  // `workspace:self` string tuples + gate on the bare object — all consistent, byte-identical, no
+  // migration. (A TENANT that wants a workspace-scoped role uses a namespaced `relationType("workspace")`
+  // + a `selfWorkspace()` seed; only THIS framework governance type is global.)
+  .asGlobal()
   .relation("admin", { rewrite: self(), allow: [user(), key()] })
   .relation("creator", { rewrite: self(), allow: [user(), key()] })
   .relation("platformCreator", { rewrite: self(), allow: [user(), key()] });

package/src/index.ts

@@ -413,6 +413,16 @@ export {
   anyUser,
   group,
   DEFAULT_RELATION_CAPS,
+  // RELATION-TYPE NAMESPACING — the qualifier helpers + the seed-object tokens (selfWorkspace()/
+  // selfObject()/objectOf()) that make a namespaced tenant seed match its qualified gate object.
+  RELATION_TYPE_DELIMITER,
+  qualifyRelationType,
+  qualifiedTypeId,
+  isRelationObjectToken,
+  selfWorkspace,
+  selfObject,
+  objectOf,
+  type RelationObjectToken,
   type RelationTypeDecl,
   type RelationTypeBuilder,
   type RelationDefAst,

package/src/relation_schema.ts

@@ -91,6 +91,19 @@ export interface RelationTypeDecl {
   readonly relations: ReadonlyMap<string, RelationDefAst>;
   /** Per-type cap override; absent ⇒ the schema/default caps apply. */
   readonly caps?: RelationCaps;
+  /**
+   * GLOBAL (un-namespaced) type — the RELATION-NAMESPACING opt-out. A tenant relation type is
+   * QUALIFIED by its owning domain key at compile (`estate` → `estate__estate`) so two domains that
+   * each declare the same bare type never collide (kernel last-wins schema merge). A `global` type is
+   * EXEMPT: its id, gate object, and tuple object all stay BARE. Reserved for the KERNEL-COUPLED
+   * framework types the kernel hardcodes by bare name and which we cannot qualify without a Rust
+   * change: the governance `workspace` (`workspace:self#admin`, the operated-probe expand), the signer
+   * `identity` (`executor::signer_object` = bare `identity:<principal>`), and the synthesized
+   * read-visibility `workspace` (the read gate hardcodes `ObjectRef::new("workspace","self")`). A
+   * global-only package emits byte-identically to the pre-namespacing compiler (no era key). Default
+   * (absent ⇒ namespaced) is the safe posture — a tenant NEVER wants a bare, collision-prone id.
+   */
+  readonly global?: boolean;
   /** Brand so a plain object is never mistaken for a declaration (mirrors workspaceInvariant). */
   readonly __isRelationType: true;
 }
@@ -99,6 +112,72 @@ export function isRelationTypeDecl(v: unknown): v is RelationTypeDecl {
   return typeof v === "object" && v !== null && (v as { __isRelationType?: unknown }).__isRelationType === true;
 }
 
+// ─────────────────────────────── relation-type NAMESPACING ───────────────────────────────
+
+/**
+ * The relation-type QUALIFIER delimiter. COLON-FREE by law: the kernel splits an object address on
+ * the FIRST colon (`identity/src/relations.rs::ObjectRef::parse` → `split_once(':')`), so a `:`-bearing
+ * qualifier (`estate::workspace`) would corrupt the (type,id) split. `__` is the ratified delimiter.
+ */
+export const RELATION_TYPE_DELIMITER = "__";
+
+/** Qualify a bare relation type by its owning domain key: `("estate","workspace") → "estate__workspace"`. */
+export function qualifyRelationType(domainKey: string, type: string): string {
+  return `${domainKey}${RELATION_TYPE_DELIMITER}${type}`;
+}
+
+/**
+ * The qualified id a decl serializes under, given its owning domain key. A `global` decl (a kernel-
+ * coupled framework type — see {@link RelationTypeDecl.global}) is NEVER qualified; everything else is.
+ */
+export function qualifiedTypeId(domainKey: string, decl: RelationTypeDecl): string {
+  return decl.global === true ? decl.type : qualifyRelationType(domainKey, decl.type);
+}
+
+// ─────────────────────────────── relation OBJECT tokens (the namespacing-aware seed lane) ───────────────────────────────
+
+/**
+ * A relation OBJECT token — the namespacing-aware replacement for a hardcoded `"workspace:self"` STRING
+ * in a plan's `writeTuple({ object })`. A plain string passes through the tuple lowering VERBATIM (the
+ * BARE lane — governance's global `workspace:self`, a read-visibility grant, an already-qualified
+ * literal). A TOKEN carries only the (type, id); the framework qualifies its `type` by the DISPATCHING
+ * domain at plan runtime (`framework/relations.ts::writeTuple`), producing the SAME `<domain>__<type>`
+ * the compiler wrote onto the schema + gate object. Authors of a seed for a NAMESPACED tenant type swap
+ * `object: "workspace:self"` → `object: selfWorkspace()` — the qualifier flows through, they name no
+ * domain. (A namespaced type's tuple object MUST match its qualified gate object or the gate finds no
+ * tuple; the token is what guarantees it from one place.)
+ */
+export interface RelationObjectToken {
+  readonly __isRelationObjectToken: true;
+  /** The BARE object type (`workspace`, or a per-record aggregate type) — qualified at plan runtime. */
+  readonly type: string;
+  /** The object id (`self` for a workspace-scope object, or a record id). */
+  readonly id: string;
+}
+
+export function isRelationObjectToken(v: unknown): v is RelationObjectToken {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    (v as { __isRelationObjectToken?: unknown }).__isRelationObjectToken === true
+  );
+}
+
+/** The workspace-scope object token `<domain>__workspace:self` — the default gate-object shape, qualified. */
+export function selfWorkspace(): RelationObjectToken {
+  return { __isRelationObjectToken: true, type: "workspace", id: "self" };
+}
+
+/** The workspace-scope object token for a specific relation type: `selfObject(EstateRelations)`. */
+export function selfObject(decl: RelationTypeDecl): RelationObjectToken {
+  return { __isRelationObjectToken: true, type: decl.type, id: "self" };
+}
+
+/** A PER-RECORD object token `<domain>__<type>:<id>` (the objectFrom gate's tuple side). */
+export function objectOf(decl: RelationTypeDecl, id: string): RelationObjectToken {
+  return { __isRelationObjectToken: true, type: decl.type, id };
+}
+
 // ─────────────────────────────── the rewrite combinators ───────────────────────────────
 
 /** `_this` — the directly-stored tuples (and their recursive userset subjects). */
@@ -174,6 +253,13 @@ export interface RelationTypeBuilder extends RelationTypeDecl {
    * tuples — legal but inert; a purely-`computed`/`from` relation needs no `allow`.
    */
   relation(name: string, opts?: { rewrite?: Rewrite; allow?: AllowedSubject[] }): RelationTypeBuilder;
+  /**
+   * Mark this type GLOBAL (un-namespaced) — the relation-namespacing opt-out (see
+   * {@link RelationTypeDecl.global}). RESERVED for kernel-coupled framework types the kernel hardcodes
+   * by bare name; a tenant type must NOT call this (it would re-introduce the cross-domain collision
+   * namespacing exists to dissolve).
+   */
+  asGlobal(): RelationTypeBuilder;
 }
 
 /**
@@ -206,6 +292,11 @@ export function relationType(type: string, caps?: Partial<RelationCaps>): Relati
       relations.set(name, { rewrite: opts?.rewrite ?? null, allowed });
       return builder;
     },
+    asGlobal(): RelationTypeBuilder {
+      // Mutate in place so a later `.relation(...)` chain still returns the SAME (now-global) builder.
+      (builder as { global?: boolean }).global = true;
+      return builder;
+    },
   };
   return builder;
 }

package/src/usd.ts

@@ -42,7 +42,7 @@ import {
 import type { WireSchema, WireRefMode } from "./wire.js";
 import type { DomainModule } from "./codegen_dart.js";
 import { domainInterface } from "./shape_compat.js";
-import { relationType, user, key, anyUser } from "./relation_schema.js";
+import { relationType, user, key, anyUser, qualifiedTypeId, qualifyRelationType } from "./relation_schema.js";
 import { harvestPrincipalFlows } from "./wire_encode.js";
 
 /** The referential marker of a directive prim (kernel `RefMode` wire string). */
@@ -260,6 +260,21 @@ export interface UsdLayer {
     readonly v: 1;
     readonly requires: Record<string, { readonly relation: string; readonly object: string }>;
   };
+  /**
+   * THE RELATION-TYPE NAMESPACE ERA KEY (relation-namespacing). Present IFF a layer qualified ≥1
+   * (non-global) `relationType` by its owning domain key (`estate` → `estate__workspace`), so two
+   * domains in one package that each declare the same bare type no longer collide at the kernel's
+   * last-wins schema merge. `types` is the SORTED set of qualified ids this layer produced; `delimiter`
+   * is the ratified colon-free `"__"` (the kernel splits object addresses on the first colon). OMITTED
+   * for a layer that declares no relation type OR only GLOBAL (kernel-coupled framework) types — those
+   * emit BYTE-IDENTICALLY to the pre-namespacing compiler (the era rule; the marker is a witness, the
+   * kernel needs no new arm because the qualification is already baked into the `nomosRelations` ids).
+   */
+  readonly nomosRelationNamespace?: {
+    readonly v: 1;
+    readonly delimiter: string;
+    readonly types: readonly string[];
+  };
   /**
    * THE CROSS-CUSTODY ATTESTATION GATE (home_holons §3/§5). Present IFF ≥1 directive declares
    * `.attestationAuthorized()`: the SORTED set of their ids. A directive named here is authorized by a
@@ -632,6 +647,7 @@ function readProjectionForModule(mod: DomainModule, manifest: CanonicalManifest)
  */
 function serializeRelationSchema(
   decls: readonly import("./relation_schema.js").RelationTypeDecl[],
+  domainKey: string,
 ): UsdLayer["nomosRelations"] {
   if (decls.length === 0) return undefined;
   type AllowedW = { kind: string; type?: string; ns?: string; relation?: string };
@@ -639,10 +655,15 @@ function serializeRelationSchema(
     a.kind === "direct" ? `direct:${a.type}` : a.kind === "wildcard" ? "wildcard" : `userset:${a.type}#${a.relation}`;
   const byType = new Map<string, { relations: Map<string, { rewrite: unknown; allowed: unknown[] }>; caps?: { maxDepth: number; maxFanout: number } }>();
   for (const d of decls) {
-    let entry = byType.get(d.type);
+    // RELATION-TYPE NAMESPACING: a tenant type keys under `<domainKey>__<type>` so two domains that each
+    // declare the same bare type never collide at the kernel's last-wins schema merge; a `global` type
+    // (kernel-coupled framework type) keys BARE. `computed`/`ttu` targets inside a rewrite are
+    // type-RELATIVE relation names resolved on the (now-qualified) type — so no rewrite rewrite is needed.
+    const typeId = qualifiedTypeId(domainKey, d);
+    let entry = byType.get(typeId);
     if (entry === undefined) {
       entry = { relations: new Map(), ...(d.caps ? { caps: d.caps } : {}) };
-      byType.set(d.type, entry);
+      byType.set(typeId, entry);
     } else if (d.caps !== undefined) {
       if (entry.caps !== undefined && (entry.caps.maxDepth !== d.caps.maxDepth || entry.caps.maxFanout !== d.caps.maxFanout)) {
         throw new Error(`relationType("${d.type}"): conflicting caps across declarations`);
@@ -682,7 +703,10 @@ function synthesizeReadRelationTypes(
     if (a.requiresRead !== undefined) caps.add(a.requiresRead);
   }
   if (caps.size === 0) return [];
-  const builder = relationType("workspace");
+  // GLOBAL (un-namespaced): the read gate hardcodes `ObjectRef::new("workspace","self")` in Rust
+  // (`wasm_git_holon.rs`), so the synthesized read-visibility `workspace` type MUST stay bare — it is
+  // NOT namespaced by the owning domain (site-6 exemption; a Rust change would be needed to qualify it).
+  const builder = relationType("workspace").asGlobal();
   // Sorted for byte-determinism (the serializer also sorts, but keep the source stable). PURE
   // DIRECT (`rewrite` omitted ⇒ `null`, not `self()`): a flat membership relation — the read-cap is
   // exactly "who was granted it". (`self()`/`Rewrite::This` inside a rewrite expands to an EMPTY
@@ -724,29 +748,87 @@ export function emitUsd(
       // into. The `nomosReadVisibility` key (type → cap) is RETAINED as the type-to-relation map; the
       // synthesized schema is what makes that cap a checkable relation. SORTED + omit-when-empty.
       const readRelationTypes = synthesizeReadRelationTypes(manifest);
+      // THE OWNING DOMAIN KEY — the relation-namespacing qualifier (the SAME key the openapi routes
+      // dispatch by, `module.domain ?? module.name`, so `intent.domain` at plan runtime === the key the
+      // schema/gate qualified under; the tuple object a token produces then lines up by construction).
+      const domainKey = l.module.domain ?? l.module.name;
+      // The NON-GLOBAL (namespaced) relation type names this layer declares — the set whose gate objects
+      // must be qualified. A `global` type (governance `workspace`, signer `identity`, read-visibility
+      // `workspace`) stays bare on BOTH the schema and the gate side, so it is excluded here.
+      const namespacedTypes = new Set(
+        (l.module.relationTypes ?? []).filter((d) => d.global !== true).map((d) => d.type),
+      );
+      // THE AMBIGUITY GUARD (relation-namespacing): a bare `writeTuple({object:"workspace:self", relation:R})`
+      // is auto-qualified iff `(type,R)` is a LOCAL non-global authored relation, and left BARE iff it is a
+      // GLOBAL / read-visibility cap. If ONE `(type,R)` is BOTH — a non-global authored relation AND a
+      // synthesized read-visibility cap (always on type `workspace`) — the bare object is genuinely
+      // ambiguous. Refuse at compile with a clear message (the maintainer's rule: never silently pick).
+      {
+        const readCaps = new Set(readRelationTypes.flatMap((rt) => [...rt.relations.keys()]));
+        for (const d of l.module.relationTypes ?? []) {
+          if (d.global === true || d.type !== "workspace") continue;
+          for (const rel of d.relations.keys()) {
+            if (readCaps.has(rel)) {
+              throw new Error(
+                `relation-namespacing conflict in domain "${domainKey}": relation "workspace#${rel}" is ` +
+                  `declared BOTH as a local authored relationType("workspace") relation AND as a ` +
+                  `read-visibility cap (a requires("${rel}") aggregate). A bare writeTuple object for ` +
+                  `"${rel}" would be ambiguous (qualify vs stay bare). Rename one of them.`,
+              );
+            }
+          }
+        }
+      }
+      // THE RELATION-NAMESPACE ERA KEY (`nomosRelationNamespace`): present IFF this layer qualified ≥1
+      // (non-global) relation type — the marker that this bundle's relation ids are domain-qualified.
+      // Absent when a layer declares no relation type OR only global ones ⇒ byte-identical to the
+      // pre-namespacing compiler (the `nomosRelations`/`nomosInvariantGate` era discipline).
+      const qualifiedTypeIds = [...namespacedTypes].map((t) => qualifyRelationType(domainKey, t)).sort();
+      const nomosRelationNamespace =
+        qualifiedTypeIds.length > 0 ? { v: 1 as const, delimiter: "__", types: qualifiedTypeIds } : undefined;
+      // Qualify the TYPE half of a gate object by the owning domain — but ONLY when this layer declares
+      // that type as a NON-GLOBAL relation type (so the gate object matches its qualified schema id). A
+      // global-type object (`workspace:self` for governance/read-visibility) or a type this layer doesn't
+      // declare passes through BARE — byte-identical to the pre-namespacing compiler.
+      const qualifyGateObject = (obj: string): string => {
+        const colon = obj.indexOf(":");
+        if (colon < 0) return obj;
+        const ty = obj.slice(0, colon);
+        return namespacedTypes.has(ty) ? `${qualifyRelationType(domainKey, ty)}${obj.slice(colon)}` : obj;
+      };
       // THE RELATION SCHEMA (P1): per-type rewrites lowered to the nomosRelations AST, UNIONED with the
-      // synthesized read relations. SORTED keys (byte-determinism — the layered flatten reproduces these
-      // bytes); omit-when-empty (era rule). A read-cap name colliding with an authored `workspace`
-      // relation is an author error (caught in the merge).
-      const nomosRelations = serializeRelationSchema([
-        ...(l.module.relationTypes ?? []),
-        ...readRelationTypes,
-      ]);
+      // synthesized read relations. Keys are QUALIFIED by the owning domain (namespacing) except global
+      // types. SORTED keys (byte-determinism); omit-when-empty (era rule). A read-cap name colliding with
+      // an authored `workspace` relation is an author error (caught in the merge).
+      const nomosRelations = serializeRelationSchema(
+        [...(l.module.relationTypes ?? []), ...readRelationTypes],
+        domainKey,
+      );
       // THE RELATION GATE (P4): directives declaring `.requiresRelation` → directiveId → {relation,
-      // object}. SORTED keys; omit-when-empty (era rule — a relation-gate-free layer is byte-identical).
+      // object}. The object's TYPE half is qualified to match the (now-namespaced) schema id. SORTED
+      // keys; omit-when-empty (era rule — a relation-gate-free layer is byte-identical).
       const relationGateReq: Record<
         string,
         { relation: string; object: string; objectFrom?: { recordType: string; idField: string } }
       > = {};
       for (const d of [...l.module.directives].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))) {
         if (d.requiresRelationGate !== undefined) {
+          const objectFrom = d.requiresRelationGate.objectFrom;
           relationGateReq[d.id] = {
             relation: d.requiresRelationGate.relation,
-            object: d.requiresRelationGate.object,
+            object: qualifyGateObject(d.requiresRelationGate.object),
             // PER-RECORD object (home_holons §6): carried through to the wasm gate; omitted when absent
-            // so a self-relative directive's USD is byte-identical (the era rule).
-            ...(d.requiresRelationGate.objectFrom !== undefined
-              ? { objectFrom: d.requiresRelationGate.objectFrom }
+            // so a self-relative directive's USD is byte-identical (the era rule). The recordType is the
+            // object type of the per-record tuple, so it namespaces exactly like the gate object type.
+            ...(objectFrom !== undefined
+              ? {
+                  objectFrom: {
+                    recordType: namespacedTypes.has(objectFrom.recordType)
+                      ? qualifyRelationType(domainKey, objectFrom.recordType)
+                      : objectFrom.recordType,
+                    idField: objectFrom.idField,
+                  },
+                }
               : {}),
           };
         }
@@ -951,6 +1033,7 @@ export function emitUsd(
             }
           : {}),
         ...(nomosRelations !== undefined ? { nomosRelations } : {}),
+        ...(nomosRelationNamespace !== undefined ? { nomosRelationNamespace } : {}),
         ...(nomosRelationGate !== undefined ? { nomosRelationGate } : {}),
         ...(nomosAttestationGate !== undefined ? { nomosAttestationGate } : {}),
         ...(nomosBirthGate !== undefined ? { nomosBirthGate } : {}),

package/src/usd_layers.ts

@@ -171,6 +171,9 @@ function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string):
     ...(layer.nomosRelations !== undefined
       ? [`${indent}custom string nomos:relationsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosRelations)))}`]
       : []),
+    ...(layer.nomosRelationNamespace !== undefined
+      ? [`${indent}custom string nomos:relationNamespaceHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosRelationNamespace)))}`]
+      : []),
     ...(layer.nomosRelationGate !== undefined
       ? [`${indent}custom string nomos:relationGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosRelationGate)))}`]
       : []),
@@ -736,7 +739,23 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
       const t = new Map<string, NonNullable<UsdLayer["nomosRelations"]>["types"][string]>();
       for (const l of stack) {
         if (l.nomosRelations === undefined) continue;
-        for (const [type, spec] of Object.entries(l.nomosRelations.types)) t.set(type, spec);
+        for (const [type, spec] of Object.entries(l.nomosRelations.types)) {
+          // RELATION-NAMESPACING SAFETY: after qualification, two domains' same bare type key under
+          // DISTINCT ids (`estate__workspace` vs `home__workspace`) and never reach here as the same key.
+          // A collision on the SAME canonical id can now only be a genuinely SHARED id (two layers
+          // contributing the same global type, or a future cross-domain shared type). Silent last-wins
+          // would DROP one layer's relations — so a collision on a key whose spec DIFFERS is a HARD ERROR
+          // (loud, not last-wins). An identical re-contribution (framework dedup) is fine.
+          const prior = t.get(type);
+          if (prior !== undefined && JSON.stringify(prior) !== JSON.stringify(spec)) {
+            throw new Error(
+              `nomosRelations: relation type "${type}" is contributed with DIFFERING definitions by two ` +
+                `layers — the qualified ids collide. A shared relation type must be identical across ` +
+                `domains (or namespaced per-domain). Refusing to silently last-wins.`,
+            );
+          }
+          t.set(type, spec);
+        }
       }
       if (t.size > 0) {
         const typesRec: NonNullable<UsdLayer["nomosRelations"]>["types"] = {};
@@ -744,6 +763,18 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         relations = { v: 1, types: typesRec };
       }
     }
+    // THE RELATION-NAMESPACE ERA KEY (relation-namespacing): the SORTED union of every layer's qualified
+    // type ids. Present iff ANY layer namespaced ≥1 type; omit-when-empty (byte-identical for global-only
+    // / relation-free packages). `delimiter` is the ratified colon-free `"__"`.
+    let relationNamespace: UsdLayer["nomosRelationNamespace"];
+    {
+      const ns = new Set<string>();
+      for (const l of stack) {
+        if (l.nomosRelationNamespace === undefined) continue;
+        for (const id of l.nomosRelationNamespace.types) ns.add(id);
+      }
+      if (ns.size > 0) relationNamespace = { v: 1, delimiter: "__", types: [...ns].sort() };
+    }
     // THE RELATION GATE (P4): directiveId → {relation, object} merged later-wins, SORTED. Omit-when-empty.
     let relationGate: UsdLayer["nomosRelationGate"];
     {
@@ -825,6 +856,7 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
       ...(readVisibility !== undefined ? { nomosReadVisibility: readVisibility } : {}),
       ...(encryption !== undefined ? { nomosEncryption: encryption } : {}),
       ...(relations !== undefined ? { nomosRelations: relations } : {}),
+      ...(relationNamespace !== undefined ? { nomosRelationNamespace: relationNamespace } : {}),
       ...(relationGate !== undefined ? { nomosRelationGate: relationGate } : {}),
       ...(attestationGate !== undefined ? { nomosAttestationGate: attestationGate } : {}),
       ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),
@@ -956,6 +988,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const encryptionByDomain = new Map<string, UsdLayer["nomosEncryption"]>();
   const relationsByDomain = new Map<string, UsdLayer["nomosRelations"]>();
   const relationGateByDomain = new Map<string, UsdLayer["nomosRelationGate"]>();
+  const relationNamespaceByDomain = new Map<string, UsdLayer["nomosRelationNamespace"]>();
   const attestationGateByDomain = new Map<string, UsdLayer["nomosAttestationGate"]>();
   const birthGateByDomain = new Map<string, UsdLayer["nomosBirthGate"]>();
   const parentAttestedBirthByDomain = new Map<string, UsdLayer["nomosParentAttestedBirth"]>();
@@ -1006,6 +1039,11 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof relGateHex === "string") {
         relationGateByDomain.set(domain, JSON.parse(unhexUtf8(relGateHex)) as UsdLayer["nomosRelationGate"]);
       }
+      // THE RELATION-NAMESPACE ERA KEY (relation-namespacing): the hex-carried qualified-type witness.
+      const relNsHex = p.attrs.get("nomos:relationNamespaceHex");
+      if (typeof relNsHex === "string") {
+        relationNamespaceByDomain.set(domain, JSON.parse(unhexUtf8(relNsHex)) as UsdLayer["nomosRelationNamespace"]);
+      }
       // THE ATTESTATION GATE (home_holons §3/§5): the hex-carried attestation-authorized directive set.
       const attGateHex = p.attrs.get("nomos:attestationGateHex");
       if (typeof attGateHex === "string") {
@@ -1122,6 +1160,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const enc = encryptionByDomain.get(domain);
       const rel = relationsByDomain.get(domain);
       const relGate = relationGateByDomain.get(domain);
+      const relNs = relationNamespaceByDomain.get(domain);
       const attGate = attestationGateByDomain.get(domain);
       const birthGate = birthGateByDomain.get(domain);
       const parentAttestedBirth = parentAttestedBirthByDomain.get(domain);
@@ -1140,6 +1179,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(rv !== undefined ? { nomosReadVisibility: rv } : {}),
         ...(enc !== undefined ? { nomosEncryption: enc } : {}),
         ...(rel !== undefined ? { nomosRelations: rel } : {}),
+        ...(relNs !== undefined ? { nomosRelationNamespace: relNs } : {}),
         ...(relGate !== undefined ? { nomosRelationGate: relGate } : {}),
         ...(attGate !== undefined ? { nomosAttestationGate: attGate } : {}),
         ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),