@githolon/dsl 0.108.6 → 0.110.0

package/src/framework/console_governance.ts

@@ -0,0 +1,295 @@
+// 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.
+
+/**
+ * framework/console_governance.ts — THE CONSOLE'S LAWFUL REACH INTO EVERY WORKSPACE OF ITS JURISDICTION
+ * (identity target model D15, D18, D22, D23).
+ *
+ * A founded child inherits its parent's `operator` and `principalScope:<s>#enroller` tuples (the founding
+ * step). Three things make that inheritance usable, and let the real operators replace a stand-in without
+ * re-founding anything:
+ *
+ * 1. **Keys and law authority at founding** — {@link seedInheritedGovernance}. The kernel's signer rule
+ *    reads `identity:P#signer` only from the child's own state, and law is installed under
+ *    `workspace:self#installDomain`, so an inherited principal holding neither can do nothing there.
+ *    The step copies, once, every ACTIVE key the parent holds for each inherited operator and enroller,
+ *    and seats `installDomain` for each inherited operator (an operator is who installs law, D15). Keys
+ *    live on every workspace: that is what keeps each one independently replayable. It also copies the
+ *    parent's active admission-checkpoint workload keys, so a child can receive workspace effects from
+ *    its first moment instead of waiting for an operator to seat its custodian's key.
+ * 2. **Operator handover after birth** — {@link grantConsoleOperator} / {@link revokeConsoleOperator},
+ *    gated on `operator` itself (a founded child's admin is its founder, a user, who is not the
+ *    jurisdiction). Only `console:` principals, and always the PAIR `operator` + `installDomain`.
+ *    Operators already hold `installDomain` (total authority over law), so letting them pass it on grants
+ *    nothing new. A revoke that would leave no operator is refused.
+ * 3. **Key rotation for console principals** — {@link enrollConsoleSigner} / {@link revokeConsoleSigner},
+ *    self-bound: a principal signs with a current key to add or revoke one of ITS OWN keys, never anyone
+ *    else's, and never its last one. `console:` only: device self-enrolment for other scopes stays with
+ *    their enrollers.
+ */
+import { z } from "zod";
+import { directive } from "../directive.js";
+import { readFrameworkDeclaredRows } from "../read.js";
+import { CONSOLE_PRINCIPAL_SCOPE, principalScopeOf } from "../member_authentication.js";
+import { endorsementOf } from "../principal_evidence.js";
+import { GENESIS_WARRANT_ID } from "./genesis.js";
+import { MODEL_LIFECYCLE_AUTHORITY } from "./domain_lifecycle.js";
+import { WORKSPACE_OPERATOR_RELATION } from "./governance_relations.js";
+import { RelationTuple, relationTupleInstanceId, relationTuplesByObject, removeTuple, writeTuple } from "./relations.js";
+import {
+  admissionCheckpointSigner,
+  readAdmissionCheckpointSigners,
+  signerObject,
+  SIGNER_RELATION,
+  writeAdmissionCheckpointSigners,
+  type AdmissionCheckpointSigner,
+} from "./signing_identity.js";
+import { readRef, readSet, refAs, workspaceInvariant } from "./workspace_invariant.js";
+
+/** The `grantedBy` of everything the founding step {@link seedInheritedGovernance} seats. */
+export const INHERITED_SIGNER_GRANTOR = "inherited-at-birth" as const;
+export const SEED_INHERITED_GOVERNANCE_DIRECTIVE = "seedInheritedGovernance" as const;
+
+const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/, "expected lowercase sha256 hex (a public key hash)");
+const scopedPrincipal = z.string().min(1).refine((p) => principalScopeOf(p) !== undefined, "a <scope>:<subject> principal");
+/** `console:<subject>` — the principal-subject grammar (`principalScopeOf`), as a regex the compiler's
+ *  probe can sample. */
+const consolePrincipal = z
+  .string()
+  .regex(/^console:[A-Za-z0-9][A-Za-z0-9_.:/-]{0,255}$/, "a console principal is console:<subject>");
+
+type ActiveLeaf = { status?: string };
+const activeSubjects = (tuple: unknown): string[] =>
+  Object.entries(((tuple as { subjects?: Record<string, ActiveLeaf> } | undefined)?.subjects) ?? {})
+    .filter(([, leaf]) => leaf?.status === "active")
+    .map(([subject]) => subject);
+
+// ─────────────────────────────── 1. at founding ───────────────────────────────
+
+export const inheritedGovernancePayload = z
+  .object({
+    /** Each inherited operator or enroller principal and one of its active parent keys, sorted. */
+    signers: z.array(z.object({ principal: scopedPrincipal, keyHash: sha256Hex }).strict()).default([]),
+    /** Each inherited operator principal: seated on `workspace:self#installDomain`, sorted. */
+    modelAuthorities: z.array(scopedPrincipal).default([]),
+    grantedAt: z.number().int().nonnegative(),
+    /** The parent's active admission-checkpoint workload keys, so the child can receive workspace
+     *  effects from birth. Absent when the parent has none (a recipe without it is unchanged). */
+    admissionCheckpointSigners: z.array(admissionCheckpointSigner).optional(),
+  })
+  .strict()
+  .refine((p) => p.signers.length + p.modelAuthorities.length + (p.admissionCheckpointSigners?.length ?? 0) > 0,
+    { message: "nothing to seat", path: ["signers"] });
+
+export type InheritedSigner = { readonly principal: string; readonly keyHash: string };
+
+/** `seedInheritedGovernance` — see the module doc (1). Warrant-free prefix only. */
+export const seedInheritedGovernance = directive(SEED_INHERITED_GOVERNANCE_DIRECTIVE)
+  .ensures(RelationTuple)
+  .payload(inheritedGovernancePayload)
+  .plan((p) => [
+    ...p.signers.flatMap((signer) =>
+      writeTuple({
+        object: signerObject(signer.principal),
+        relation: SIGNER_RELATION,
+        subject: `key:${signer.keyHash}`,
+        grantedBy: INHERITED_SIGNER_GRANTOR,
+        grantedAt: String(p.grantedAt),
+      })),
+    ...p.modelAuthorities.flatMap((principal) =>
+      writeTuple({
+        object: "workspace:self",
+        relation: MODEL_LIFECYCLE_AUTHORITY,
+        subject: principal,
+        grantedBy: INHERITED_SIGNER_GRANTOR,
+        grantedAt: String(p.grantedAt),
+      })),
+    ...writeAdmissionCheckpointSigners(p.admissionCheckpointSigners ?? [], INHERITED_SIGNER_GRANTOR),
+  ]);
+
+export const inheritedGovernanceBeforeWarrant = workspaceInvariant("InheritedGovernanceBeforeWarrant")
+  .on(SEED_INHERITED_GOVERNANCE_DIRECTIVE)
+  .reads(readSet(readRef("warrant", "GenesisWarrant").pre().at(GENESIS_WARRANT_ID)))
+  .assert(({ warrant }) =>
+    (warrant as { principal?: string } | undefined)?.principal
+      ? { reject: "inherited-governance-after-warrant" }
+      : { accept: true });
+
+/** The parent's active keys for each principal, one `relationTuplesByObject` read per principal. */
+export function readInheritedSigners(principals: readonly string[]): readonly InheritedSigner[] {
+  const out: InheritedSigner[] = [];
+  for (const principal of [...new Set(principals)].filter((p) => principalScopeOf(p) !== undefined).sort()) {
+    const rows = readFrameworkDeclaredRows(relationTuplesByObject, RelationTuple, { object: signerObject(principal) });
+    const row = rows.find((candidate) => candidate.relation === SIGNER_RELATION);
+    for (const subject of activeSubjects(row)) {
+      if (/^key:[0-9a-f]{64}$/.test(subject)) out.push({ principal, keyHash: subject.slice("key:".length) });
+    }
+  }
+  return out.sort((a, b) =>
+    a.principal < b.principal ? -1 : a.principal > b.principal ? 1 : a.keyHash < b.keyHash ? -1 : a.keyHash > b.keyHash ? 1 : 0);
+}
+
+/**
+ * The founding step for a founded birth, or none when nothing is inherited. `operators` and `enrollers`
+ * are the subjects the founding step seats (`readInheritedOperators` / `readInheritedEnrollers`); bare
+ * `key:` subjects are their own principals and need nothing.
+ */
+export function inheritedGovernanceStep(
+  domain: string,
+  actor: string,
+  operators: readonly string[],
+  enrollers: readonly { readonly subject: string }[],
+  grantedAt: number,
+  founding: InheritedSigner,
+): Array<{ domain: string; directiveId: string; actor: string; payload: Record<string, unknown> }> {
+  const signers = readInheritedSigners([...operators, ...enrollers.map((e) => e.subject)]);
+  return inheritedGovernanceStepFrom(domain, actor, operators, signers, grantedAt, founding,
+    readAdmissionCheckpointSigners());
+}
+
+/**
+ * The pure half of {@link inheritedGovernanceStep}, for recipe builders handed already-read signers.
+ *
+ * `founding` is the (principal, key) the founding step already seated. That leaf is never rewritten:
+ * when the founder is also an inherited operator or enroller, its founding key keeps its `genesis`
+ * grant — the mark a founded parent's births select the founded recipe by — and the founder's OTHER
+ * parent keys are still copied.
+ */
+export function inheritedGovernanceStepFrom(
+  domain: string,
+  actor: string,
+  operators: readonly string[],
+  allSigners: readonly InheritedSigner[],
+  grantedAt: number,
+  founding: InheritedSigner,
+  checkpointSigners: readonly AdmissionCheckpointSigner[] = [],
+): Array<{ domain: string; directiveId: string; actor: string; payload: Record<string, unknown> }> {
+  const signers = allSigners.filter((s) => !(s.principal === founding.principal && s.keyHash === founding.keyHash));
+  const modelAuthorities = [...new Set(operators)].filter((p) => principalScopeOf(p) !== undefined).sort();
+  if (signers.length === 0 && modelAuthorities.length === 0 && checkpointSigners.length === 0) return [];
+  return [{
+    domain,
+    directiveId: seedInheritedGovernance.id,
+    actor,
+    payload: inheritedGovernancePayload.parse({
+      signers: [...signers],
+      modelAuthorities,
+      grantedAt,
+      ...(checkpointSigners.length > 0 ? { admissionCheckpointSigners: [...checkpointSigners] } : {}),
+    }) as Record<string, unknown>,
+  }];
+}
+
+// ─────────────────────────────── 2. operator handover ───────────────────────────────
+
+const operatorPayload = z.object({ consolePrincipal, at: z.number().int().nonnegative() }).strict();
+
+/** The operator/installDomain pair for one principal. */
+function operatorPair(subject: string, at: string, grantedBy: string) {
+  return [
+    { object: "workspace:self", relation: WORKSPACE_OPERATOR_RELATION, subject, grantedBy, grantedAt: at },
+    { object: "workspace:self", relation: MODEL_LIFECYCLE_AUTHORITY, subject, grantedBy, grantedAt: at },
+  ];
+}
+
+/** `grantConsoleOperator` — an operator seats another console principal as operator (with installDomain). */
+export const grantConsoleOperator = directive("grantConsoleOperator")
+  .ensures(RelationTuple)
+  .payload(operatorPayload)
+  .plan((p, ctx) => {
+    const by = endorsementOf(ctx.principal().asAuthoritySubject<string>("hand the law operator seat to a console principal"))?.principal ?? "";
+    return operatorPair(p.consolePrincipal, String(p.at), by).flatMap((tuple) => writeTuple(tuple));
+  })
+  .requires(WORKSPACE_OPERATOR_RELATION);
+
+/** `revokeConsoleOperator` — an operator removes a console principal's operator seat (and installDomain). */
+export const revokeConsoleOperator = directive("revokeConsoleOperator")
+  .ensures(RelationTuple)
+  .payload(operatorPayload)
+  .plan((p, ctx) => {
+    const by = endorsementOf(ctx.principal().asAuthoritySubject<string>("withdraw a console principal's law operator seat"))?.principal ?? "";
+    return operatorPair(p.consolePrincipal, String(p.at), by).flatMap((tuple) =>
+      removeTuple({ ...tuple, revokedBy: by, revokedAt: String(p.at) }));
+  })
+  .requires(WORKSPACE_OPERATOR_RELATION);
+
+/** A workspace always keeps an operator: the jurisdiction never locks itself out of its own law. */
+export const lastOperatorRemains = workspaceInvariant("LastOperatorRemains")
+  .on("revokeConsoleOperator")
+  .reads(() => [refAs("tuple", "RelationTuple", "pre:" + relationTupleInstanceId("workspace:self", WORKSPACE_OPERATOR_RELATION))])
+  .assert(({ tuple }, ctx) => {
+    const leaving = String(((ctx?.intent ?? {}) as { consolePrincipal?: string }).consolePrincipal ?? "");
+    return activeSubjects(tuple).some((subject) => subject !== leaving)
+      ? { accept: true }
+      : { reject: "last-operator-cannot-be-revoked" };
+  });
+
+// ─────────────────────────────── 3. console key rotation ───────────────────────────────
+
+const signerPayload = z.object({ keyHash: sha256Hex, at: z.number().int().nonnegative() }).strict();
+
+function ownConsolePrincipal(ctx: { principal(): { asAuthoritySubject<T>(why: string): T } }, why: string): string {
+  const principal = endorsementOf(ctx.principal().asAuthoritySubject<string>(why))?.principal ?? "";
+  if (principalScopeOf(principal) !== CONSOLE_PRINCIPAL_SCOPE) {
+    throw new Error("console-signer-lane-is-for-console-principals");
+  }
+  return principal;
+}
+
+/** `enrollConsoleSigner` — a console principal, signing with a current key, adds a key to ITSELF. */
+export const enrollConsoleSigner = directive("enrollConsoleSigner")
+  .ensures(RelationTuple)
+  .payload(signerPayload)
+  .plan((p, ctx) => {
+    const me = ownConsolePrincipal(ctx as never, "add a signer key to my own console identity");
+    return writeTuple({
+      object: signerObject(me),
+      relation: SIGNER_RELATION,
+      subject: `key:${p.keyHash}`,
+      grantedBy: me,
+      grantedAt: String(p.at),
+    });
+  });
+
+/** `revokeConsoleSigner` — a console principal revokes one of ITS OWN keys, never its last. */
+export const revokeConsoleSigner = directive("revokeConsoleSigner")
+  .ensures(RelationTuple)
+  .payload(signerPayload)
+  .plan((p, ctx) => {
+    const me = ownConsolePrincipal(ctx as never, "revoke a signer key of my own console identity");
+    return removeTuple({
+      object: signerObject(me),
+      relation: SIGNER_RELATION,
+      subject: `key:${p.keyHash}`,
+      grantedBy: me,
+      grantedAt: String(p.at),
+      revokedBy: me,
+      revokedAt: String(p.at),
+    });
+  });
+
+export const lastConsoleSignerRemains = workspaceInvariant("LastConsoleSignerRemains")
+  .on("revokeConsoleSigner")
+  .reads((ctx) => [
+    refAs("tuple", "RelationTuple", "pre:" + relationTupleInstanceId(signerObject(String(ctx.principal ?? "")), SIGNER_RELATION)),
+  ])
+  .assert(({ tuple }, ctx) => {
+    const leaving = `key:${String(((ctx?.intent ?? {}) as { keyHash?: string }).keyHash ?? "")}`;
+    return activeSubjects(tuple).some((subject) => subject !== leaving)
+      ? { accept: true }
+      : { reject: "last-signer-key-cannot-be-revoked" };
+  });
+
+/** Everything this module contributes to a law, for the laws that compose it. */
+export const consoleGovernanceLaw = {
+  seedInheritedGovernance,
+  inheritedGovernanceBeforeWarrant,
+  grantConsoleOperator,
+  revokeConsoleOperator,
+  lastOperatorRemains,
+  enrollConsoleSigner,
+  revokeConsoleSigner,
+  lastConsoleSignerRemains,
+} as const;

