@githolon/dsl 0.69.3 → 0.70.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.69.3",
+  "version": "0.70.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/build_package.ts

@@ -61,6 +61,7 @@ import {
 } from "./birth_meter.js";
 import { withBirthMeterExports } from "./birth_meter_ensure.js";
 import { withClearDirectives } from "./clear_directive.js";
+import { expandRoleExports, rolesOf } from "./role.js";
 import {
   withAttestedReadExports,
   isTrustSourceDecl,
@@ -184,6 +185,12 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   // `clear<Agg><Field>` directive (mutates + one clear op; `.requires` when declared) at the same
   // seam — manifest-visible, kernel-gated, proof-covered. Clearable-free domains are byte-identical.
   merged = withClearDirectives(merged);
+  // ROLE SUGAR: lift every `role(...).emit()` into discoverable grant/revoke/seed directives (so
+  // `directivesOf` folds them into the manifest) — the SAME "discoverable without re-exports" seam.
+  // The role-synthesized `relationType("workspace")` rides `spec.relationTypes` (the compile plane
+  // discovered it off the same expansion). Role-free domains are byte-identical (era rule).
+  merged = expandRoleExports(merged);
+  const roles = rolesOf(merged);
 
   const byId = new Map<string, AggregateHandle>();
   for (const a of [...aggregatesOf(merged), ...(spec.extraAggregates ?? [])]) byId.set(a.id, a);
@@ -388,6 +395,9 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
     directives,
     // Diagnostic metadata for the compile summary — NOT law (not hashed). Omit-when-empty.
     ...(autoDeclaredEnsures.length > 0 ? { autoDeclaredEnsures } : {}),
+    // ROLE SUGAR codegen metadata — NOT law (not hashed): drives the `canEdit<Agg>`/`canView<Agg>`
+    // UI-hint helpers. Omit-when-empty (a role-free domain is byte-identical).
+    ...(roles.length > 0 ? { roles } : {}),
     ...(queries.length > 0 ? { queries } : {}),
     ...(counts.length > 0 ? { counts } : {}),
     ...(spatials.length > 0 ? { spatials } : {}),

package/src/codegen_dart.ts

@@ -3702,6 +3702,12 @@ export interface DomainModule {
    * when the domain has no unsanctioned secondary ensure (the common case).
    */
   autoDeclaredEnsures?: string[];
+  /**
+   * ROLE SUGAR codegen metadata (role.ts) — the emitted roles' names, lowered edit/view relation
+   * names, and the aggregates each covers. Drives the `canEdit<Agg>`/`canView<Agg>` UI-hint helpers
+   * (TS + Dart). NOT law, NOT hashed (like {@link autoDeclaredEnsures}). Absent when no role is declared.
+   */
+  roles?: import("./role.js").RoleMeta[];
   /**
    * STABLE-ID CONTINUITY (#58 — names are labels, identity is minted). When present
    * (attached by `nomos-compile` from the PRIOR build's identity manifests), the
@@ -4269,6 +4275,62 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
       ]
     : [];
 
+  // ROLE SUGAR — per-(role × aggregate) `canEdit<Agg>`/`canView<Agg>` UI-HINT helpers, pure functions
+  // over the folded RelationTuple projection (the client-side MIRROR of engine.check). INFORMATIONAL
+  // only — THE KERNEL GATE REMAINS THE AUTHORITY. Emitted only when the domain declares roles (era-safe).
+  const roleBlock = (() => {
+    const editRels = new Map<string, Set<string>>();
+    const viewRels = new Map<string, Set<string>>();
+    for (const r of mod.roles ?? []) {
+      if (r.editRelation) for (const agg of r.editAggregates) (editRels.get(agg) ?? editRels.set(agg, new Set()).get(agg)!).add(r.editRelation);
+      if (r.viewRelation) for (const agg of r.viewAggregates) {
+        const s = viewRels.get(agg) ?? viewRels.set(agg, new Set()).get(agg)!;
+        s.add(r.viewRelation);
+        if (r.editRelation && r.editAggregates.includes(agg)) s.add(r.editRelation);
+      }
+    }
+    if (editRels.size === 0 && viewRels.size === 0) return "";
+    const lines: string[] = [
+      `/// True iff [principal] holds ANY of [relations] as an ACTIVE tuple in [rows] (or a \`user:*\` wildcard).`,
+      `bool _holdsAnyRelation(List<Map<String, dynamic>>? rows, Set<String> relations, String principal) {`,
+      `  for (final r in rows ?? const []) {`,
+      `    final data = r['data'];`,
+      `    if (data is! Map) continue;`,
+      `    final rel = data['relation'];`,
+      `    if (rel is! String || !relations.contains(rel)) continue;`,
+      `    final subjects = data['subjects'];`,
+      `    if (subjects is! Map) continue;`,
+      `    for (final entry in subjects.entries) {`,
+      `      final subj = entry.key.toString();`,
+      `      dynamic leaf = entry.value;`,
+      `      if (leaf is String) { try { leaf = jsonDecode(leaf); } catch (_) { leaf = const {}; } }`,
+      `      final status = leaf is Map ? leaf['status'] : null;`,
+      `      if (status != null && status != 'active') continue;`,
+      `      if (subj == 'user:\$principal' || subj == 'user:*') return true;`,
+      `    }`,
+      `  }`,
+      `  return false;`,
+      `}`,
+    ];
+    const dartSet = (s: Set<string>): string => `{${[...s].sort().map((x) => `'${x}'`).join(", ")}}`;
+    for (const [agg, rels] of [...editRels].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+      lines.push(
+        `/// UI HINT — may [principal] EDIT a ${agg}? Mirrors the kernel's ReBAC check; INFORMATIONAL only`,
+        `/// (the one wasm gate is the authority and refuses regardless).`,
+        `bool canEdit${cap(agg)}(List<Map<String, dynamic>>? relations, String principal) =>`,
+        `    _holdsAnyRelation(relations, ${dartSet(rels)}, principal);`,
+      );
+    }
+    for (const [agg, rels] of [...viewRels].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+      lines.push(
+        `/// UI HINT — may [principal] VIEW a ${agg}? Mirrors the kernel's ReBAC read gate; INFORMATIONAL only.`,
+        `bool canView${cap(agg)}(List<Map<String, dynamic>>? relations, String principal) =>`,
+        `    _holdsAnyRelation(relations, ${dartSet(rels)}, principal);`,
+      );
+    }
+    return lines.join("\n");
+  })();
+
   return [
     `// GENERATED by nomos2/dsl/src/codegen_dart.ts — DO NOT EDIT BY HAND.`,
     `//`,
@@ -4280,7 +4342,7 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
     `// ignore_for_file: unused_import`,
     ``,
     // A nullable plain-`t.json()` read-model slot decode re-stringifies via `jsonEncode`.
-    ...(needsJsonConvert ? [`import 'dart:convert';`] : []),
+    ...(needsJsonConvert || roleBlock !== "" ? [`import 'dart:convert';`] : []),
     // The generated tenant domains live in the `co2_nomos_domains` package and depend
     // on the framework `nomos_client` package by its PUBLIC package: URI — NOT a relative
     // `../wire.dart` path into the framework (which broke when the generated dir moved
@@ -4354,5 +4416,12 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
         ]
       : []),
     ...helperBlock,
+    ...(roleBlock !== ""
+      ? [
+          ``,
+          `// ---- role policy (UI hints — the KERNEL GATE is the authority) ----`,
+          roleBlock,
+        ]
+      : []),
   ].join("\n");
 }

package/src/codegen_ts.ts

@@ -1908,6 +1908,66 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     );
   }
 
+  // ROLE SUGAR — the per-(role × aggregate) `canEdit<Agg>` / `canView<Agg>` UI-HINT helpers. They
+  // evaluate LOCALLY against the folded RelationTuple projection (the client-side MIRROR of
+  // `engine.check`) — INFORMATIONAL only; THE KERNEL GATE REMAINS THE AUTHORITY and refuses regardless.
+  {
+    const editRels = new Map<string, Set<string>>(); // aggregate id → the edit relations that cover it
+    const viewRels = new Map<string, Set<string>>(); // aggregate id → the view relations that cover it
+    for (const m of modules) {
+      for (const r of m.roles ?? []) {
+        if (r.editRelation) for (const agg of r.editAggregates) (editRels.get(agg) ?? editRels.set(agg, new Set()).get(agg)!).add(r.editRelation);
+        // A role-holder granted `.canView` holds BOTH its view relation AND (when it can edit) its edit
+        // relation — an editor can always read what it edits, so canView accepts either.
+        if (r.viewRelation) for (const agg of r.viewAggregates) {
+          const s = viewRels.get(agg) ?? viewRels.set(agg, new Set()).get(agg)!;
+          s.add(r.viewRelation);
+          if (r.editRelation && r.editAggregates.includes(agg)) s.add(r.editRelation);
+        }
+      }
+    }
+    if (editRels.size > 0 || viewRels.size > 0) {
+      out.push(
+        `// ── ROLE POLICY (UI hints — the KERNEL GATE is the authority) ─────────────────────────────`,
+        `/** One folded RelationTuple row (as \`relationTuplesByObject\`/\`queryById("reltuple-…")\` yields). */`,
+        `export interface NomosRoleRelationRow { data?: { relation?: string; subjects?: Record<string, unknown> } }`,
+        `/** True iff \`principal\` holds ANY of \`relations\` as an ACTIVE tuple in \`rows\` (or a \`user:*\` wildcard). */`,
+        `function _holdsAnyRelation(rows: readonly NomosRoleRelationRow[] | undefined, relations: readonly string[], principal: string): boolean {`,
+        `  const want = new Set(relations);`,
+        `  for (const r of rows ?? []) {`,
+        `    if (r?.data?.relation === undefined || !want.has(r.data.relation)) continue;`,
+        `    for (const [subj, leafRaw] of Object.entries(r.data.subjects ?? {})) {`,
+        `      let leaf: { status?: string };`,
+        `      try { leaf = typeof leafRaw === "string" ? JSON.parse(leafRaw) : (leafRaw as { status?: string }); } catch { leaf = {}; }`,
+        `      if (leaf?.status !== undefined && leaf.status !== "active") continue;`,
+        `      if (subj === \`user:\${principal}\` || subj === "user:*") return true;`,
+        `    }`,
+        `  }`,
+        `  return false;`,
+        `}`,
+      );
+      for (const [agg, rels] of [...editRels].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+        out.push(
+          `/** UI HINT — may \`principal\` EDIT a ${agg}? Mirrors the kernel's ReBAC check over the folded`,
+          ` *  tuples; INFORMATIONAL only (the one wasm gate is the authority and refuses regardless). */`,
+          `export function canEdit${cap(agg)}(relations: readonly NomosRoleRelationRow[] | undefined, principal: string): boolean {`,
+          `  return _holdsAnyRelation(relations, ${JSON.stringify([...rels].sort())}, principal);`,
+          `}`,
+        );
+      }
+      for (const [agg, rels] of [...viewRels].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+        out.push(
+          `/** UI HINT — may \`principal\` VIEW a ${agg}? Mirrors the kernel's ReBAC read gate;`,
+          ` *  INFORMATIONAL only (the one wasm read boundary is the authority). */`,
+          `export function canView${cap(agg)}(relations: readonly NomosRoleRelationRow[] | undefined, principal: string): boolean {`,
+          `  return _holdsAnyRelation(relations, ${JSON.stringify([...rels].sort())}, principal);`,
+          `}`,
+        );
+      }
+      out.push(``);
+    }
+  }
+
   // RECURSIVE PAYLOAD TYPES (`z.lazy`): emit each minted named alias once. Sorted by name for
   // byte-determinism; TS hoists type aliases so referencing them above is fine.
   if (lazyReg.decls.size > 0) {

package/src/compile_package_main.ts

@@ -90,6 +90,7 @@ import {
 import { synthesizePreconditionInvariants } from "./precondition.js";
 import { BIRTH_METER_QUERIES, synthesizeBirthQuotaInvariants } from "./birth_meter.js";
 import { withBirthMeterExports } from "./birth_meter_ensure.js";
+import { expandRoleExports, rolesOf } from "./role.js";
 import { collectEngineRouting } from "./engine_entry.js";
 import {
   discover,
@@ -1286,6 +1287,10 @@ async function main(): Promise<void> {
     merged = expandCapabilityExports(merged);
     // METERED BIRTH: the same injection composeDomainModule/mergeModules apply — one seam, no drift.
     merged = withBirthMeterExports(merged);
+    // ROLE SUGAR: lift every `role(...).emit()` into discoverable directives + the synthesized
+    // `relationType("workspace")` (the same seam composeDomainModule expands) so this plane's openapi /
+    // relation-schema discovery sees the grant/revoke/seed directives + the teeth-bearing schema.
+    merged = expandRoleExports(merged);
     let shardingSums: AnySum[] = [];
     let shardingMins: AnyExtremum[] = [];
     let shardingMaxes: AnyExtremum[] = [];

package/src/engine_entry.ts

@@ -59,6 +59,7 @@ import { isRelationTypeDecl } from "./relation_schema.js";
 import { synthesizePreconditionInvariants } from "./precondition.js";
 import { synthesizeBirthQuotaInvariants } from "./birth_meter.js";
 import { withBirthMeterExports } from "./birth_meter_ensure.js";
+import { expandRoleExports } from "./role.js";
 import { withAttestedReadExports } from "./attested.js";
 import { generateOpenApiFragment, mergeOpenApiFragments, type OpenApiDoc } from "./codegen_openapi.js";
 import type { QueryDecl } from "./query.js";
@@ -250,7 +251,9 @@ function mergeModules(mods: readonly DomainModuleExports[]): DomainModuleExports
   // METERED BIRTH: a `.births()`-declaring domain gains the birth-meter structural exports
   // (the sanctioning `nomosBirthRecordEnsure` + the meter aggregates) at this same seam, so
   // the registry + `describe()` see the exact surface the composed manifest carries.
-  return withAttestedReadExports(withBirthMeterExports(expandCapabilityExports(merged)));
+  // ROLE SUGAR: lift every `role(...).emit()` into its grant/revoke/seed directives at the SAME
+  // engine merge point so the registry dispatches them (the compiler saw them via the same expander).
+  return expandRoleExports(withAttestedReadExports(withBirthMeterExports(expandCapabilityExports(merged)))) as DomainModuleExports;
 }
 
 /**

package/src/framework/workspaces.ts

@@ -172,6 +172,19 @@ export const workspaceRelations = relationType("workspace")
 /** Where a workspace's holon runs: an edge DO or the dedicated 12GiB container. */
 export const WORKSPACE_TIERS = ["edge", "heavy"] as const;
 
+/**
+ * GOVERNANCE POSTURE (architecture/governance_postures.md) — every platform DECLARES how the operator may
+ * act in its subtree. `managed` (the default when absent) folds an OperatorGrant: the operator may run
+ * recovery verbs (rebirth, certifyEra, repairs) FOR the tenant, each a signed, attributed, replayable law
+ * fact. `sovereign` withholds it: root's recovery verbs REFUSE for a Sovereign workspace UNLESS the offer
+ * carries the tenant's own {@link RebirthConsent} fact (folded in the tenant's OWN chain — the two-key
+ * ceremony). v1 is bailiff-verified (the custody act reads both facts); v2 rides the attested-read lane so
+ * the ROOT GATE re-derives it. Hosted sovereignty = law-encoded restraint + total detectability + credible
+ * exit — never prevention (the operator controls root's law, but cannot change it SECRETLY, and the tenant
+ * can always clone + leave).
+ */
+export const GOVERNANCE_POSTURES = ["managed", "sovereign"] as const;
+
 /**
  * The workspace lifecycle: `requested` (law fact only — nothing physical exists)
  * → `provisioned` (the worker built the machinery and recorded the owner hash)
@@ -304,6 +317,13 @@ export const CloudWorkspace = aggregate("CloudWorkspace", {
    *  incarnation's genesis oid. The reborn holon itself testifies to its ancestry (alongside the UNCHANGED
    *  `parent` — a rebirth may never claim new parents; see {@link rebirthRetainsLineage}). Additive/era-safe. */
   rebornFrom: t.string().merge(Lww).optional(),
+  /** GOVERNANCE POSTURE MIRROR (architecture/governance_postures.md) — the child's declared posture as a
+   *  root lineage annotation, so root's bailiff can consult it WITHOUT reading N tenant chains on the hot
+   *  path. AUTHORITATIVE is the tenant chain's own {@link GovernancePosture} singleton — this is the fast
+   *  path only; a mirror↔tenant MISMATCH fails CLOSED to sovereign at the custody act. Absent ⇒ `managed`
+   *  (the default). Set at birth ({@link birthChild}/{@link createWorkspace} `posture` payload). Additive/
+   *  era-safe (optional Lww). */
+  governancePosture: t.enum(GOVERNANCE_POSTURES).merge(Lww).optional(),
 });
 
 // AdminGrant / CreationGrant aggregates: DELETED (full-native Zanzibar). Admin/creation authority is
@@ -440,6 +460,10 @@ function planBirthRecord(
     tier: (typeof WORKSPACE_TIERS)[number];
     requestedBy: string;
     requestedAt: number;
+    /** GOVERNANCE POSTURE MIRROR (governance_postures.md) — the child's declared posture, mirrored onto its
+     *  root lineage record. Absent ⇒ managed (the default; never written when managed to keep the write
+     *  additive/minimal). */
+    posture?: (typeof GOVERNANCE_POSTURES)[number] | undefined;
   },
   genesis?: { foundingAdminHash: string; pool: number },
 ) {
@@ -452,6 +476,8 @@ function planBirthRecord(
     .set("ownerGrantHash", "") // no owner credential until provisioned
     .set("createdBy", p.requestedBy)
     .set("createdAt", p.requestedAt);
+  // POSTURE MIRROR: record it only when a non-default posture is declared (managed = absent — additive/era-safe).
+  if (p.posture && p.posture !== "managed") rec.set("governancePosture", p.posture);
   if (genesis) {
     rec
       .set("kind", "platform" as const) // DERIVED LABEL ONLY — the order's foundingAdminHash is the real signal
@@ -692,6 +718,9 @@ export const createWorkspace = directive("createWorkspace")
       principal: z.string().min(1),
       requestedBy: z.string().min(1),
       requestedAt: epochMs,
+      /** GOVERNANCE POSTURE (governance_postures.md) — the born workspace's declared posture; default
+       *  `managed`. Mirrored onto the lineage record (the tenant's own chain is authoritative). */
+      posture: z.enum(GOVERNANCE_POSTURES).optional(),
     }),
   )
   .plan((p) => {
@@ -1028,6 +1057,142 @@ export const rebirthRetainsLineage = workspaceInvariant("RebirthRetainsLineage")
  *  `/rebirth-custody` drain's queue). Keyed on `supersededBy` is unhelpful; the flat record read via
  *  {@link workspaceByName} suffices for the custody gate, so this stays a by-name lookup upstream. */
 
+// ─────────────────────────── GOVERNANCE POSTURES (managed / sovereign) ────────────────────────────────
+// architecture/governance_postures.md — v1, the BAILIFF-GRADE consent seam. A platform DECLARES its
+// governance posture as a fact in its OWN chain (the tenant owns the fact); it is mirrored onto root's
+// lineage record ({@link CloudWorkspace.governancePosture}) as a hot-path fast-path (a mismatch fails
+// CLOSED to sovereign at the custody act). Under `sovereign`, root's `rebirthWorkspace` custody act
+// REFUSES unless a live {@link RebirthConsent} fact — folded by the tenant's OWN admin, in the tenant's
+// OWN chain — is present (the two-key ceremony). All ADDITIVE / era-safe (a chain that never sets a
+// posture is `managed` and replays byte-identical). The v2 kernel-grade lane (attested-read consent
+// re-derived at the ROOT GATE on every lane) is the named follow-up — NOT built here.
+
+/** THE POSTURE SINGLETON INSTANCE ID — the platform's own declared posture lives at this constant id in
+ *  its OWN governance chain (the RelationTuple/AuthProvider discipline — a literal, never minted). */
+const GOVERNANCE_POSTURE_ID = "governance-posture:self";
+
+/**
+ * GovernancePosture — the platform's OWN declared governance posture (a law-state singleton, id
+ * `governance-posture:self`). `managed` (default when this record is absent) ⇒ the operator may run
+ * recovery verbs for the tenant; `sovereign` ⇒ recovery verbs require the tenant's {@link RebirthConsent}.
+ * The tenant owns this fact — it is set through the platform's own SIGNED governance offers
+ * ({@link setGovernancePosture} / {@link revokeOperator} / {@link grantOperator}).
+ */
+export const GovernancePosture = aggregate("GovernancePosture", {
+  /** The singleton key — always `"self"`. */
+  scope: t.string().merge(Lww),
+  /** `managed` | `sovereign`. */
+  posture: t.enum(GOVERNANCE_POSTURES).merge(Lww),
+  /** WHY the posture was last set (audit, on the ledger forever). */
+  reason: t.string().merge(Lww),
+  /** Who last set it (attribution — the signing principal). */
+  setBy: t.string().merge(Lww),
+  /** Epoch-ms it was last set (caller-stamped). */
+  setAt: t.int().merge(Lww),
+});
+
+/**
+ * RebirthConsent — the tenant's OWN consent to a rebirth, folded in the tenant's OWN chain (the two-key
+ * ceremony: the custody act cannot move without BOTH root's supersession fact AND this consent fact). A
+ * Sovereign workspace's operator restraint becomes law that replays, not host policy. `expiresAt` bounds
+ * the consent window (absent ⇒ until revoked-by-supersession). Keyed by the workspace NAME so the bailiff
+ * can resolve it while reading the tenant chain.
+ */
+export const RebirthConsent = aggregate("RebirthConsent", {
+  /** The workspace NAME this consent authorizes a rebirth of. */
+  workspaceId: t.string().merge(Lww),
+  /** WHY the tenant consents (audit). */
+  reason: t.string().merge(Lww),
+  /** The tenant admin that consented (attribution). */
+  consentedBy: t.string().merge(Lww),
+  /** Epoch-ms the consent was authored (caller-stamped). */
+  consentedAt: t.int().merge(Lww),
+  /** OPTIONAL epoch-ms expiry; absent = until superseded. Expired ⇒ the custody act treats it as absent. */
+  expiresAt: t.int().merge(Lww).optional(),
+});
+
+/** Shared plan body for the three posture setters — ensures the singleton to `posture`. */
+function setPosturePlan(posture: (typeof GOVERNANCE_POSTURES)[number], reason: string, setBy: string, at: number) {
+  const gp = instance(GovernancePosture, GOVERNANCE_POSTURE_ID);
+  return [
+    withMarker(set(gp, "scope", "self"), "ensures"),
+    set(gp, "posture", posture),
+    set(gp, "reason", reason),
+    set(gp, "setBy", setBy),
+    set(gp, "setAt", at),
+  ];
+}
+
+/**
+ * setGovernancePosture — the platform DECLARES (or changes) its posture. A SIGNED, admin-gated offer to the
+ * platform's OWN gateway — the tenant owns the fact. `managed → sovereign` withdraws the operator grant
+ * (forward-only; help already given stays in history); `sovereign → managed` re-invites help.
+ */
+export const setGovernancePosture = directive("setGovernancePosture")
+  .ensures(GovernancePosture)
+  .payload(
+    z.object({
+      /** The workspace this posture governs (the platform's own name — informational; the singleton is self-scoped). */
+      workspaceId: z.string().min(1),
+      posture: z.enum(GOVERNANCE_POSTURES),
+      reason: z.string().min(1),
+      /** The signing principal (attribution). */
+      setBy: z.string().min(1),
+      at: epochMs,
+    }),
+  )
+  .plan((p) => setPosturePlan(p.posture, p.reason, p.setBy, p.at))
+  .requires("admin");
+
+/** revokeOperator — posture sugar: `managed → sovereign` (withdraw the operator grant). */
+export const revokeOperator = directive("revokeOperator")
+  .ensures(GovernancePosture)
+  .payload(z.object({ workspaceId: z.string().min(1), reason: z.string().min(1), setBy: z.string().min(1), at: epochMs }))
+  .plan((p) => setPosturePlan("sovereign", p.reason, p.setBy, p.at))
+  .requires("admin");
+
+/** grantOperator — posture sugar: `sovereign → managed` (re-invite the operator's help). */
+export const grantOperator = directive("grantOperator")
+  .ensures(GovernancePosture)
+  .payload(z.object({ workspaceId: z.string().min(1), reason: z.string().min(1), setBy: z.string().min(1), at: epochMs }))
+  .plan((p) => setPosturePlan("managed", p.reason, p.setBy, p.at))
+  .requires("admin");
+
+/**
+ * consentToRebirth — the tenant's OWN consent to a rebirth (the Sovereign lane). A SIGNED, founding-admin-
+ * gated offer folding a {@link RebirthConsent} fact in the TENANT'S chain. The custody act reads it (v1) /
+ * the root gate re-derives it (v2) before superseding a Sovereign workspace.
+ */
+export const consentToRebirth = directive("consentToRebirth")
+  .creates(RebirthConsent)
+  .payload(
+    z.object({
+      workspaceId: z.string().min(1),
+      reason: z.string().min(1),
+      consentedBy: z.string().min(1),
+      consentedAt: epochMs,
+      expiresAt: epochMs.optional(),
+    }),
+  )
+  .plan((p) => {
+    const c = create(RebirthConsent)
+      .set("workspaceId", p.workspaceId)
+      .set("reason", p.reason)
+      .set("consentedBy", p.consentedBy)
+      .set("consentedAt", p.consentedAt);
+    if (p.expiresAt !== undefined) c.set("expiresAt", p.expiresAt);
+    return [];
+  })
+  .requires("admin");
+
+/** The platform's own declared posture (`scope: "self"` singleton) — the AUTHORITATIVE posture read. */
+export const governancePosture = query("governancePosture").key("scope").returns(GovernancePosture);
+
+/** The tenant's rebirth-consent facts for a workspace name — the custody act's Sovereign-lane consent probe. */
+export const rebirthConsentByWorkspace = query("rebirthConsentByWorkspace")
+  .key("workspaceId")
+  .returns(RebirthConsent);
+
 // ─────────────────────────── BIRTH AS A NOMOS PRIMITIVE ──────────────────────────────────────────────
 // (birthPlatform is GONE — the tier collapsed onto #creator; birthChild is the one birth directive.)
 // THE RECORD IS THE OBLIGATION (architecture/githolon_host_contract.md "Birth is a capability" +
@@ -1096,6 +1261,10 @@ export const birthChild = directive("birthChild")
          *  only pass it when the `lawHash` the order names carries `seedBirthPolicy` (a governance
          *  package compiled under the metered-birth DSL). Only meaningful with a genesis. */
         descendantPool: z.number().int().positive().optional(),
+        /** GOVERNANCE POSTURE (governance_postures.md) — the born child's declared posture; default
+         *  `managed`. Mirrored onto its lineage record so root's bailiff can consult it on the hot path
+         *  (the tenant's own {@link GovernancePosture} singleton is authoritative). Additive/era-safe. */
+        posture: z.enum(GOVERNANCE_POSTURES).optional(),
       })
       // A genesis birth (a platform) must carry a principal AND a bornAt — it owns a subtree, a lineage
       // anchor, and a law-authored genesis chain whose warrant is stamped at bornAt.

package/src/index.ts

@@ -597,6 +597,19 @@ export {
   type RelationOpts,
   type SugaredRelationTypeBuilder,
 } from "./relation_sugar.js";
+// ROLE SUGAR — the highest-level authz surface: `role("editor").canEdit(Note).canView(Note)
+// .grantableBy("admin")` LOWERS onto the ONE Zanzibar spine (relation tuples + the kernel gate) —
+// emitting the relation schema (teeth, no fail-open), grant/revoke/seed directives, typed policy
+// refs (role.edit / role.view), and codegen canEdit/canView UI helpers. NO role-array auth anywhere.
+export {
+  role,
+  isRoleEmission,
+  expandRoleExports,
+  rolesOf,
+  type RoleBuilder,
+  type RoleEmission,
+  type RoleMeta,
+} from "./role.js";
 export { csv, csvRows } from "./report/csv.js";
 // CertifiedRead — the DECLARED write-path read surface (survival Constraint 5;
 // `certified_read.md`). A directive declares profiled reads via `.readsCertified({ name:

package/src/read_projection_namespace.ts

@@ -109,6 +109,9 @@ export const GLOBAL_READ_PROJECTION_AGGREGATE_IDS: ReadonlySet<string> = new Set
   "CapabilityBinding",
   "AuthProvider",
   "HostnameClaim",
+  // governance postures (managed / sovereign) — the tenant-owned posture singleton + consent facts
+  "GovernancePosture",
+  "RebirthConsent",
 ]);
 
 /** The minimal handle shape the classification reads (compiler AND engine — one function). */

package/src/role.ts

@@ -0,0 +1,292 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * role — ROLE SUGAR over the ONE Zanzibar/ReBAC spine.
+ *
+ * A `role("editor").canEdit(Note).canView(Note).grantableBy("admin")` declaration is PURE SUGAR
+ * that LOWERS onto the native relation spine — there is NO role-array membership check anywhere,
+ * and NOTHING kernel-judged stops being kernel-judged. A role EMITS:
+ *
+ *   1. RELATION TYPE entries + schema — the `<role>Edit` write relation is authored into a
+ *      `relationType("workspace")` block (the fail-open footgun is CLOSED — a `.requires(role.edit)`
+ *      always finds a declared relation), and the `<role>View` relation is a READ-VISIBILITY cap
+ *      (used as an aggregate `requires(role.view)` — usd.ts synthesizes the global workspace read
+ *      relation, exactly as any private aggregate does). The grant-authority relation (`grantableBy`,
+ *      default `admin`) is likewise authored into the schema so the gate on the grant directive has teeth.
+ *
+ *   2. GRANT / SEED DIRECTIVES per role — `grant<Role>` / `revoke<Role>` fold the relation TUPLE via
+ *      the existing `writeTuple`/`removeTuple` primitives (a grant seats `<role>Edit` + `<role>View`
+ *      on `user:<principal>`), gated `.requires(grantableBy)` — the KERNEL judges the granter. A
+ *      `seed<Role>` UNGATED directive seats the `grantableBy` relation on a founding principal at
+ *      genesis/birth (the birthHome seed pattern) so the grant-authority exists from intent 0.
+ *
+ *   3. POLICY REFS — the role handle is usable DIRECTLY, typed (never strings): `.requires(editor.edit)`
+ *      on a mutating directive, `requires(editor.view)` as an aggregate visibility.
+ *
+ *   4. CODEGEN `canEdit<Agg>` / `canView<Agg>` — per (role × aggregate) TS + Dart helpers that evaluate
+ *      LOCALLY against the folded RelationTuple projection (the client-side MIRROR of `engine.check`).
+ *      They are INFORMATIONAL / UI-gating ONLY — THE KERNEL GATE REMAINS THE AUTHORITY and refuses
+ *      regardless of what the helper returns (documented in the emitted doc-comment).
+ *
+ * NOTHING here adds a role ARRAY as auth: every capability lowers to ONE relation tuple + the ONE
+ * kernel gate. Roles are workspace-scoped (object `workspace:self`) — the read-visibility gate is
+ * workspace-scoped in the kernel, so a per-record VIEW cap could not have teeth; per-record grants are
+ * a documented follow-on (the `.requires(rel, { objectFrom })` axis is unchanged and still available).
+ */
+import { z } from "zod";
+import type { AggregateHandle } from "./aggregate.js";
+import type { Directive, RequirableDirective } from "./directive.js";
+import { directive } from "./directive.js";
+import { RelationTuple, writeTuple, removeTuple } from "./framework/relations.js";
+import { relationType, self, user, key, type RelationTypeDecl } from "./relation_schema.js";
+
+/** A role name: kebab-case (`editor`, `site-admin`) — lowered to relation/directive labels. */
+const ROLE_NAME_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+const camel = (s: string): string => s.replace(/-+(\w)/g, (_m, c: string) => c.toUpperCase());
+const pascal = (s: string): string => {
+  const c = camel(s);
+  return c.length ? c[0]!.toUpperCase() + c.slice(1) : c;
+};
+
+/**
+ * The codegen + expander view of one emitted role — pure metadata (NOT law, NOT hashed): the role
+ * name, its lowered edit/view relation names, the grant-authority relation, and the aggregates it
+ * covers. The compiler reads THIS to synthesize the schema block and the `canEdit`/`canView` helpers.
+ */
+export interface RoleMeta {
+  readonly role: string;
+  /** The `<role>Edit` write relation (present iff the role `.canEdit`s ≥1 aggregate). */
+  readonly editRelation?: string;
+  /** The `<role>View` read-visibility relation (present iff the role `.canView`s ≥1 aggregate). */
+  readonly viewRelation?: string;
+  /** The relation the granter must HOLD to grant/revoke this role (default `admin`). */
+  readonly grantableBy: string;
+  /** The aggregate TYPE ids this role may edit (drives `canEdit<Agg>` codegen). Sorted. */
+  readonly editAggregates: readonly string[];
+  /** The aggregate TYPE ids this role may view (drives `canView<Agg>` codegen). Sorted. */
+  readonly viewAggregates: readonly string[];
+}
+
+/**
+ * The value `role(...).emit()` returns — a discoverable container the compiler expands (like a
+ * `capability()` bundle): its `directives` (grant/revoke/seed) are lifted into the module's directive
+ * set, and its `meta` drives the synthesized relation schema + codegen. Branded so `expandRoleExports`
+ * / `rolesOf` find it by shape (`__isRoleEmission`).
+ */
+export interface RoleEmission {
+  readonly __isRoleEmission: true;
+  readonly meta: RoleMeta;
+  readonly directives: readonly Directive<unknown>[];
+}
+
+export function isRoleEmission(v: unknown): v is RoleEmission {
+  return typeof v === "object" && v !== null && (v as { __isRoleEmission?: unknown }).__isRoleEmission === true;
+}
+
+/** The fluent role builder. `role.edit` / `role.view` are the typed POLICY REFS (relation names). */
+export interface RoleBuilder {
+  /** The role name (kebab-case). */
+  readonly name: string;
+  /** POLICY REF — the `<role>Edit` write relation, for `.requires(role.edit)` on a mutating directive. */
+  readonly edit: string;
+  /** POLICY REF — the `<role>View` read relation, for an aggregate `requires(role.view)` visibility. */
+  readonly view: string;
+  /** Declare that this role may EDIT `agg` (its `<role>Edit` relation gates `agg`'s mutating directives). */
+  canEdit(agg: AggregateHandle): RoleBuilder;
+  /** Declare that this role may VIEW `agg` (wire `agg`'s visibility to `role.view` for teeth). */
+  canView(agg: AggregateHandle): RoleBuilder;
+  /** Who may grant/revoke this role — a relation ref (default `admin`). Seeded via `seed<Role>` at genesis. */
+  grantableBy(relation: string): RoleBuilder;
+  /** Finalize — emit the grant/revoke/seed directives + the metadata the compiler lowers. */
+  emit(): RoleEmission;
+}
+
+interface RoleState {
+  readonly name: string;
+  readonly editRelation: string;
+  readonly viewRelation: string;
+  readonly grantableBy: string;
+  readonly editAggregates: string[];
+  readonly viewAggregates: string[];
+  readonly canEdit: boolean;
+  readonly canView: boolean;
+}
+
+function aggId(agg: AggregateHandle, verb: string, role: string): string {
+  if (agg === null || typeof agg !== "object" || typeof (agg as { id?: unknown }).id !== "string" || (agg as { id: string }).id.length === 0) {
+    throw new Error(`role("${role}").${verb}(...): expected an aggregate handle with a string id (pass the aggregate(...) handle, not its name)`);
+  }
+  return (agg as { id: string }).id;
+}
+
+function build(s: RoleState): RoleBuilder {
+  const builder: RoleBuilder = {
+    name: s.name,
+    edit: s.editRelation,
+    view: s.viewRelation,
+    canEdit(agg: AggregateHandle): RoleBuilder {
+      const id = aggId(agg, "canEdit", s.name);
+      if (s.editAggregates.includes(id)) return builder;
+      return build({ ...s, canEdit: true, editAggregates: [...s.editAggregates, id] });
+    },
+    canView(agg: AggregateHandle): RoleBuilder {
+      const id = aggId(agg, "canView", s.name);
+      if (s.viewAggregates.includes(id)) return builder;
+      return build({ ...s, canView: true, viewAggregates: [...s.viewAggregates, id] });
+    },
+    grantableBy(relation: string): RoleBuilder {
+      if (typeof relation !== "string" || relation.length === 0) {
+        throw new Error(`role("${s.name}").grantableBy(...): expected a non-empty relation name`);
+      }
+      return build({ ...s, grantableBy: relation });
+    },
+    emit(): RoleEmission {
+      if (!s.canEdit && !s.canView) {
+        throw new Error(`role("${s.name}").emit(): a role must declare at least one .canEdit(...) or .canView(...)`);
+      }
+      const editRelation = s.canEdit ? s.editRelation : undefined;
+      const viewRelation = s.canView ? s.viewRelation : undefined;
+      const P = pascal(s.name);
+      // The subject of a grant is the `user:<uid>` leaf — the SAME wire form the kernel's Subject::parse
+      // reads (a bare uid never forges a wildcard/userset; the reserved-token rules live in relatePayload).
+      const seatTuples = (principal: string, grantedBy: string, grantedAt: string) => [
+        ...(editRelation ? writeTuple({ object: "workspace:self", relation: editRelation, subject: `user:${principal}`, grantedBy, grantedAt }) : []),
+        ...(viewRelation ? writeTuple({ object: "workspace:self", relation: viewRelation, subject: `user:${principal}`, grantedBy, grantedAt }) : []),
+      ];
+
+      const grantPayload = z.object({
+        principal: z.string().min(1),
+        grantedBy: z.string().min(1),
+        grantedAt: z.string().min(1),
+      });
+      let grantDir: RequirableDirective<z.infer<typeof grantPayload>> = directive(`grant${P}`)
+        .ensures(RelationTuple)
+        .payload(grantPayload)
+        .plan((p) => seatTuples(p.principal, p.grantedBy, p.grantedAt))
+        .doc(`Grant the "${s.name}" role to a principal (seats the relation tuple; the kernel judges the granter via .requires("${s.grantableBy}")).`)
+        .requires(s.grantableBy);
+      // Proof-tooling hint: this directive ESTABLISHES the role's relations (so the relation-bootstrap
+      // proof leg seats a role-holder before proving a `.requires(role.edit)`-gated write).
+      if (editRelation) grantDir = grantDir.grants(editRelation);
+      if (viewRelation) grantDir = grantDir.grants(viewRelation);
+
+      const revokePayload = grantPayload.extend({
+        revokedBy: z.string().min(1),
+        revokedAt: z.string().min(1),
+      });
+      const revokeDir: RequirableDirective<z.infer<typeof revokePayload>> = directive(`revoke${P}`)
+        .ensures(RelationTuple)
+        .payload(revokePayload)
+        .plan((p) => [
+          ...(editRelation ? removeTuple({ object: "workspace:self", relation: editRelation, subject: `user:${p.principal}`, grantedBy: p.grantedBy, grantedAt: p.grantedAt, revokedBy: p.revokedBy, revokedAt: p.revokedAt }) : []),
+          ...(viewRelation ? removeTuple({ object: "workspace:self", relation: viewRelation, subject: `user:${p.principal}`, grantedBy: p.grantedBy, grantedAt: p.grantedAt, revokedBy: p.revokedBy, revokedAt: p.revokedAt }) : []),
+        ])
+        .doc(`Revoke the "${s.name}" role from a principal (remove-wins: the projection drops the tuple; a replayed grant cannot resurrect it).`)
+        .requires(s.grantableBy);
+
+      // THE SEED LANE (genesis/birth) — seat the grant-authority relation on a founding principal, UNGATED,
+      // so the granter exists from intent 0 (the seedHomeOwner shape: a genesis-chain step, refused on the
+      // open session lane structurally like any control write). Grants nothing but the authority to grant.
+      const seedPayload = z.object({
+        principal: z.string().min(1),
+        grantedAt: z.string().min(1),
+      });
+      const seedDir: RequirableDirective<z.infer<typeof seedPayload>> = directive(`seed${P}`)
+        .ensures(RelationTuple)
+        .payload(seedPayload)
+        .plan((p) => writeTuple({ object: "workspace:self", relation: s.grantableBy, subject: `user:${p.principal}`, grantedBy: p.principal, grantedAt: p.grantedAt }))
+        .doc(`Seed the "${s.grantableBy}" grant-authority on a founding principal (genesis/birth only).`)
+        .grants(s.grantableBy);
+
+      const meta: RoleMeta = {
+        role: s.name,
+        ...(editRelation ? { editRelation } : {}),
+        ...(viewRelation ? { viewRelation } : {}),
+        grantableBy: s.grantableBy,
+        editAggregates: [...s.editAggregates].sort(),
+        viewAggregates: [...s.viewAggregates].sort(),
+      };
+      return {
+        __isRoleEmission: true,
+        meta,
+        directives: [grantDir, revokeDir, seedDir] as unknown as Directive<unknown>[],
+      };
+    },
+  };
+  return builder;
+}
+
+/**
+ * `role("editor")` — begin a role declaration. `role.edit` / `role.view` (the typed policy refs) are
+ * available IMMEDIATELY (derived from the name, no aggregate needed) so an aggregate can wire
+ * `requires(editor.view)` before the role is `.emit()`ed (no declaration-order cycle).
+ */
+export function role(name: string): RoleBuilder {
+  if (typeof name !== "string" || !ROLE_NAME_RE.test(name)) {
+    throw new Error(`role(${JSON.stringify(name)}): a role name must be kebab-case (${ROLE_NAME_RE})`);
+  }
+  const base = camel(name);
+  return build({
+    name,
+    editRelation: `${base}Edit`,
+    viewRelation: `${base}View`,
+    grantableBy: "admin",
+    editAggregates: [],
+    viewAggregates: [],
+    canEdit: false,
+    canView: false,
+  });
+}
+
+/** Collect every emitted role's metadata from a module's exports bag (by shape) — sorted by role name. */
+export function rolesOf(mod: Record<string, unknown>): RoleMeta[] {
+  const out: RoleMeta[] = [];
+  for (const v of Object.values(mod)) if (isRoleEmission(v)) out.push(v.meta);
+  return out.sort((a, b) => (a.role < b.role ? -1 : a.role > b.role ? 1 : 0));
+}
+
+/** The injected export key for the role-synthesized `relationType("workspace")` block. */
+const ROLE_RELATIONS_KEY = "__nomosRoleRelations";
+
+/**
+ * EXPANDER (the `capability()`/birth-meter seam): given a module's exports bag, LIFT every `RoleEmission`
+ * into discoverable entries — the grant/revoke/seed directives become top-level exports (so `directivesOf`
+ * finds them), and ONE synthesized `relationType("workspace")` (the `<role>Edit` write relations + the
+ * distinct `grantableBy` grant-authority relations, deduped) becomes a discoverable relation type (so
+ * `.requires(role.edit)` / `.requires(grantableBy)` have TEETH — the fail-open footgun is closed). The
+ * `<role>View` read relations are NOT authored here: they are read-visibility caps, synthesized by usd.ts
+ * from the aggregates that declare `requires(role.view)`. IDEMPOTENT + additive: a bag with no role is
+ * returned unchanged (byte-identical), and re-running on an already-expanded bag is a no-op.
+ */
+export function expandRoleExports(mod: Record<string, unknown>): Record<string, unknown> {
+  const emissions: RoleEmission[] = [];
+  for (const v of Object.values(mod)) if (isRoleEmission(v)) emissions.push(v);
+  if (emissions.length === 0) return mod;
+  if (ROLE_RELATIONS_KEY in mod) return mod; // already expanded (idempotent)
+
+  const out: Record<string, unknown> = { ...mod };
+  // ONE workspace-scoped relation block covering every role's authored (edit + grant-authority) relations.
+  const builder = relationType("workspace");
+  const declared = new Set<string>();
+  const declare = (rel: string): void => {
+    if (declared.has(rel)) return;
+    declared.add(rel);
+    // A flat direct-membership relation, leaf subjects only (user + the control-plane key) — the same
+    // shape the read-visibility synthesis + governance control relations use (never a userset/wildcard).
+    builder.relation(rel, { rewrite: self(), allow: [user(), key()] });
+  };
+  for (const e of emissions) {
+    if (e.meta.editRelation) declare(e.meta.editRelation);
+    declare(e.meta.grantableBy);
+    for (const dir of e.directives) {
+      const anyDir = dir as { id: string };
+      out[`__role_${anyDir.id}`] = dir;
+    }
+  }
+  out[ROLE_RELATIONS_KEY] = builder as unknown as RelationTypeDecl;
+  return out;
+}