@githolon/dsl 0.29.1 → 0.30.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.29.1",
+  "version": "0.30.1",
   "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";
@@ -382,6 +383,27 @@ function relationSeedLegLines(
     ? ` — a COMPUTED gate: granting "${leg.grantedRelation}" makes the actor satisfy "${leg.relation}" via the rewrite`
     : ``;
 
+  if (leg.bornContext !== undefined) {
+    // LAYER 4 — THE BORN-DOMAIN GENESIS-AUTHORITY PATH (co2 home). R is established ONLY by the birth genesis
+    // (e.g. birthHome → seedHomeCreator seats creator), and the seed carries an owner-binding PREREQUISITE a
+    // standalone re-seed can't satisfy. This leg is proven by `githolon proof` (offline, on the local wasm):
+    // the runner BIRTHS the workspace as the proof actor (= owner), then dispatches the gated directive INSIDE
+    // the born workspace as that owner, asserting ADMITTED at the real kernel gate (a refusal degrades to a
+    // diagnostic — never a false green). The LIVE `--live` lane proves the underlying birth via the child-birth
+    // leg; the gated-directive-in-born-context proof is the offline runner's (birthing a throwaway home per
+    // gated directive live would leave orphan workspaces).
+    const bc = leg.bornContext;
+    return [
+      `// ${n()}. RELATION BOOTSTRAP — LAYER 4 (born-domain genesis authority): \`${leg.domain}/${leg.gatedDirectiveId}\``,
+      `//    is GATED (\`.requires("${leg.relation}")\`), established ONLY by the birth genesis (\`${bc.birthDirectiveId}\` →`,
+      `//    \`${bc.seatsViaDirectiveId}\` seats "${leg.relation}") — NOT a standalone-replayable seed (its owner-binding`,
+      `//    prerequisite would false-fail). Proven by \`githolon proof\` (offline): birth the workspace as the owner,`,
+      `//    then dispatch \`${leg.gatedDirectiveId}\` INSIDE the born workspace as that owner (real-gate admitted).`,
+      `console.log("– relation-bootstrap leg (born-context) — \`${leg.domain}/${leg.gatedDirectiveId}\` .requires(\\"${leg.relation}\\") is proven in the BORN workspace by \`githolon proof\` (offline); the birth is proven live by the child-birth leg");`,
+      ``,
+    ];
+  }
+
   if (speculative) {
     // LAYER 3 (seed-path replay). The gate relation is reachable only through ttu/intersection/exclusion — no
     // directly-grantable base. We REPLAY the domain's declared seed and let the REAL GATE arbitrate: if the
@@ -492,8 +514,10 @@ export interface RelationBootstrapLeg {
    *  `writeTuple(R)`), `"computed-base"` (R is computed; the grant seats a rewrite BASE relation the granter
    *  was found for), or `"seed-path"` (LAYER 3: R is reachable only through ttu/intersection/exclusion — no
    *  directly-grantable base — so a DECLARED SEED directive that establishes root authority is replayed and
-   *  the REAL KERNEL GATE is the arbiter of whether it authorizes the write). Audit + runner semantics. */
-  readonly via: "marker" | "inferred" | "computed-base" | "seed-path";
+   *  the REAL KERNEL GATE is the arbiter of whether it authorizes the write), or `"born-context"` (LAYER 4:
+   *  R is established by the domain's BIRTH GENESIS — the gated directive is proven INSIDE the born workspace
+   *  as the owner; see {@link BornContextAuthority}). Audit + runner semantics. */
+  readonly via: "marker" | "inferred" | "computed-base" | "seed-path" | "born-context";
   /** LAYER-3 ANTI-FALSE-GREEN FLAG. `true` ⇒ this is a SPECULATIVE seed-path leg: codegen could NOT prove
    *  (via rewrite resolution) that replaying `grantDirectiveId` authorizes the gated write — it discovered a
    *  seed that writes relation tuples and is DEFERRING to the real kernel gate. The runner replays the seed,
@@ -503,6 +527,37 @@ export interface RelationBootstrapLeg {
   readonly seedSpeculative?: boolean;
   /** The relations the discovered seed directive writes (layer-3 audit/diagnostic — what authority it seats). */
   readonly seedWritesRelations?: readonly string[];
+  /** LAYER 4 — THE BORN-DOMAIN GENESIS-AUTHORITY PATH. Present iff the gate relation is established by the
+   *  domain's BIRTH GENESIS (not a standalone-replayable seed): a `.births()` directive whose genesis chain
+   *  seats R (e.g. co2's `birthHome` → `seedHomeCreator` seats `creator`), and whose born workspace runs the
+   *  SAME law — so the gated directive can be proven INSIDE the born context, dispatched as the genesis-
+   *  established OWNER, where the seed's own prerequisite invariants (HomeCreatorSeedBindsOwner) hold. This
+   *  TAKES PRECEDENCE over a standalone seed (`grantDirectiveId`) for a born domain: a standalone re-seed
+   *  would trip the seed's owner-binding prerequisite (HomeOwner unset) and FALSE-fail. When present, the
+   *  runner IGNORES the standalone grant fields and proves via {@link BornContextAuthority}. */
+  readonly bornContext?: BornContextAuthority;
+}
+
+/** THE BORN-DOMAIN GENESIS AUTHORITY (layer 4): the self-birth directive whose genesis seats the gate relation
+ *  for the OWNER, plus what the runner needs to birth it (as the proof actor = the home owner) and then prove
+ *  the gated directive INSIDE the born workspace. The real kernel gate is the arbiter — a refusal degrades to
+ *  a diagnostic (never a false green). */
+export interface BornContextAuthority {
+  /** The self-birth directive (`birthHome`) whose genesis chain seats the gate relation. */
+  readonly birthDirectiveId: string;
+  /** The synthesized birth payload (auto-stamped `…At` omitted; framework/law-hash placeholders removed — the
+   *  runtime injects the REAL hashes + the proof actor as owner). */
+  readonly birthPayload: Record<string, unknown>;
+  readonly birthAutoStamped: readonly string[];
+  /** The birth payload field carrying the home OWNER — the runtime sets it to the proof actor, so the born
+   *  home is owned by (and seats the relation for) the actor the gated dispatch then runs as. */
+  readonly ownerField?: string;
+  /** The birth payload field carrying the framework-controller hash (runtime injects the real one). */
+  readonly frameworkHashField?: string;
+  /** The birth payload field carrying the child law hash (runtime injects the deployed package hash). */
+  readonly lawHashField?: string;
+  /** The genesis step directive that actually seats the relation (audit — e.g. `seedHomeCreator`). */
+  readonly seatsViaDirectiveId: string;
 }
 
 /** Run a directive's plan with a synthesized+probe payload under birth-probe globals and return the drained
@@ -686,6 +741,127 @@ export function resolveGrantableBaseRelations(
   return out;
 }
 
+// ── LAYER 4: born-domain genesis-authority discovery (the co2 home case) ─────────────────────────────────
+//
+// A gate relation R may be established ONLY by the domain's BIRTH GENESIS — a `.births()` directive whose
+// genesis chain seats R for the owner (co2's `birthHome` genesis runs `seedHomeCreator`, seating `creator`).
+// The seed itself carries a PREREQUISITE (an owner-binding workspaceInvariant reading state set by an EARLIER
+// genesis step), so a standalone re-seed FALSE-fails (the prior state is absent). The law-true authority path
+// is to BIRTH the workspace (replaying the whole genesis, seating R for the owner) and prove the gated
+// directive INSIDE the born workspace, dispatched as that owner. Discovery probes each `.births()` directive's
+// genesis chain for a step that writeTuples R; if found, the born workspace (running the SAME law) is where
+// the gated directive proves.
+
+/** Probe a `.births()` directive's genesis chain (birth-probe globals) → the recorded steps + the synthesized
+ *  parent payload. `undefined` ⇒ not probeable / no recipe. Mirrors {@link discoverChildBirthLeg}'s probe. */
+function probeBirthGenesis(
+  birthDir: Directive<unknown>,
+  where: string,
+): { chain: Array<{ domain?: string; directiveId?: string; actor?: unknown }>; synth: SynthesizedPayload } | undefined {
+  let synth: SynthesizedPayload;
+  try {
+    synth = synthesizePayload(birthDir.payloadSchema as z.ZodTypeAny, where);
+  } catch {
+    return undefined;
+  }
+  const probePayload: Record<string, unknown> = { ...synth.value };
+  for (const f of synth.autoStamped) probePayload[f] = "2026-01-01T00:00:00Z";
+  let recipe: { genesisChain?: unknown } | undefined;
+  try {
+    withBirthProbeGlobals(() => {
+      __resetAuthoring();
+      __resetReads();
+      __resetBirths();
+      try {
+        birthDir.plan(probePayload as never, deterministicPorts({ physical: 1, replica: 1, principal: "principal:probe" }));
+      } finally {
+        try { __drainAuthoring(); __drainReads(); } catch { /* drained */ }
+      }
+      recipe = __drainBirths()[0] as typeof recipe;
+    });
+  } catch {
+    return undefined;
+  }
+  if (recipe === undefined || !Array.isArray(recipe.genesisChain)) return undefined;
+  return { chain: recipe.genesisChain as Array<{ domain?: string; directiveId?: string; actor?: unknown }>, synth };
+}
+
+/**
+ * Discover the BORN-DOMAIN genesis authority for a gate `relation`: a `.births()` directive in `mod` whose
+ * genesis chain seats `relation` (a genesis step whose directive `writeTuple`s R) AND whose born workspace
+ * runs the SAME law (so the gated directive is addressable there). Returns what the runner needs to birth the
+ * workspace as the proof actor (= the owner) + the owner/hash payload fields. `undefined` ⇒ no birth seats R.
+ */
+export function discoverBornContextAuthority(
+  mod: DomainModule,
+  relation: string,
+): BornContextAuthority | undefined {
+  const domain = mod.domain ?? mod.name;
+  const directives = mod.directives as Directive<unknown>[];
+  const byId = new Map(directives.map((d) => [d.id, d]));
+  for (const bd of directives) {
+    if (bd?.birthsChild !== true || typeof bd.payloadSchema !== "object") continue;
+    const probed = probeBirthGenesis(bd, `${domain}/${bd.id}`);
+    if (probed === undefined) continue;
+    const { chain, synth } = probed;
+    // Find the genesis step (in THIS domain) whose directive writeTuples `relation` — that step seats R.
+    let seatsVia: string | undefined;
+    for (const step of chain) {
+      if (step === null || typeof step !== "object" || step.domain !== domain || typeof step.directiveId !== "string") continue;
+      const stepDir = byId.get(step.directiveId);
+      if (stepDir === undefined) continue;
+      if (probeRelationsWritten(stepDir, `${domain}/${stepDir.id}`).includes(relation)) {
+        seatsVia = step.directiveId;
+        break;
+      }
+    }
+    if (seatsVia === undefined) continue;
+
+    // Resolve the owner field (the payload field whose value the genesis routes as the seed's subject/actor)
+    // + the framework/law-hash fields (matched by value against the genesis install steps), mirroring
+    // discoverChildBirthLeg. The owner field is the payload field carried as a genesis step actor.
+    const fieldForValue = (v: unknown): string | undefined =>
+      Object.entries(synth.value).find(([, sv]) => sv === v && typeof v === "string" && v.length > 0)?.[0];
+    const ownerField = (() => {
+      for (const step of chain as Array<{ actor?: unknown }>) {
+        const exact = fieldForValue(step?.actor);
+        if (exact !== undefined) return exact;
+        if (typeof step?.actor === "string") {
+          for (const [field, value] of Object.entries(synth.value)) {
+            if (typeof value === "string" && value.length > 0 && (step.actor === `user:${value}` || step.actor === `key:${value}`)) return field;
+          }
+        }
+      }
+      return undefined;
+    })();
+    const installSteps = chain.filter((s) => s !== null && typeof s === "object" && s.directiveId === "installDomain") as Array<{ domain?: string; payload?: { domainHash?: unknown } }>;
+    const frameworkHashField = fieldForValue(installSteps.find((s) => s.domain === "bootstrap")?.payload?.domainHash);
+    const lawHashField = fieldForValue(installSteps.find((s) => s.domain === "nomos")?.payload?.domainHash);
+
+    const birthPayload: Record<string, unknown> = { ...synth.value };
+    if (frameworkHashField !== undefined) delete birthPayload[frameworkHashField];
+    if (lawHashField !== undefined) delete birthPayload[lawHashField];
+
+    return {
+      birthDirectiveId: bd.id,
+      birthPayload,
+      birthAutoStamped: synth.autoStamped,
+      ...(ownerField !== undefined ? { ownerField } : {}),
+      ...(frameworkHashField !== undefined ? { frameworkHashField } : {}),
+      ...(lawHashField !== undefined ? { lawHashField } : {}),
+      seatsViaDirectiveId: seatsVia,
+    };
+  }
+  return undefined;
+}
+
+/** Does any workspaceInvariant fire ON `directiveId` — i.e. does that directive carry a PREREQUISITE (a
+ *  declared invariant reading state another step must establish first)? A standalone replay of such a
+ *  directive can FALSE-fail (the prior state is absent), so a born domain must prove via the genesis path. */
+function directiveHasPrerequisiteInvariant(mod: DomainModule, directiveId: string): boolean {
+  return (mod.workspaceInvariants ?? []).some((inv) => inv.on === directiveId);
+}
+
 /** Discover the RELATION-BOOTSTRAP leg for a module: the first gated (`.requires(R)`) directive plus the
  *  sibling that ESTABLISHES the actor's authority for R. In priority order: (1) a DIRECT granter of R (a
  *  `.grants(R)` marker or a plan-probed `writeTuple(R)`) — the original lane; (2) REWRITE-AWARE — when R is
@@ -764,14 +940,54 @@ export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstr
       // guard: `seedSpeculative`). Prefer a seed that seats the MOST relations (a genesis/owner seed like
       // estate's, which lands admin/creator/estateOwner together — the broadest root authority).
       const seed = discoverSeedDirective(candidates, domain);
-      if (seed === undefined) return undefined; // no seed path → the caller emits the diagnostic
-      found = { granter: seed.dir, via: "inferred" };
-      grantedRelation = seed.relationsWritten[0] ?? relation; // cosmetic — the seed's primary relation
-      via = "seed-path";
-      seedSpeculative = true;
-      seedWritesRelations = seed.relationsWritten;
+      if (seed !== undefined) {
+        found = { granter: seed.dir, via: "inferred" };
+        grantedRelation = seed.relationsWritten[0] ?? relation; // cosmetic — the seed's primary relation
+        via = "seed-path";
+        seedSpeculative = true;
+        seedWritesRelations = seed.relationsWritten;
+      }
     }
   }
+
+  // (4) BORN-DOMAIN GENESIS AUTHORITY (the co2 home case) — precedence over a standalone seed. The standalone
+  // path is "clean" ONLY when a granter was found, it isn't the speculative seed-path lane, AND that granter
+  // carries NO prerequisite invariant (a standalone re-seed of a prerequisite-gated granter — e.g.
+  // seedHomeCreator, gated by HomeCreatorSeedBindsOwner — would FALSE-fail because the prior genesis state is
+  // absent). When the standalone path is NOT clean, prefer proving the gated directive INSIDE the born
+  // workspace, whose genesis seats R for the owner.
+  const standaloneClean =
+    found !== undefined && !seedSpeculative && !directiveHasPrerequisiteInvariant(mod, found.granter.id);
+  if (!standaloneClean) {
+    const bornContext = discoverBornContextAuthority(mod, relation);
+    if (bornContext !== undefined) {
+      return {
+        domain,
+        gatedDirectiveId: gated.id,
+        relation,
+        grantedRelation: relation,
+        gatedPayload,
+        gatedAutoStamped: gatedSynth.autoStamped,
+        ...(gatedMintField !== undefined ? { gatedMintField, gatedAggregateId: gated.aggregateId } : {}),
+        // grant fields are UNUSED for a born-context leg (the runner births + dispatches inside); populate them
+        // with the genesis seed's id / empty payload so the shape stays uniform (never dispatched standalone).
+        grantDirectiveId: bornContext.seatsViaDirectiveId,
+        grantPayload: {},
+        grantAutoStamped: [],
+        grantSubjectFields: [],
+        grantGrantedByFields: [],
+        via: "born-context",
+        bornContext,
+      };
+    }
+    // No born-domain path. If a standalone granter exists but carries a prerequisite it can't satisfy alone
+    // (and isn't the speculative lane), do NOT emit a doomed passing leg — return undefined so the caller's
+    // loud diagnostic names the unmet prerequisite. A speculative seed-path stays (it degrades safely).
+    if (found !== undefined && !seedSpeculative && directiveHasPrerequisiteInvariant(mod, found.granter.id)) {
+      return undefined;
+    }
+  }
+  if (found === undefined) return undefined; // no granter at all → the caller emits the diagnostic
   const granter = found.granter;
 
   // Synthesize the grant payload + resolve which fields route into subject / grantedBy (so runtime seats the
@@ -844,6 +1060,19 @@ export function diagnoseRelationBootstrapGap(mod: DomainModule): string | undefi
   if (discoverRelationBootstrapLeg(mod) !== undefined) return undefined; // resolved — no gap
   const relation = gated.requiresRelationGate!.relation;
   const object = gated.requiresRelationGate!.object;
+  // NAME THE UNMET PREREQUISITE (co2 home diagnostic): when a granter of R exists but carries a prerequisite
+  // invariant a standalone re-seed can't satisfy AND no birth genesis seats R, say so precisely.
+  const directivesAll = mod.directives as Directive<unknown>[];
+  const prereqGranter = directivesAll.find(
+    (d) => d !== gated && typeof d?.payloadSchema === "object" && d.birthsChild !== true
+      && probeGrantsRelation(d, relation, `${domain}/${d.id}`) && directiveHasPrerequisiteInvariant(mod, d.id),
+  );
+  if (prereqGranter !== undefined) {
+    const inv = (mod.workspaceInvariants ?? []).find((i) => i.on === prereqGranter.id);
+    return `${domain}/${gated.id} is gated by .requires("${relation}") but the proof cannot seed authority: the only granter of "${relation}" is `
+      + `${domain}/${prereqGranter.id}, which carries the prerequisite invariant '${inv?.id ?? "?"}' (it reads state an EARLIER step must establish), so a standalone re-seed FALSE-fails — and no \`.births()\` genesis seats "${relation}" to prove it in a born workspace. `
+      + `Establish "${relation}" via a birth genesis (a \`.births()\` whose chain runs ${prereqGranter.id} after seeding its prerequisite), or prove ${gated.id} by hand. (The negative conformance leg still proves the gate refuses an actorless offer.)`;
+  }
   const bases = resolveGrantableBaseRelations(mod.relationTypes, object, relation).filter((b) => b !== relation);
   const tried = bases.length > 0
     ? `no directive grants "${relation}" directly, nor any of its directly-grantable rewrite bases [${bases.join(", ")}]`
@@ -939,9 +1168,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;
   }
 }
@@ -1537,7 +1772,7 @@ function generateBirthOnlyProof(
     `import { readFileSync } from "node:fs";`,
     `import { connect, encodeIntentOfferBytes } from "@githolon/client";`,
     `import { ${factory}, ${hashConst} } from "./${opts.packageName}.client.ts";`,
-    `void connect; void ${factory};`,
+    `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);`,
@@ -1545,6 +1780,11 @@ function generateBirthOnlyProof(
     ...v2IdentityAndCleanupPreamble(opts, hashConst, n),
     ``,
     ...liveChildBirthLegLines(cb, opts, n),
+    // THE RELATION-BOOTSTRAP LEG (incl. LAYER 4 born-context): a birth-only domain may ALSO carry a gated
+    // non-birth directive whose authority is established by the birth genesis (co2 home's updateHomeProfile
+    // via birthHome→seedHomeCreator). Emit it so the birth-only proof names it (the born-context proof itself
+    // runs in the offline `githolon proof` lane). No-op when the domain has no gated directive.
+    ...relationSeedLegLines(primaryLegs.relationBootstrap, factory, n, primaryLegs.relationBootstrap === undefined ? diagnoseRelationBootstrapGap(mod) : undefined),
     `console.log(\`\\nALL GREEN — generated proof for "${opts.packageName}": deploy → child birth (\${WS} → the born child) → verified\`);`,
     ``,
     ...v2CatchFinally(),

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 } : {}),