package/src/framework/delegated_roles.ts

@@ -0,0 +1,301 @@
+// 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.
+
+/**
+ * framework/delegated_roles.ts — ROLES A PARENT DELEGATES INTO THE CHILDREN ITS PRINCIPALS FOUND
+ * (identity target model D22).
+ *
+ * Before D22 a platform delegated a role into a child a user founded (a Home's right to birth estates,
+ * say) by a signed delegation CERTIFICATE carried on each intent and re-verified per write
+ * (`.delegatedRole(...)`). The certificate lane is deleted; the role becomes an ordinary state tuple
+ * in the child, seeded once at founding exactly like the inherited operator and enroller tuples (D15).
+ *
+ * - **The child's law declares what is delegable, by relation-schema reference.** A tenant domain
+ *   calls {@link delegatedRoles}(relationType, [names]) and exports what it returns: the founding seed
+ *   and the post-birth adoption lane. Both write through `selfObject(relationType)`, so the tuple object
+ *   is qualified EXACTLY as the law's own `.requires(...)` gates are (a tenant type lives on
+ *   `<domain namespace>__<type>:self`, never the bare `<type>:self`), and both refuse any relation the
+ *   declaration does not list. They run dispatched in the declaring domain.
+ * - **The parent states the policy** once per principal scope: `grantDelegatedRole { scope, childKind,
+ *   domain, objectType, relation }` — "every `<scope>:` principal who founds a `<childKind>` child here
+ *   holds `<objectType>#<relation>` from `<domain>`'s law in it". It is an ordinary relation tuple,
+ *   `nomosDelegatedRole:<childKind>.<domain>.<objectType>.<relation>#delegatedTo@principalScope:<scope>`,
+ *   read through the `relationTuplesByRelation` read every founded birth already declares.
+ *   `revokeDelegatedRole` withdraws it for children founded afterwards.
+ * - **A founded birth** authors one `seedDelegatedRoles` step per named domain for its founder, granted
+ *   by {@link DELEGATED_ROLE_GRANTOR}, on the warrant-free prefix only. Later grants and revokes reach
+ *   an existing child through `adoptDelegatedRoles`, authored there by an enroller of the principal's
+ *   scope (the jurisdiction's hosted backend, which holds a key in every founded child).
+ *
+ * `childKind` scopes a grant to one kind of child: `receiving-group` for a Home, a business birth's
+ * namespace (e.g. `estate`) otherwise. A grant naming a domain whose law does not publish the seed fails
+ * that child's birth, so a tenant declares {@link delegatedRoles} in every domain its grants name.
+ */
+import { z } from "zod";
+import { directive, type Directive } from "../directive.js";
+import { readFrameworkDeclaredRows } from "../read.js";
+import { principalScopeOf } from "../member_authentication.js";
+import { object, relationType, self, selfObject, type RelationTypeDecl } from "../relation_schema.js";
+import { GENESIS_WARRANT_ID } from "./genesis.js";
+import { RelationTuple, removeTuple, writeTuple } from "./relations.js";
+import {
+  PRINCIPAL_SCOPE_OBJECT_TYPE,
+  principalScopeRelations,
+  providerScopeField,
+  relationTuplesByRelation,
+} from "./principal_enrollment.js";
+import { readRef, readSet, workspaceInvariant } from "./workspace_invariant.js";
+
+/** The child kind of a receiving group (an application's Home). */
+export const RECEIVING_GROUP_CHILD_KIND = "receiving-group" as const;
+/** The `grantedBy` of every role a founding seat writes. */
+export const DELEGATED_ROLE_GRANTOR = "inherited-at-birth" as const;
+/** The `grantedBy` of a role the jurisdiction's enroller carries into an existing child. */
+export const ADOPTED_ROLE_GRANTOR = "inherited-from-parent" as const;
+/** The framework object type of a delegated-role policy, and its one relation. */
+export const DELEGATED_ROLE_OBJECT_TYPE = "nomosDelegatedRole" as const;
+export const DELEGATED_TO_RELATION = "delegatedTo" as const;
+export const SEED_DELEGATED_ROLES_DIRECTIVE = "seedDelegatedRoles" as const;
+export const ADOPT_DELEGATED_ROLES_DIRECTIVE = "adoptDelegatedRoles" as const;
+
+/** Delegation carries business roles, never governance, identity or delegation itself: no framework
+ *  object type (every framework governance relation lives on one), and — on any type — no relation
+ *  named like the authority to administer, install law, sign or enrol. */
+const GOVERNANCE_OBJECT_TYPES: readonly string[] = ["workspace", "identity", PRINCIPAL_SCOPE_OBJECT_TYPE, DELEGATED_ROLE_OBJECT_TYPE];
+const GOVERNANCE_RELATIONS: readonly string[] = [
+  "admin", "operator", "installDomain", "signer", "enroller", DELEGATED_TO_RELATION,
+];
+
+/** Refuse a role that would carry governance rather than a business role. */
+export function requireBusinessRole(objectType: string, relation: string): void {
+  if (GOVERNANCE_OBJECT_TYPES.includes(objectType) || GOVERNANCE_RELATIONS.includes(relation)) {
+    throw new Error(`delegated-role-is-governance: '${objectType}#${relation}' is not a delegable business role`);
+  }
+}
+
+const childKindField = z.string().regex(/^[a-z][a-z0-9-]*$/, "a child kind is a lowercase business noun");
+const domainField = z.string().regex(/^[A-Za-z_][A-Za-z0-9_-]{0,127}$/, "a law domain key");
+const nameField = z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,127}$/, "a relation-schema name");
+
+// ─────────────────────────────── the parent's policy (framework) ───────────────────────────────
+
+/** `nomosDelegatedRole:<childKind>.<domain>.<objectType>.<relation>#delegatedTo@principalScope:<scope>`. */
+export const delegatedRoleRelations = relationType(DELEGATED_ROLE_OBJECT_TYPE)
+  .asGlobal()
+  .relation(DELEGATED_TO_RELATION, { rewrite: self(), allow: [object("principalScope")] });
+
+export function delegatedRoleObject(p: { childKind: string; domain: string; objectType: string; relation: string }): string {
+  return `${DELEGATED_ROLE_OBJECT_TYPE}:${p.childKind}.${p.domain}.${p.objectType}.${p.relation}`;
+}
+
+const grantPayload = z
+  .object({
+    scope: providerScopeField,
+    childKind: childKindField,
+    /** The child-law domain that declares the role ({@link delegatedRoles}) and seats it. */
+    domain: domainField,
+    objectType: nameField,
+    relation: nameField,
+    grantedAt: z.number().int().nonnegative(),
+  })
+  .strict();
+
+/** `grantDelegatedRole` — an admin delegates a role into every child a `<scope>:` principal founds here. */
+export const grantDelegatedRole = directive("grantDelegatedRole")
+  .ensures(RelationTuple)
+  .payload(grantPayload)
+  .plan((p, ctx) => {
+    requireBusinessRole(p.objectType, p.relation);
+    return writeTuple({
+      object: delegatedRoleObject(p),
+      relation: DELEGATED_TO_RELATION,
+      subject: `principalScope:${p.scope}`,
+      grantedBy: ctx.principal().asAttribution(),
+      grantedAt: String(p.grantedAt),
+    });
+  })
+  .requires("admin");
+
+/** `revokeDelegatedRole` — children founded afterwards no longer receive it (existing ones keep their tuple
+ *  until the enroller carries the revoke into them with `adoptDelegatedRoles`). */
+export const revokeDelegatedRole = directive("revokeDelegatedRole")
+  .ensures(RelationTuple)
+  .payload(grantPayload)
+  .plan((p, ctx) =>
+    removeTuple({
+      object: delegatedRoleObject(p),
+      relation: DELEGATED_TO_RELATION,
+      subject: `principalScope:${p.scope}`,
+      grantedBy: ctx.principal().asAttribution(),
+      grantedAt: String(p.grantedAt),
+      revokedBy: ctx.principal().asAttribution(),
+      revokedAt: String(p.grantedAt),
+    }))
+  .requires("admin");
+
+export type DelegatedRolesByDomain = ReadonlyArray<{ domain: string; objectType: string; relations: readonly string[] }>;
+
+/** The parent's active grants for `principal`'s scope and `childKind`, grouped by (domain, objectType), sorted. */
+export function readDelegatedRoles(principal: string, childKind: string): DelegatedRolesByDomain {
+  const scope = principalScopeOf(principal);
+  if (scope === undefined) return [];
+  const rows = readFrameworkDeclaredRows(relationTuplesByRelation, RelationTuple, { relation: DELEGATED_TO_RELATION });
+  const prefix = `${DELEGATED_ROLE_OBJECT_TYPE}:`;
+  const groups = new Map<string, { domain: string; objectType: string; relations: Set<string> }>();
+  for (const row of rows) {
+    if (row.relation !== DELEGATED_TO_RELATION || !row.object?.startsWith(prefix)) continue;
+    const parts = row.object.slice(prefix.length).split(".");
+    if (parts.length !== 4) continue;
+    const [kind, domain, objectType, relation] = parts as [string, string, string, string];
+    if (kind !== childKind) continue;
+    const subjects = row.subjects as Record<string, { status?: string }> | undefined;
+    if (subjects?.[`principalScope:${scope}`]?.status !== "active") continue;
+    const key = `${domain}\u001f${objectType}`;
+    const group = groups.get(key) ?? { domain, objectType, relations: new Set<string>() };
+    group.relations.add(relation);
+    groups.set(key, group);
+  }
+  return [...groups.entries()]
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([, g]) => ({ domain: g.domain, objectType: g.objectType, relations: [...g.relations].sort() }));
+}
+
+/** One `seedDelegatedRoles` step per (domain, objectType) the parent delegates, dispatched in that domain. */
+export function delegatedRolesSteps(
+  actor: string,
+  principal: string,
+  childKind: string,
+  grantedAt: number,
+): Array<{ domain: string; directiveId: string; actor: string; payload: Record<string, unknown> }> {
+  return readDelegatedRoles(principal, childKind).map((group) => ({
+    domain: group.domain,
+    directiveId: SEED_DELEGATED_ROLES_DIRECTIVE,
+    actor,
+    payload: { principal, objectType: group.objectType, relations: [...group.relations], grantedAt },
+  }));
+}
+
+// ─────────────────────────────── the child's law (tenant-declared) ───────────────────────────────
+
+/** Admitted only on the warrant-free prefix: after birth, roles change by `adoptDelegatedRoles`. */
+export const delegatedRolesBeforeWarrant = workspaceInvariant("DelegatedRolesBeforeWarrant")
+  .on(SEED_DELEGATED_ROLES_DIRECTIVE)
+  .reads(readSet(readRef("warrant", "GenesisWarrant").pre().at(GENESIS_WARRANT_ID)))
+  .assert(({ warrant }) =>
+    (warrant as { principal?: string } | undefined)?.principal
+      ? { reject: "delegated-roles-after-warrant" }
+      : { accept: true });
+
+export interface DelegatedRolesLaw {
+  /** The founding seat a founded birth dispatches in this domain. */
+  readonly seedDelegatedRoles: Directive<{ principal: string; objectType: string; relations: string[]; grantedAt: number }>;
+  readonly delegatedRolesBeforeWarrant: typeof delegatedRolesBeforeWarrant;
+  /** The post-birth lane: an enroller of the principal's scope carries a later grant or revoke here. */
+  readonly adoptDelegatedRoles: Directive<{
+    scope: string; principal: string; objectType: string; relation: string; active: boolean; at: number;
+  }>;
+  /** The enroller relation the adoption lane requires, carried so the declaring domain's closure has it. */
+  readonly principalScopeRelations: typeof principalScopeRelations;
+}
+
+/**
+ * DECLARE the roles of `relations` (a relation type THIS domain declares) that a parent may delegate
+ * into this workspace. Export every member of the result from the declaring domain. What may be seated
+ * or adopted is this list — law, closed over by the directives, never payload — and every tuple lands
+ * on the object `.requires(relation, …)` checks, because it is written through the same schema reference.
+ */
+export function delegatedRoles(relations: RelationTypeDecl, roles: readonly string[]): DelegatedRolesLaw {
+  if (relations.global === true) {
+    throw new Error("delegatedRoles: a global (framework) relation type is never delegable");
+  }
+  if (roles.length === 0) throw new Error("delegatedRoles: declare at least one delegable role");
+  for (const role of roles) {
+    nameField.parse(role);
+    requireBusinessRole(relations.type, role);
+    if (!relations.relations.has(role)) {
+      throw new Error(`delegatedRoles: '${relations.type}' declares no relation '${role}'`);
+    }
+  }
+  const allowed = new Set(roles);
+  const objectType = relations.type;
+  const refuseUndeclared = (type: string, relation: string) => {
+    if (type !== objectType || !allowed.has(relation)) {
+      throw new Error(`delegated-role-not-declared: '${type}#${relation}' is not a delegable role of this law`);
+    }
+  };
+
+  const seedDelegatedRoles = directive(SEED_DELEGATED_ROLES_DIRECTIVE)
+    .ensures(RelationTuple)
+    .payload(
+      z
+        .object({
+          principal: z.string().min(1),
+          objectType: nameField,
+          relations: z.array(nameField).min(1),
+          grantedAt: z.number().int().nonnegative(),
+        })
+        .strict()
+        .refine((p) => principalScopeOf(p.principal) !== undefined, {
+          message: "delegated roles are held by a <scope>:<subject> principal",
+          path: ["principal"],
+        }),
+    )
+    .plan((p) =>
+      p.relations.flatMap((relation) => {
+        refuseUndeclared(p.objectType, relation);
+        return writeTuple({
+          object: selfObject(relations),
+          relation,
+          subject: p.principal,
+          grantedBy: DELEGATED_ROLE_GRANTOR,
+          grantedAt: String(p.grantedAt),
+        });
+      }));
+
+  const adoptDelegatedRoles = directive(ADOPT_DELEGATED_ROLES_DIRECTIVE)
+    .ensures(RelationTuple)
+    .payload(
+      z
+        .object({
+          /** The principal scope whose enroller carries the parent's policy here. */
+          scope: providerScopeField,
+          principal: z.string().min(1),
+          objectType: nameField,
+          relation: nameField,
+          /** true = the parent currently delegates the role; false = it no longer does. */
+          active: z.boolean(),
+          at: z.number().int().nonnegative(),
+        })
+        .strict()
+        .refine((p) => principalScopeOf(p.principal) === p.scope, {
+          message: "principal must be <scope>:<subject> of the named scope",
+          path: ["principal"],
+        }),
+    )
+    .plan((p, ctx) => {
+      refuseUndeclared(p.objectType, p.relation);
+      if (principalScopeOf(p.principal) !== p.scope) throw new Error("principal-not-in-scope");
+      const tuple = {
+        object: selfObject(relations),
+        relation: p.relation,
+        subject: p.principal,
+        grantedBy: ADOPTED_ROLE_GRANTOR,
+        grantedAt: String(p.at),
+      };
+      return p.active
+        ? writeTuple(tuple)
+        : removeTuple({ ...tuple, revokedBy: ctx.principal().asAttribution(), revokedAt: String(p.at) });
+    })
+    .requires("enroller", {
+      objectFrom: { recordType: PRINCIPAL_SCOPE_OBJECT_TYPE, idField: "scope" },
+    });
+
+  return {
+    seedDelegatedRoles: seedDelegatedRoles as unknown as DelegatedRolesLaw["seedDelegatedRoles"],
+    delegatedRolesBeforeWarrant,
+    adoptDelegatedRoles: adoptDelegatedRoles as unknown as DelegatedRolesLaw["adoptDelegatedRoles"],
+    principalScopeRelations,
+  };
+}