permdock 0.5.0 → 0.6.0

package/dist/{ownership-BatFgAA4.js → ownership-DqaJNJPn.js}

@@ -4,14 +4,14 @@ import { l as isSqlFunctionField } from "./refs-K6eWUJ0H.js";
 import { u as isoAt } from "./time-DkWjdL98.js";
 import { c as rootScope, d as scopeList, l as scopeChain, o as resolveScope } from "./scopes-CUPSjo9q.js";
 import { t as isoInstant } from "./instant-BluqDvyS.js";
-import { m as findRole, v as listRoles } from "./grantee-Cn1HyUsI.js";
+import { m as findRole, v as listRoles } from "./grantee-hxrUsbpM.js";
 import { r as relationCondition, t as inheritCondition } from "./grantee-conditions-CcXf8hMM.js";
 import { l as partitionsOf, p as scopeField } from "./tenancy-DN2QAx9z.js";
 import { i as configError } from "./errors-CWTY6uih.js";
 import { i as scopeMembershipTable, o as relatedSql, r as scopeColumn } from "./compile-CMqMx_IN.js";
 import { i as qualifySqlTable, t as SQL_IDENT, u as sqlTextArray } from "./sql-B5T1IL83.js";
 import { d as keptKeys, l as roleColumn, u as roleManifest } from "./sources-vs5dGOsS.js";
-import { A as declaredArray, D as sqlType, E as scopeTypeOf, F as quoteQualified, I as quoteTable, L as textArrayLiteral, M as qualified, N as quoteIdent, O as tenantTypeOf, P as quoteLiteral, S as CLAIM, _ as subjectClaimJsonSql, b as tenantClaimSql, d as keyTenantSql, f as kindFilterSql, h as roleKindSql, i as allowEntry, j as helperSchema, k as CLI, m as memberVia, n as GLOBAL_ROLES, o as rootName, p as liveSessionSql, r as HELPERS, s as signedIn, t as CUSTOM_ROLES, u as globalKindFilterSql, v as subjectClaimSql, x as userIdHelperSql, y as subjectIdSql } from "./shared-CD11nBbC.js";
+import { A as declaredArray, D as sqlType, E as scopeTypeOf, F as quoteQualified, I as quoteTable, L as textArrayLiteral, M as qualified, N as quoteIdent, O as tenantTypeOf, P as quoteLiteral, S as CLAIM, _ as subjectClaimJsonSql, b as tenantClaimSql, d as keyTenantSql, f as kindFilterSql, h as roleKindSql, i as allowEntry, j as helperSchema, k as CLI, m as memberVia, n as GLOBAL_ROLES, o as rootName, p as liveSessionSql, r as HELPERS, s as signedIn, t as CUSTOM_ROLES, u as globalKindFilterSql, v as subjectClaimSql, x as userIdHelperSql, y as subjectIdSql } from "./shared-BAK8t4Uo.js";
 //#region src/cli/sql/active.ts
 function checkActiveRow(label, row) {
 	quoteTable(row.table);
@@ -840,909 +840,963 @@ function byKey([a], [b]) {
 	return byCodeUnit(a, b);
 }
 //#endregion
-//#region src/cli/sql/global-roles.ts
-function qualify(name, schema) {
-	return name.includes(".") ? name : `${schema}.${name}`;
-}
-function throughTenant(through, roles) {
-	if (through === void 0 || roles?.tenant === void 0) return;
-	return qualify(roles.table, "public") === through.table ? roles.tenant : void 0;
-}
-/** Resolves `source` against `schema`, aliasing the table `alias` and the roles table `<alias>k`. */
-function globalRoleSource(source, schema, alias, roles) {
-	const table = qualify(source.table, schema);
-	const user = source.user ?? "user_id";
-	const role = roleColumn(source.role ?? "role", table, alias, {
-		label: "roles.role",
-		prefix: "PermDock CLI",
-		indent: "    "
-	});
-	const tenant = role.lateral ? void 0 : throughTenant(role.through, roles);
-	const global = tenant === void 0 ? "" : ` and ${alias}k.${quoteIdent(tenant)} is null`;
-	return {
-		table,
-		user,
-		from: `${quoteTable(table)} ${alias}${role.join}${global}`,
-		userSql: `${alias}.${quoteIdent(user)}`,
-		roleSql: role.sql,
-		role: roleManifest(role),
-		...role.through === void 0 ? {} : { through: role.through },
-		...tenant === void 0 ? {} : { tenant }
-	};
-}
-//#endregion
-//#region src/cli/rls/helper-rows.ts
-function activeTenant(ctx) {
-	return `nullif(${subjectClaimSql(ctx, ctx.tenantClaim)}, '')`;
-}
-function keyTenantLine(ctx, scope, tenant) {
-	const keyed = keyTenantSql(ctx, underRoot(ctx, scope) ? tenant : void 0);
-	return keyed === void 0 ? "" : `\n    and ${keyed}`;
-}
-/** Whether the helper for `scope` narrows to the tenant claim: unless `rls.tenants` is `'all'`, when the first scope is on its chain. */
-function narrowsTo(ctx, scope) {
-	return ctx.tenants !== "all" && underRoot(ctx, scope);
-}
-/** Whether the active tenant narrows memberships of `scope`: the first scope is on its chain. */
-function underRoot(ctx, scope) {
-	const root = ctx.scopes[0]?.name;
-	let current = ctx.scopes.find((item) => item.name === scope);
-	const seen = /* @__PURE__ */ new Set();
-	while (current !== void 0 && !seen.has(current.name)) {
-		if (current.name === root) return true;
-		seen.add(current.name);
-		const parent = current.within;
-		current = parent === void 0 ? void 0 : ctx.scopes.find((item) => item.name === parent);
-	}
-	return false;
-}
-/** `and exists (...)` lines for an active user; empty without `rls.suspension.users`. */
-function userActive(ctx, indent, user) {
-	return activeUserSql(ctx, user).map((part) => `${indent}and ${part}`);
-}
-/** `and exists (...)` lines for every suspendable instance on the chain of `scope`'s membership. */
-function instancesActive(ctx, scope, idOf, indent, permission) {
-	return activeInstancesSql(ctx, scope, idOf, permission).map((part) => `${indent}and ${part}`);
-}
-function roleRows(ctx) {
-	const claim = ctx.roleClaim ?? "user_role";
-	switch (ctx.dialect) {
-		case "guc": return `unnest(string_to_array(nullif(current_setting(${quoteLiteral(`${ctx.gucPrefix}.${claim}`)}, true), ''), ',')) r(role)`;
-		case "supabase":
-		case "neon": {
-			const raw = subjectClaimJsonSql(ctx, claim);
-			const value = ctx.dialect === "supabase" ? `coalesce(nullif(${raw}, 'null'::jsonb), (select auth.jwt()) -> 'app_metadata' -> ${quoteLiteral(claim)})` : raw;
-			return `jsonb_array_elements_text(
-      case jsonb_typeof(${value})
-        when 'array' then ${value}
-        when 'string' then jsonb_build_array(${value})
-        else '[]'::jsonb
-      end
-    ) r(role)`;
-		}
-		default: return ctx.dialect;
-	}
-}
-function membershipRows(ctx) {
-	const raw = subjectClaimJsonSql(ctx, "memberships");
-	const value = ctx.dialect === "supabase" ? `coalesce(${raw}, (select auth.jwt()) -> 'app_metadata' -> 'memberships')` : raw;
-	return `jsonb_array_elements(
-      case jsonb_typeof(${value}) when 'array' then ${value} else '[]'::jsonb end
-    ) m
-    cross join lateral jsonb_array_elements_text(
-      case jsonb_typeof(m -> 'roles') when 'array' then m -> 'roles' else '[]'::jsonb end
-    ) r(role)`;
-}
-function andLine(indent, condition) {
-	return condition === void 0 ? "" : `\n${indent}and ${condition}`;
-}
-/** `rls.roles`, or the generated `user_roles (user_id, role)`, aliased `ur`. */
-function globalRoleRows(ctx) {
-	return ctx.roles === void 0 ? {
-		from: `${qualified(ctx, "user_roles")} ur`,
-		userSql: "ur.user_id",
-		roleSql: "ur.role::text"
-	} : globalRoleSource(ctx.roles, "public", "ur", ctx.customRoles?.table);
-}
-function customKeysJoin(ctx, scope, allows, denies, includes) {
-	return `  cross join lateral ${qualified(ctx, CUSTOM_ROLES.keys)}(
-    ${allows},
-    ${denies},
-    ${includes},
-    ${quoteLiteral(scope)}
-  ) ck(grant_key)`;
-}
-//#endregion
-//#region src/cli/rls/helper-bodies.ts
-function hasSetBody(ctx) {
-	const rp = qualified(ctx, "role_permissions");
-	const active = userActive(ctx, "    ").map((line) => `\n${line}`).join("");
+//#region src/cli/rls/custom-roles.ts
+/** The readers every helpers file ends with. Names are part of the SQL contract. */
+const READERS = {
+	keys: "permdock_permission_keys",
+	roles: "permdock_role_permissions",
+	trusted: "permdock_trusted_role_permissions"
+};
+/**
+* The custom-role objects: the tables (`database` mode), the ceiling view
+* over the `assignable` declared roles, and `permdock_custom_keys`, which
+* resolves one custom role to the grant keys it holds in a scope. A row in
+* the tables can never reach a key outside the view.
+*/
+function customRolesSql(ctx) {
 	const custom = ctx.customRoles;
-	if (ctx.authorize === "database") {
-		const ur = globalRoleRows(ctx);
-		const declared = `  select rp.grant_key
-  from ${ur.from}
-  join ${rp} rp on rp.role = ${ur.roleSql}
-  where ${ur.userSql} = ${subjectIdSql(ctx)}
-    and rp.scope = 'global'${andLine("    ", globalKindFilterSql(ctx, ur.roleSql))}${active}`;
-		if (custom === void 0) return declared;
-		const match = `c.tenant_id is null and c.scope = 'global' and c.scope_id is null and c.role = ${ur.roleSql}`;
-		const rows = (source, value, extra) => `array(select c.${value} from ${qualified(ctx, source)} c where ${match}${extra})`;
-		return `${declared}
-  union
-  select ck.grant_key
-  from ${ur.from}
-${customKeysJoin(ctx, "global", rows(CUSTOM_ROLES.permissions, allowEntry(ctx), " and c.effect = 'allow'"), rows(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'deny'"), rows(CUSTOM_ROLES.includes, "include_role", ""))}
-  where ${ur.userSql} = ${subjectIdSql(ctx)}
-    and not (${ur.roleSql} = any(${sqlTextArray(custom.declared)}))${active}`;
-	}
-	const declared = `  select rp.grant_key
-  from ${roleRows(ctx)}
-  join ${rp} rp on rp.role = r.role
-  where ${signedIn(ctx)}
-    and rp.scope = 'global'${andLine("    ", globalKindFilterSql(ctx, "r.role"))}${active}`;
-	if (custom === void 0) return declared;
-	const claim = subjectClaimJsonSql(ctx, GLOBAL_GRANTS_CLAIM);
-	return `${declared}
-  union
-  select ck.grant_key
-  from ${roleRows(ctx)}
-  cross join lateral (select ${claim} -> r.role as g) cg
-${customKeysJoin(ctx, "global", claimEntries("left(e, 1) not in ('-', '@')", "e"), claimEntries("left(e, 1) = '-'", "substr(e, 2)"), claimEntries("left(e, 1) = '@'", "substr(e, 2)"))}
-  where ${signedIn(ctx)}
-    and jsonb_typeof(cg.g) = 'array'
-    and not (r.role = any(${sqlTextArray(custom.declared)}))${active}`;
-}
-function hasBody(ctx) {
-	if (ctx.grantSet === true) return hasSetBody(ctx);
+	if (custom === void 0) return "";
 	const rp = qualified(ctx, "role_permissions");
-	const active = userActive(ctx, "      ").map((line) => `\n${line}`).join("");
-	const custom = ctx.customRoles;
+	const ceiling = qualified(ctx, CUSTOM_ROLES.ceiling);
+	const keys = qualified(ctx, CUSTOM_ROLES.keys);
+	const chunks = [];
 	if (ctx.authorize === "database") {
-		const ur = globalRoleRows(ctx);
-		const declared = `  select exists (
-    select 1
-    from ${ur.from}
-    join ${rp} rp on rp.role = ${ur.roleSql}
-    where ${ur.userSql} = ${subjectIdSql(ctx)}
-      and rp.grant_key = p_grant
-      and rp.scope = 'global'${andLine("      ", globalKindFilterSql(ctx, ur.roleSql))}${active}
-  )`;
-		if (custom === void 0) return declared;
-		const match = `c.tenant_id is null and c.scope = 'global' and c.scope_id is null and c.role = ${ur.roleSql}`;
-		const rows = (source, value, extra) => `array(select c.${value} from ${qualified(ctx, source)} c where ${match}${extra})`;
-		return `${declared}
-  or exists (
-    select 1
-    from ${ur.from}
-    where ${ur.userSql} = ${subjectIdSql(ctx)}
-      and not (${ur.roleSql} = any(${sqlTextArray(custom.declared)}))${active}
-      ${customKeysSql(ctx, "global", rows(CUSTOM_ROLES.permissions, allowEntry(ctx), " and c.effect = 'allow'"), rows(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'deny'"), rows(CUSTOM_ROLES.includes, "include_role", "")).trimStart()}
-  )`;
-	}
-	const declared = `  select ${signedIn(ctx)} and exists (
-    select 1
-    from ${roleRows(ctx)}
-    join ${rp} rp on rp.role = r.role
-    where rp.grant_key = p_grant
-      and rp.scope = 'global'${andLine("      ", globalKindFilterSql(ctx, "r.role"))}${active}
-  )`;
-	if (custom === void 0) return declared;
-	const claim = subjectClaimJsonSql(ctx, GLOBAL_GRANTS_CLAIM);
-	return `${declared}
-  or (${signedIn(ctx)} and exists (
-    select 1
-    from ${roleRows(ctx)}
-    cross join lateral (select ${claim} -> r.role as g) cg
-    where jsonb_typeof(cg.g) = 'array'
-      and not (r.role = any(${sqlTextArray(custom.declared)}))${active}
-      ${customKeysSql(ctx, "global", claimEntries("left(e, 1) not in ('-', '@')", "e"), claimEntries("left(e, 1) = '-'", "substr(e, 2)"), claimEntries("left(e, 1) = '@'", "substr(e, 2)")).trimStart()}
-  ))`;
-}
-/** The claim `jwt` mode reads platform custom roles from: `customRoleClaim(globalRoles)`. */
-const GLOBAL_GRANTS_CLAIM = "role_grants";
-function memberColumn(name) {
-	return `m.${quoteIdent(name)}`;
-}
-function disabledColumn(table) {
-	return table.disabledAt === void 0 ? void 0 : memberColumn(table.disabledAt);
-}
-function claimKeptLines(ctx, indent, permission) {
-	return disabledKeep(ctx).length === 0 ? [] : [`${indent}and ${keptRowSql("m -> 'keep'", permission)}`];
-}
-/** Entries of a compact custom-role claim (`cg.g`) that match `where`. */
-function claimEntries(where, value) {
-	return `array(select ${value} from jsonb_array_elements_text(cg.g) e where ${where})`;
-}
-/** `p_grant in (select permdock_custom_keys(allows, denies, includes, scope))`. */
-function customKeysSql(ctx, scope, allows, denies, includes) {
-	return `    and p_grant in (select ${qualified(ctx, CUSTOM_ROLES.keys)}(
-      ${allows},
-      ${denies},
-      ${includes},
-      ${quoteLiteral(scope)}
-    ))`;
-}
-function tableBody(ctx, scope, type) {
-	const mapped = scopeTable(ctx, scope);
-	if (mapped === void 0) return `  select null::${type} where false -- no ${scope} memberships table configured`;
-	const { table, column, tenantColumn } = mapped;
-	const set = ctx.grantSet === true;
-	const filtersFor = (grant) => {
-		const filters = [`  where ${memberColumn(table.user)} = ${subjectIdSql(ctx)}`];
-		if (table.expiresAt !== void 0) {
-			const expires = memberColumn(table.expiresAt);
-			filters.push(`    and (${expires} is null or ${expires} > now())`);
+		const tenantType = tenantTypeOf(ctx);
+		for (const [name, column, check] of [[
+			CUSTOM_ROLES.permissions,
+			"permission",
+			`,
+  effect text not null default 'allow' check (effect in ('allow', 'deny'))`
+		], [
+			CUSTOM_ROLES.includes,
+			"include_role",
+			""
+		]]) {
+			const table = qualified(ctx, name);
+			const leveled = custom.levels === true && name === CUSTOM_ROLES.permissions;
+			const unique = `${column}${name === CUSTOM_ROLES.permissions ? ", effect" : ""}${leveled ? ", coalesce(level, '')" : ""}`;
+			const index = leveled ? `drop index if exists ${qualified(ctx, quoteIdent(`${name}_key`))};
+alter table ${table} add column if not exists level text check (level ~ '^[a-z][a-z0-9_]*$');
+create unique index if not exists ${quoteIdent(`${name}_level_key`)}` : `create unique index if not exists ${quoteIdent(`${name}_key`)}`;
+			chunks.push(`create table if not exists ${table} (
+  tenant_id ${tenantType},
+  scope text not null default ${quoteLiteral(rootName(ctx))},
+  scope_id text,
+  role text not null,
+  ${column} text not null${check}
+);
+-- global: no tenant or instance; a tenant role: a tenant; a shared role: no tenant or instance
+alter table ${table} drop constraint if exists ${quoteIdent(`${name}_check`)};
+alter table ${table} drop constraint if exists ${quoteIdent(`${name}_shape`)};
+alter table ${table} add constraint ${quoteIdent(`${name}_shape`)} check (
+  case when scope = 'global' then tenant_id is null and scope_id is null
+  else tenant_id is not null or scope_id is null end
+);
+${index}
+  on ${table} (coalesce(tenant_id::text, ''), scope, coalesce(scope_id, ''), role, ${unique});
+-- a row identity for triggers the application adds, such as an audit trigger that reads the primary key
+alter table ${table} add column if not exists id bigint generated always as identity primary key;
+alter table ${table} enable row level security;
+revoke all on table ${table} from anon, authenticated, public;`);
 		}
-		filters.push(...activeMembershipSql(ctx, disabledColumn(table), grantPermissionSql(grant)).map((part) => `    and ${part}`));
-		if (tenantColumn !== void 0 && ctx.tenants !== "all") filters.push(`    and (${activeTenant(ctx)} is null or ${memberColumn(tenantColumn)}::text = ${activeTenant(ctx)})`);
-		const keyed = keyTenantSql(ctx, tenantColumn === void 0 ? void 0 : memberColumn(tenantColumn));
-		if (keyed !== void 0) filters.push(`    and ${keyed}`);
-		filters.push(...userActive(ctx, "    "), ...instancesActive(ctx, scope, (name) => {
-			const held = scopeColumn(table, ctx.scopes, name);
-			return held === void 0 ? void 0 : memberColumn(held);
-		}, "    ", grantPermissionSql(grant)));
-		return filters;
-	};
-	const filters = filtersFor(set ? "rp.grant_key" : "p_grant");
-	const [owner, ...rest] = filters;
-	const role = memberRoleOf(table, "m", "  ");
-	const kind = kindFilterSql(ctx, role.sql, memberVia(table));
-	const lines = [
-		`  select${role.lateral ? " distinct" : ""} ${memberColumn(column)}::${type}${set ? ", rp.grant_key" : ""}`,
-		`  from ${quoteQualified(table.table)} m${role.join}`,
-		`  join ${qualified(ctx, "role_permissions")} rp on rp.role = ${role.sql}`,
-		owner ?? "",
-		...set ? [] : ["    and rp.grant_key = p_grant"],
-		`    and rp.scope = ${quoteLiteral(scope)}`,
-		...kind === void 0 ? [] : [`    and ${kind}`],
-		...rest
-	];
-	const custom = ctx.customRoles;
-	if (custom === void 0) return lines.join("\n");
-	const match = [
-		`c.tenant_id::text = ${memberColumn(tenantColumn ?? column)}::text`,
-		`c.scope = ${quoteLiteral(scope)}`,
-		`(c.scope_id is null or c.scope_id = ${memberColumn(column)}::text)`,
-		`c.role = ${role.sql}`
-	].join(" and ");
-	const rows = (source, value, extra) => `array(select c.${value} from ${qualified(ctx, source)} c where ${match}${extra})`;
-	const entries = [
-		rows(CUSTOM_ROLES.permissions, allowEntry(ctx), " and c.effect = 'allow'"),
-		rows(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'deny'"),
-		rows(CUSTOM_ROLES.includes, "include_role", "")
-	];
-	if (set) return [
-		...lines,
-		"  union",
-		`  select ${memberColumn(column)}::${type}, ck.grant_key`,
-		`  from ${quoteQualified(table.table)} m${role.join}`,
-		customKeysJoin(ctx, scope, ...entries),
-		...filtersFor("ck.grant_key"),
-		`    and not (${role.sql} = any(${sqlTextArray(custom.declared)}))`
-	].join("\n");
-	return [
-		...lines,
-		"  union",
-		`  select ${memberColumn(column)}::${type}`,
-		`  from ${quoteQualified(table.table)} m${role.join}`,
-		...filters,
-		`    and not (${role.sql} = any(${sqlTextArray(custom.declared)}))`,
-		customKeysSql(ctx, scope, ...entries)
-	].join("\n");
-}
-/** The membership's instance of the first scope, from the canonical claim. */
-function claimTenant(ctx, scope) {
-	const root = rootName(ctx);
-	return scope === root ? `m ->> 'id'` : `m -> 'within' ->> ${quoteLiteral(root)}`;
-}
-function claimBody(ctx, scope, type) {
-	const set = ctx.grantSet === true;
-	const narrow = narrowsTo(ctx, scope) ? `
-    and (${activeTenant(ctx)} is null or ${claimTenant(ctx, scope)} = ${activeTenant(ctx)})` : "";
-	const filtersFor = (grant) => `    and m ->> 'scope' = ${quoteLiteral(scope)}
-    and m ->> 'id' is not null${narrow}${keyTenantLine(ctx, scope, claimTenant(ctx, scope))}
-    and case jsonb_typeof(m -> 'expires_at')
-      when 'number' then (m ->> 'expires_at')::numeric > extract(epoch from now())
-      else true
-    end${[
-		...claimKeptLines(ctx, "    ", grantPermissionSql(grant)),
-		...userActive(ctx, "    "),
-		...instancesActive(ctx, scope, (name) => name === scope ? `m ->> 'id'` : `m -> 'within' ->> ${quoteLiteral(name)}`, "    ", grantPermissionSql(grant))
-	].map((line) => `\n${line}`).join("")}`;
-	const filters = filtersFor(set ? "rp.grant_key" : "p_grant");
-	const declared = `  select (m ->> 'id')::${type}${set ? ", rp.grant_key" : ""}
-  from ${membershipRows(ctx)}
-  join ${qualified(ctx, "role_permissions")} rp on rp.role = r.role
-  where ${signedIn(ctx)}${set ? "" : "\n    and rp.grant_key = p_grant"}
-    and rp.scope = ${quoteLiteral(scope)}${andLine("    ", kindFilterSql(ctx, "r.role", "m ->> 'via'"))}
-${filters}`;
-	const custom = ctx.customRoles;
-	if (custom === void 0) return declared;
-	if (set) return `${declared}
+	}
+	chunks.push(`-- the ceiling: keys of assignable declared roles, and the denies of those roles on the same permissions
+create or replace view ${ceiling} with (security_invoker = true) as
+select rp.scope, rp.role, rp.permission, rp.grant_key, rp.effect
+from ${rp} rp
+where rp.role = any(${sqlTextArray(custom.assignable)})
+  and exists (
+    select 1 from ${rp} a
+    where a.role = rp.role
+      and a.permission = rp.permission
+      and a.scope = rp.scope
+      and a.effect = 'allow'
+  );
+revoke all on table ${ceiling} from anon, authenticated, public;`);
+	const renames = Object.entries(custom.renamed ?? {}).toSorted(byKey);
+	const shared = sharedRoleSql(ctx);
+	if (custom.levels === true) {
+		chunks.push(leveledKeysSql(ctx, renames));
+		if (shared !== "") chunks.push(shared);
+		return chunks.join("\n\n");
+	}
+	const rename = renamesSql(renames);
+	chunks.push(`-- one custom role: included ceiling keys and same-scope denies, plus every ceiling key of an allowed permission, minus denied permissions
+create or replace function ${keys}(p_allow text[], p_deny text[], p_include text[], p_scope text)
+returns setof text
+language sql
+stable
+set search_path = ''
+as $$
+  with ${rename.prelude}ceiling as (
+    select c.role, ${rename.permission("c")}, c.grant_key, c.effect
+    from ${ceiling} c${rename.join("c")}
+    where c.scope = p_scope
+  ),
+  included as (
+    select rp.role, ${rename.permission("rp")}, rp.grant_key, rp.scope, rp.effect
+    from ${rp} rp${rename.join("rp")}
+    where rp.role = any(coalesce(p_include, '{}'::text[]))
+  ),
+  kept as (
+    select i.permission, i.grant_key
+    from included i
+    where i.effect = 'allow'
+      and i.scope = p_scope
+      and exists (
+        select 1 from ceiling c
+        where c.role = i.role and c.grant_key = i.grant_key and c.effect = 'allow'
+      )
+  ),
+  wanted as (
+    ${rename.allow}
+    union
+    select i.permission
+    from included i
+    where i.effect = 'allow'
+      and not (i.scope = p_scope and exists (
+        select 1 from ceiling c
+        where c.role = i.role and c.grant_key = i.grant_key and c.effect = 'allow'
+      ))
+  ),
+  allowed as (
+    select w.permission
+    from wanted w
+    where not (${rename.denied("w")})
+      and not exists (select 1 from kept k where k.permission = w.permission)
+  )
+  select k.grant_key from kept k
+  where not (${rename.denied("k")})
   union
-  select (m ->> 'id')::${type}, ck.grant_key
-  from ${membershipRows(ctx)}
-  cross join lateral (select m -> 'grants' -> r.role as g) cg
-${customKeysJoin(ctx, scope, claimEntries("left(e, 1) not in ('-', '@')", "e"), claimEntries("left(e, 1) = '-'", "substr(e, 2)"), claimEntries("left(e, 1) = '@'", "substr(e, 2)"))}
-  where ${signedIn(ctx)}
-    and jsonb_typeof(cg.g) = 'array'
-    and not (r.role = any(${sqlTextArray(custom.declared)}))
-${filtersFor("ck.grant_key")}`;
-	return `${declared}
+  select i.grant_key from included i
+  where i.effect = 'deny' and i.scope = p_scope
   union
-  select (m ->> 'id')::${type}
-  from ${membershipRows(ctx)}
-  cross join lateral (select m -> 'grants' -> r.role as g) cg
-  where ${signedIn(ctx)}
-    and jsonb_typeof(cg.g) = 'array'
-    and not (r.role = any(${sqlTextArray(custom.declared)}))
-${filters}
-${customKeysSql(ctx, scope, claimEntries("left(e, 1) not in ('-', '@')", "e"), claimEntries("left(e, 1) = '-'", "substr(e, 2)"), claimEntries("left(e, 1) = '@'", "substr(e, 2)"))}`;
+  select c.grant_key from ceiling c
+  where c.permission in (select a.permission from allowed a)
+$$;
+revoke execute on function ${keys}(text[], text[], text[], text) from public, anon, authenticated;`);
+	if (shared !== "") chunks.push(shared);
+	return chunks.join("\n\n");
+}
+/** `permdock_is_shared_role(p_scope, p_role)` (`database` mode): whether a shared custom role of that name exists at the scope. */
+function sharedRoleSql(ctx) {
+	if (ctx.authorize !== "database") return "";
+	const perms = qualified(ctx, CUSTOM_ROLES.permissions);
+	const includes = qualified(ctx, CUSTOM_ROLES.includes);
+	const shared = qualified(ctx, CUSTOM_ROLES.shared);
+	return `-- a shared custom role: rows with no tenant at a scope below global; its name wins over a tenant role's in every tenant
+create or replace function ${shared}(p_scope text, p_role text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select p_scope <> 'global' and (
+    exists (select 1 from ${perms} c where c.tenant_id is null and c.scope = p_scope and c.role = p_role)
+    or exists (select 1 from ${includes} c where c.tenant_id is null and c.scope = p_scope and c.role = p_role)
+  )
+$$;
+revoke execute on function ${shared}(text, text) from public, anon, authenticated;`;
 }
 /**
-* The rows the membership sources select for the subject, one per instance
-* (`scope`, `id`, `within`, `roles`, `via`), with each source's own expiry
-* and suspension filters: the statements the token hook runs.
+* `permdock_custom_keys` when resources declare levels. An allow entry is
+* `key` or `key@level`. A level reaches only the ceiling's `<grant key>@<level>`
+* keys, plus the ceiling denies of that permission; a level no ceiling key
+* carries removes the permission, as `resolveCustomRole` drops it with
+* `unknown-level`.
 */
-function sourcesKeep(sources) {
-	return sources.some((source) => source.sql.keeps);
-}
-function sourceRows(sources) {
-	const keep = sourcesKeep(sources);
-	return sources.map((source, index) => source.sql.select(sourceUser(index), keep).replaceAll(/^/gmu, "    ")).join("\n    union all\n");
+function leveledKeysSql(ctx, renames) {
+	const rp = qualified(ctx, "role_permissions");
+	const ceiling = qualified(ctx, CUSTOM_ROLES.ceiling);
+	const keys = qualified(ctx, CUSTOM_ROLES.keys);
+	const renamed = renames.length > 0;
+	const prelude = renamed ? `renamed (former, key) as (values ${renames.map(([former, current]) => `(${quoteLiteral(former)}, ${quoteLiteral(current)})`).join(", ")}),
+  ` : "";
+	const current = (raw, alias) => renamed ? `coalesce(r_${alias}.key, ${raw})` : raw;
+	const join = (raw, alias) => renamed ? ` left join renamed r_${alias} on r_${alias}.former = ${raw}` : "";
+	return `-- one custom role: as above, where an allow entry key@level reaches only the ceiling keys of that level
+create or replace function ${keys}(p_allow text[], p_deny text[], p_include text[], p_scope text)
+returns setof text
+language sql
+stable
+set search_path = ''
+as $$
+  with ${prelude}entries as (
+    select ${current("split_part(e.entry, '@', 1)", "e")} as permission, nullif(split_part(e.entry, '@', 2), '') as level
+    from unnest(coalesce(p_allow, '{}'::text[])) as e(entry)${join("split_part(e.entry, '@', 1)", "e")}
+  ),
+  ceiling as (
+    select c.role, ${current("c.permission", "c")} as permission, c.grant_key, c.effect
+    from ${ceiling} c${join("c.permission", "c")}
+    where c.scope = p_scope
+  ),
+  levels as (
+    select distinct c.permission, split_part(c.grant_key, '@', 2) as level
+    from ceiling c
+    where c.effect = 'allow' and strpos(c.grant_key, '@') > 0
+  ),
+  denied as (
+    select ${current("d.permission", "d")} as permission
+    from unnest(coalesce(p_deny, '{}'::text[])) as d(permission)${join("d.permission", "d")}
+    union
+    select e.permission from entries e
+    where e.level is not null
+      and not exists (select 1 from levels l where l.permission = e.permission and l.level = e.level)
+  ),
+  included as (
+    select rp.role, ${current("rp.permission", "rp")} as permission, rp.grant_key, rp.scope, rp.effect
+    from ${rp} rp${join("rp.permission", "rp")}
+    where rp.role = any(coalesce(p_include, '{}'::text[]))
+  ),
+  kept as (
+    select i.permission, i.grant_key
+    from included i
+    where i.effect = 'allow'
+      and i.scope = p_scope
+      and exists (
+        select 1 from ceiling c
+        where c.role = i.role and c.grant_key = i.grant_key and c.effect = 'allow'
+      )
+  ),
+  wanted as (
+    select e.permission from entries e where e.level is null
+    union
+    select i.permission
+    from included i
+    where i.effect = 'allow'
+      and not (i.scope = p_scope and exists (
+        select 1 from ceiling c
+        where c.role = i.role and c.grant_key = i.grant_key and c.effect = 'allow'
+      ))
+  ),
+  allowed as (
+    select w.permission
+    from wanted w
+    where w.permission not in (select d.permission from denied d)
+      and not exists (select 1 from kept k where k.permission = w.permission)
+  ),
+  allowed_levels as (
+    select e.permission, e.level
+    from entries e
+    where e.level is not null
+      and e.permission not in (select d.permission from denied d)
+      and e.permission not in (select a.permission from allowed a)
+      and not exists (select 1 from kept k where k.permission = e.permission)
+  )
+  select k.grant_key from kept k
+  where k.permission not in (select d.permission from denied d)
+  union
+  select i.grant_key from included i
+  where i.effect = 'deny' and i.scope = p_scope
+  union
+  select c.grant_key from ceiling c
+  where c.permission in (select a.permission from allowed a)
+  union
+  select c.grant_key from ceiling c
+  join allowed_levels a on a.permission = c.permission
+  where c.effect = 'deny' or split_part(c.grant_key, '@', 2) = a.level
+$$;
+revoke execute on function ${keys}(text[], text[], text[], text) from public, anon, authenticated;`;
 }
-function sourceUser(index) {
-	return `v_user_${String(index)}`;
+function currentKeysSql(array) {
+	return `select coalesce(r.key, e.permission) as permission
+    from unnest(coalesce(${array}, '{}'::text[])) as e(permission)
+    left join renamed r on r.former = e.permission`;
 }
-function sqlBody(sql) {
-	return {
-		sql,
-		vars: []
+/**
+* SQL fragments that read a stored former key as its current key inside
+* `permdock_custom_keys`. Without renames they are the plain column and
+* array reads.
+*/
+function renamesSql(renames) {
+	if (renames.length === 0) return {
+		prelude: "",
+		permission: (alias) => `${alias}.permission`,
+		join: () => "",
+		allow: "select unnest(coalesce(p_allow, '{}'::text[])) as permission",
+		denied: (alias) => `${alias}.permission = any(coalesce(p_deny, '{}'::text[]))`
 	};
-}
-function sourcesBodyOf(sql, sources, user) {
 	return {
-		sql,
-		vars: sources.map((source, index) => `${sourceUser(index)} ${source.sql.userType} := ${user};`)
+		prelude: `renamed (former, key) as (values ${renames.map(([former, current]) => `(${quoteLiteral(former)}, ${quoteLiteral(current)})`).join(", ")}),
+  denied as (
+    ${currentKeysSql("p_deny")}
+  ),
+  `,
+		permission: (alias) => `coalesce(r_${alias}.key, ${alias}.permission) as permission`,
+		join: (alias) => ` left join renamed r_${alias} on r_${alias}.former = ${alias}.permission`,
+		allow: currentKeysSql("p_allow"),
+		denied: (alias) => `${alias}.permission in (select d.permission from denied d)`
 	};
 }
-/** `language sql`, or `plpgsql` returning the query when the body declares variables. */
-function functionBody(body) {
-	if (body.vars.length === 0) return `language sql
+/**
+* The catalog reader `permdock_permission_keys()` and the role reader
+* `permdock_role_permissions(p_role, p_scope, p_tenant, p_scope_id)`, both
+* for `authenticated`. A declared role answers from `role_permissions`, which
+* is the catalog. A custom role (`database` mode) answers from the tenant's
+* own rows through `permdock_custom_keys`, only to a member of the tenant or
+* a holder of a `meta.manageRoles` permission for a platform role; a shared
+* role (no tenant below global) to any signed-in caller. The
+* effect is `deny` for a deny the role carries after the ceiling, as
+* `resolveCustomRole` returns it, never for a deny that merely removes an allow.
+*/
+function roleReadersSql(ctx, permissions, trustedReaders) {
+	const rp = qualified(ctx, "role_permissions");
+	const reader = qualified(ctx, READERS.roles);
+	const tenantType = tenantTypeOf(ctx);
+	const custom = ctx.customRoles;
+	const root = ctx.scopes[0]?.name;
+	const database = ctx.authorize === "database";
+	const chunks = [];
+	if (permissions !== void 0) {
+		const catalog = qualified(ctx, READERS.keys);
+		chunks.push(`-- every declared permission key
+create or replace function ${catalog}()
+returns setof text
+language sql
+stable
+set search_path = ''
+as $$
+  select k.permission from unnest(${sqlTextArray(permissions.toSorted())}) k(permission) order by 1
+$$;
+revoke execute on function ${catalog}() from public, anon;
+grant execute on function ${catalog}() to authenticated;
+
+create or replace function ${catalog}(p_scope text)
+returns setof text
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select distinct rp.permission
+  from ${rp} rp
+  where rp.scope = p_scope
+    and rp.effect = 'allow'
+    and rp.permission = any(${sqlTextArray(permissions.toSorted())})
+  order by 1
+$$;
+revoke execute on function ${catalog}(text) from public, anon;
+grant execute on function ${catalog}(text) to authenticated;`);
+	}
+	const declared = `  select distinct rp.permission, rp.effect
+  from ${rp} rp
+  where rp.role = p_role and rp.scope = p_scope
+  order by 1, 2`;
+	let body = `begin
+  perform p_tenant, p_scope_id; -- only a custom role reads them
+  return query
+${declared};
+end;`;
+	let trustedBody = body;
+	if (custom !== void 0 && database && root !== void 0) {
+		const tenant = qualified(ctx, CUSTOM_ROLES.permissions);
+		const includes = qualified(ctx, CUSTOM_ROLES.includes);
+		const keys = qualified(ctx, CUSTOM_ROLES.keys);
+		const shape = qualified(ctx, CUSTOM_ROLES.shape);
+		const ids = (helper) => `(select x::text from ${qualified(ctx, helper)}() x)`;
+		const memberOf = `p_tenant::text in ${ids(memberIdsHelper(root))}
+      or ${perScope(ctx, (scope) => scope === root ? "false" : `p_scope_id in ${ids(memberIdsHelper(scope))}`)}`;
+		const manage = custom.manage ?? [];
+		const platform = manage.length === 0 ? "false" : `exists (
+        select 1 from ${rp} m
+        where m.effect = 'allow'
+          and m.permission = any(${sqlTextArray(manage)})
+          and ${qualified(ctx, HELPERS.has)}(m.grant_key)
+      )`;
+		const match = `c.tenant_id is not distinct from p_tenant and c.scope = p_scope and c.scope_id is not distinct from p_scope_id and c.role = p_role`;
+		const allowEntryOf = custom.levels === true ? "c.permission || coalesce('@' || c.level, '')" : "c.permission";
+		const checked = (gate) => `begin
+  if p_role = any(${sqlTextArray(custom.declared)}) then
+    return query
+${declared};
+    return;
+  end if;
+  perform ${shape}(p_tenant, p_scope, p_scope_id, p_role);${gate}
+  return query
+  select distinct rp.permission, rp.effect
+  from ${keys}(
+    array(select ${allowEntryOf} from ${tenant} c where ${match} and c.effect = 'allow'),
+    array(select c.permission from ${tenant} c where ${match} and c.effect = 'deny'),
+    array(select c.include_role from ${includes} c where ${match}),
+    p_scope
+  ) k(grant_key)
+  join ${rp} rp on rp.grant_key = k.grant_key and rp.scope = p_scope
+  order by 1, 2;
+end;`;
+		body = checked(`
+  if not (${signedIn(ctx)} and (
+    ${platform}
+    or (p_scope <> 'global' and p_tenant is null and p_scope_id is null)
+    or (p_scope <> 'global' and (${memberOf}))
+  )) then
+${raiseSql("    ", "42501", `'permdock: the caller is not a member of ' || coalesce(p_tenant::text, 'the platform')`, "not-member")}
+  end if;`);
+		trustedBody = checked("");
+	}
+	chunks.push(`-- the permission keys a role holds on a scope, with effect allow or deny; a custom role is read for its tenant and, below the first scope, its instance
+create or replace function ${reader}(p_role text, p_scope text, p_tenant ${tenantType} default null, p_scope_id text default null)
+returns table (permission text, effect text)
+language plpgsql
 stable
 security definer
 set search_path = ''
 as $$
-${body.sql}
-$$;`;
-	return `language plpgsql
+${body}
+$$;
+revoke execute on function ${reader}(text, text, ${tenantType}, text) from public, anon;
+grant execute on function ${reader}(text, text, ${tenantType}, text) to authenticated;`);
+	const trusted = qualified(ctx, READERS.trusted);
+	const signature = `text, text, ${tenantType}, text`;
+	const grants = trustedReaders === void 0 || trustedReaders.length === 0 ? "" : `\ngrant execute on function ${trusted}(${signature}) to ${trustedReaders.map(quoteIdent).join(", ")};`;
+	chunks.push(`create or replace function ${trusted}(p_role text, p_scope text, p_tenant ${tenantType} default null, p_scope_id text default null)
+returns table (permission text, effect text)
+language plpgsql
 stable
 security definer
 set search_path = ''
 as $$
-declare
-${body.vars.map((line) => `  ${line}`).join("\n")}
-begin
-  return query
-${body.sql};
-end;
-$$;`;
+${trustedBody}
+$$;
+revoke execute on function ${trusted}(${signature}) from public, anon, authenticated;${grants}`);
+	return chunks.join("\n\n");
+}
+/** The stored definition of `p_role` at `p_scope` for `p_tenant`: the shared rows when a shared role has the name. */
+function storedTenant(ctx) {
+	return `case when ${qualified(ctx, CUSTOM_ROLES.shared)}(p_scope, p_role) then c.tenant_id is null else c.tenant_id is not distinct from p_tenant end`;
 }
 /**
-* `ms.id` for the scope itself and `ms.within ->> name` for an ancestor. The
-* alias is not `s`, which `activeRowSql` binds inside its `exists`.
+* The tenant half of a custom-role row match for a membership: the
+* membership's tenant, or no tenant when a shared role of that name exists at
+* the scope, so a shared role shadows a tenant role of the same name.
 */
-function sourceIdOf(scope) {
-	return (name) => name === scope ? "ms.id" : `ms.within ->> ${quoteLiteral(name)}`;
+function customTenantMatch(ctx, tenant, scope, role) {
+	return `case when ${qualified(ctx, CUSTOM_ROLES.shared)}(${quoteLiteral(scope)}, ${role}) then c.tenant_id is null else c.tenant_id::text = ${tenant} end`;
 }
-function sourceFilters(ctx, scope, user = subjectIdSql(ctx), permission, keeps = false) {
-	return [
-		...keeps ? [`    and ${keptRowSql("ms.keep", permission)}`] : [],
-		...userActive(ctx, "    ", user),
-		...instancesActive(ctx, scope, sourceIdOf(scope), "    ", permission)
-	].map((line) => `\n${line}`).join("");
+/**
+* The scope of a row of the application's roles table: its scope column (or
+* the first scope) with a tenant; with no tenant, the same scope when the
+* `shared` column is true, else `'global'`.
+*/
+function rolesTableScope(table, tenant, root, column) {
+	const own = table.scope === void 0 ? quoteLiteral(root) : `${column(table.scope)}::text`;
+	return `case when ${tenant} is null then ${table.shared === void 0 ? "'global'" : `case when coalesce(${column(table.shared)}, false) then ${own} else 'global' end`} else ${own} end`;
 }
-function sourcesBody(ctx, scope, type) {
-	const root = rootName(ctx);
-	const tenant = sourceIdOf(scope)(root);
-	const narrow = narrowsTo(ctx, scope) ? `\n    and (${activeTenant(ctx)} is null or ${tenant} = ${activeTenant(ctx)})${keyTenantLine(ctx, scope, tenant)}` : keyTenantLine(ctx, scope, tenant);
-	const sources = scopeSources(ctx, scope);
-	const set = ctx.grantSet === true;
-	const rows = `  from (
-${sourceRows(sources)}
-  ) ms
-  cross join lateral jsonb_array_elements_text(
-    case jsonb_typeof(ms.roles) when 'array' then ms.roles else '[]'::jsonb end
-  ) r(role)`;
-	const declared = `  select (ms.id)::${type}${set ? ", rp.grant_key" : ""}
-${rows}
-  join ${qualified(ctx, "role_permissions")} rp on rp.role = r.role
-  where ${signedIn(ctx)}
-    and ms.scope = ${quoteLiteral(scope)}${set ? "" : "\n    and rp.grant_key = p_grant"}
-    and rp.scope = ${quoteLiteral(scope)}${andLine("    ", kindFilterSql(ctx, "r.role", "ms.via"))}${narrow}${sourceFilters(ctx, scope, subjectIdSql(ctx), grantPermissionSql(set ? "rp.grant_key" : "p_grant"), sourcesKeep(sources))}`;
-	const custom = ctx.customRoles;
-	if (custom === void 0) return sourcesBodyOf(declared, sources, subjectIdSql(ctx));
-	const match = [
-		`c.tenant_id::text = (${tenant})::text`,
-		`c.scope = ${quoteLiteral(scope)}`,
-		"(c.scope_id is null or c.scope_id = (ms.id)::text)",
-		"c.role = r.role"
-	].join(" and ");
-	const entries = (source, value, extra) => `array(select c.${value} from ${qualified(ctx, source)} c where ${match}${extra})`;
-	if (set) return sourcesBodyOf(`${declared}
-  union
-  select (ms.id)::${type}, ck.grant_key
-${rows}
-${customKeysJoin(ctx, scope, entries(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'allow'"), entries(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'deny'"), entries(CUSTOM_ROLES.includes, "include_role", ""))}
-  where ${signedIn(ctx)}
-    and ms.scope = ${quoteLiteral(scope)}
-    and not (r.role = any(${sqlTextArray(custom.declared)}))${narrow}${sourceFilters(ctx, scope, subjectIdSql(ctx), grantPermissionSql("ck.grant_key"), sourcesKeep(sources))}`, sources, subjectIdSql(ctx));
-	return sourcesBodyOf(`${declared}
-  union
-  select (ms.id)::${type}
-${rows}
-  where ${signedIn(ctx)}
-    and ms.scope = ${quoteLiteral(scope)}
-    and not (r.role = any(${sqlTextArray(custom.declared)}))${narrow}${sourceFilters(ctx, scope, subjectIdSql(ctx), grantPermissionSql("p_grant"), sourcesKeep(sources))}
-${customKeysSql(ctx, scope, entries(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'allow'"), entries(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'deny'"), entries(CUSTOM_ROLES.includes, "include_role", ""))}`, sources, subjectIdSql(ctx));
+/** `expr` read as its current key: a former key maps to the key it was renamed to. */
+function currentKeyExpr(renames, expr) {
+	if (renames.length === 0) return expr;
+	return `(case ${expr} ${renames.map(([former, current]) => `when ${quoteLiteral(former)} then ${quoteLiteral(current)}`).join(" ")} else ${expr} end)`;
 }
-function scopedBody(ctx, scope, type) {
-	if (ctx.authorize !== "database") return sqlBody(claimBody(ctx, scope, type));
-	return scopeSources(ctx, scope).length > 0 ? sourcesBody(ctx, scope, type) : sqlBody(tableBody(ctx, scope, type));
+/** `case p_scope when '<scope>' then <sql for scope> ... else false end` over the declared scopes. */
+function perScope(ctx, sql) {
+	const arms = ctx.scopes.map((scope) => `when ${quoteLiteral(scope.name)} then ${sql(scope.name)}`).join(" ");
+	return arms === "" ? "false" : `(case p_scope ${arms} else false end)`;
+}
+function raiseSql(indent, errcode, message, hint) {
+	return `${indent}raise exception using
+${indent}  errcode = '${errcode}',
+${indent}  message = ${message},
+${indent}  hint = ${quoteLiteral(hint)};`;
+}
+function hasCustomRoleChecksFor(ctx) {
+	return ctx.authorize === "database" && ctx.customRoles !== void 0 && ctx.scopes.length > 0 && ctx.scopes.every((scope) => hasMemberFor(ctx, scope.name));
 }
 //#endregion
-//#region src/cli/rls/capabilities.ts
-/** The helper `--capabilities` adds: ids of one resource a link capability claim reaches. Part of the SQL contract. */
-const CAPABILITIES = { ids: "permdock_capability_ids" };
-/**
-* The `anon` branch access for a resource-scoped grant reached through a link
-* capability: the row's `field` holds an id the capability claim names for
-* `resource`, `role` and `permission`. Uncorrelated, so it runs once per
-* statement; the column is compared as text because the claim holds text.
-*/
-function capabilityAccessSql(ctx, field, resource, role, permission) {
-	const args = [
-		resource,
-		role,
-		permission
-	].map(quoteLiteral).join(", ");
-	return `${quoteIdent(field)}::text in (select ${qualified(ctx, CAPABILITIES.ids)}(${args}))`;
+//#region src/cli/sql/global-roles.ts
+function qualify(name, schema) {
+	return name.includes(".") ? name : `${schema}.${name}`;
+}
+function throughTenant(through, roles) {
+	if (through === void 0 || roles?.tenant === void 0) return;
+	return qualify(roles.table, "public") === through.table ? roles.tenant : void 0;
+}
+/** Resolves `source` against `schema`, aliasing the table `alias` and the roles table `<alias>k`. */
+function globalRoleSource(source, schema, alias, roles) {
+	const table = qualify(source.table, schema);
+	const user = source.user ?? "user_id";
+	const role = roleColumn(source.role ?? "role", table, alias, {
+		label: "roles.role",
+		prefix: "PermDock CLI",
+		indent: "    "
+	});
+	const tenant = role.lateral ? void 0 : throughTenant(role.through, roles);
+	const shared = tenant === void 0 ? void 0 : roles?.shared;
+	const global = tenant === void 0 ? "" : ` and ${alias}k.${quoteIdent(tenant)} is null${shared === void 0 ? "" : ` and ${alias}k.${quoteIdent(shared)} is not true`}`;
+	return {
+		table,
+		user,
+		from: `${quoteTable(table)} ${alias}${role.join}${global}`,
+		userSql: `${alias}.${quoteIdent(user)}`,
+		roleSql: role.sql,
+		role: roleManifest(role),
+		...role.through === void 0 ? {} : { through: role.through },
+		...tenant === void 0 ? {} : { tenant },
+		...shared === void 0 ? {} : { shared }
+	};
+}
+//#endregion
+//#region src/cli/rls/helper-rows.ts
+function activeTenant(ctx) {
+	return `nullif(${subjectClaimSql(ctx, ctx.tenantClaim)}, '')`;
+}
+function keyTenantLine(ctx, scope, tenant) {
+	const keyed = keyTenantSql(ctx, underRoot(ctx, scope) ? tenant : void 0);
+	return keyed === void 0 ? "" : `\n    and ${keyed}`;
+}
+/** Whether the helper for `scope` narrows to the tenant claim: unless `rls.tenants` is `'all'`, when the first scope is on its chain. */
+function narrowsTo(ctx, scope) {
+	return ctx.tenants !== "all" && underRoot(ctx, scope);
+}
+/** Whether the active tenant narrows memberships of `scope`: the first scope is on its chain. */
+function underRoot(ctx, scope) {
+	const root = ctx.scopes[0]?.name;
+	let current = ctx.scopes.find((item) => item.name === scope);
+	const seen = /* @__PURE__ */ new Set();
+	while (current !== void 0 && !seen.has(current.name)) {
+		if (current.name === root) return true;
+		seen.add(current.name);
+		const parent = current.within;
+		current = parent === void 0 ? void 0 : ctx.scopes.find((item) => item.name === parent);
+	}
+	return false;
+}
+/** `and exists (...)` lines for an active user; empty without `rls.suspension.users`. */
+function userActive(ctx, indent, user) {
+	return activeUserSql(ctx, user).map((part) => `${indent}and ${part}`);
+}
+/** `and exists (...)` lines for every suspendable instance on the chain of `scope`'s membership. */
+function instancesActive(ctx, scope, idOf, indent, permission) {
+	return activeInstancesSql(ctx, scope, idOf, permission).map((part) => `${indent}and ${part}`);
+}
+function roleRows(ctx) {
+	const claim = ctx.roleClaim ?? "user_role";
+	switch (ctx.dialect) {
+		case "guc": return `unnest(string_to_array(nullif(current_setting(${quoteLiteral(`${ctx.gucPrefix}.${claim}`)}, true), ''), ',')) r(role)`;
+		case "supabase":
+		case "neon": {
+			const raw = subjectClaimJsonSql(ctx, claim);
+			const value = ctx.dialect === "supabase" ? `coalesce(nullif(${raw}, 'null'::jsonb), (select auth.jwt()) -> 'app_metadata' -> ${quoteLiteral(claim)})` : raw;
+			return `jsonb_array_elements_text(
+      case jsonb_typeof(${value})
+        when 'array' then ${value}
+        when 'string' then jsonb_build_array(${value})
+        else '[]'::jsonb
+      end
+    ) r(role)`;
+		}
+		default: return ctx.dialect;
+	}
+}
+function membershipRows(ctx) {
+	const raw = subjectClaimJsonSql(ctx, "memberships");
+	const value = ctx.dialect === "supabase" ? `coalesce(${raw}, (select auth.jwt()) -> 'app_metadata' -> 'memberships')` : raw;
+	return `jsonb_array_elements(
+      case jsonb_typeof(${value}) when 'array' then ${value} else '[]'::jsonb end
+    ) m
+    cross join lateral jsonb_array_elements_text(
+      case jsonb_typeof(m -> 'roles') when 'array' then m -> 'roles' else '[]'::jsonb end
+    ) r(role)`;
+}
+function andLine(indent, condition) {
+	return condition === void 0 ? "" : `\n${indent}and ${condition}`;
+}
+/** `rls.roles`, or the generated `user_roles (user_id, role)`, aliased `ur`. */
+function globalRoleRows(ctx) {
+	return ctx.roles === void 0 ? {
+		from: `${qualified(ctx, "user_roles")} ur`,
+		userSql: "ur.user_id",
+		roleSql: "ur.role::text"
+	} : globalRoleSource(ctx.roles, "public", "ur", ctx.customRoles?.table);
 }
-function capabilitiesSql(ctx) {
-	if (ctx.capabilities !== true) return "";
-	const fn = qualified(ctx, CAPABILITIES.ids);
-	return `-- link capabilities: the capability claim exchangeCapability mints (role anon, short-lived)
-create or replace function ${fn}(p_resource text, p_role text, p_permission text)
-returns setof text
-language sql
-stable
-set search_path = ''
-as $$
-  select c -> 'on' ->> 'id'
-  from (select ${subjectClaimJsonSql(ctx, "capability")} as c) capability
-  where jsonb_typeof(c) = 'object'
-    and c ->> 'v' = '1'
-    and c ->> 'holder' = 'link'
-    and c -> 'on' ->> 'resource' = p_resource
-    and jsonb_typeof(c -> 'roles') = 'array'
-    and c -> 'roles' @> jsonb_build_array(p_role)
-    and (c -> 'permissions' is null or c -> 'permissions' @> jsonb_build_array(p_permission))
-    and jsonb_typeof(c -> 'expires_at') = 'number'
-    and (c ->> 'expires_at')::numeric > extract(epoch from now())
-$$;
-revoke execute on function ${fn}(text, text, text) from public;
-grant execute on function ${fn}(text, text, text) to anon, authenticated;`;
+function customKeysJoin(ctx, scope, allows, denies, includes) {
+	return `  cross join lateral ${qualified(ctx, CUSTOM_ROLES.keys)}(
+    ${allows},
+    ${denies},
+    ${includes},
+    ${quoteLiteral(scope)}
+  ) ck(grant_key)`;
 }
 //#endregion
-//#region src/cli/rls/custom-roles.ts
-/** The readers every helpers file ends with. Names are part of the SQL contract. */
-const READERS = {
-	keys: "permdock_permission_keys",
-	roles: "permdock_role_permissions",
-	trusted: "permdock_trusted_role_permissions"
-};
-/**
-* The custom-role objects: the tables (`database` mode), the ceiling view
-* over the `assignable` declared roles, and `permdock_custom_keys`, which
-* resolves one custom role to the grant keys it holds in a scope. A row in
-* the tables can never reach a key outside the view.
-*/
-function customRolesSql(ctx) {
-	const custom = ctx.customRoles;
-	if (custom === void 0) return "";
+//#region src/cli/rls/helper-bodies.ts
+function hasSetBody(ctx) {
 	const rp = qualified(ctx, "role_permissions");
-	const ceiling = qualified(ctx, CUSTOM_ROLES.ceiling);
-	const keys = qualified(ctx, CUSTOM_ROLES.keys);
-	const chunks = [];
+	const active = userActive(ctx, "    ").map((line) => `\n${line}`).join("");
+	const custom = ctx.customRoles;
 	if (ctx.authorize === "database") {
-		const tenantType = tenantTypeOf(ctx);
-		for (const [name, column, check] of [[
-			CUSTOM_ROLES.permissions,
-			"permission",
-			`,
-  effect text not null default 'allow' check (effect in ('allow', 'deny'))`
-		], [
-			CUSTOM_ROLES.includes,
-			"include_role",
-			""
-		]]) {
-			const table = qualified(ctx, name);
-			const leveled = custom.levels === true && name === CUSTOM_ROLES.permissions;
-			const unique = `${column}${name === CUSTOM_ROLES.permissions ? ", effect" : ""}${leveled ? ", coalesce(level, '')" : ""}`;
-			const index = leveled ? `drop index if exists ${qualified(ctx, quoteIdent(`${name}_key`))};
-alter table ${table} add column if not exists level text check (level ~ '^[a-z][a-z0-9_]*$');
-create unique index if not exists ${quoteIdent(`${name}_level_key`)}` : `create unique index if not exists ${quoteIdent(`${name}_key`)}`;
-			chunks.push(`create table if not exists ${table} (
-  tenant_id ${tenantType},
-  scope text not null default ${quoteLiteral(rootName(ctx))},
-  scope_id text,
-  role text not null,
-  ${column} text not null${check},
-  check ((scope = 'global') = (tenant_id is null)),
-  check (scope <> 'global' or scope_id is null)
-);
-${index}
-  on ${table} (coalesce(tenant_id::text, ''), scope, coalesce(scope_id, ''), role, ${unique});
--- a row identity for triggers the application adds, such as an audit trigger that reads the primary key
-alter table ${table} add column if not exists id bigint generated always as identity primary key;
-alter table ${table} enable row level security;
-revoke all on table ${table} from anon, authenticated, public;`);
-		}
+		const ur = globalRoleRows(ctx);
+		const declared = `  select rp.grant_key
+  from ${ur.from}
+  join ${rp} rp on rp.role = ${ur.roleSql}
+  where ${ur.userSql} = ${subjectIdSql(ctx)}
+    and rp.scope = 'global'${andLine("    ", globalKindFilterSql(ctx, ur.roleSql))}${active}`;
+		if (custom === void 0) return declared;
+		const match = `c.tenant_id is null and c.scope = 'global' and c.scope_id is null and c.role = ${ur.roleSql}`;
+		const rows = (source, value, extra) => `array(select c.${value} from ${qualified(ctx, source)} c where ${match}${extra})`;
+		return `${declared}
+  union
+  select ck.grant_key
+  from ${ur.from}
+${customKeysJoin(ctx, "global", rows(CUSTOM_ROLES.permissions, allowEntry(ctx), " and c.effect = 'allow'"), rows(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'deny'"), rows(CUSTOM_ROLES.includes, "include_role", ""))}
+  where ${ur.userSql} = ${subjectIdSql(ctx)}
+    and not (${ur.roleSql} = any(${sqlTextArray(custom.declared)}))${active}`;
 	}
-	chunks.push(`-- the ceiling: keys of assignable declared roles, and the denies of those roles on the same permissions
-create or replace view ${ceiling} with (security_invoker = true) as
-select rp.scope, rp.role, rp.permission, rp.grant_key, rp.effect
-from ${rp} rp
-where rp.role = any(${sqlTextArray(custom.assignable)})
-  and exists (
-    select 1 from ${rp} a
-    where a.role = rp.role
-      and a.permission = rp.permission
-      and a.scope = rp.scope
-      and a.effect = 'allow'
-  );
-revoke all on table ${ceiling} from anon, authenticated, public;`);
-	const renames = Object.entries(custom.renamed ?? {}).toSorted(byKey);
-	if (custom.levels === true) {
-		chunks.push(leveledKeysSql(ctx, renames));
-		return chunks.join("\n\n");
+	const declared = `  select rp.grant_key
+  from ${roleRows(ctx)}
+  join ${rp} rp on rp.role = r.role
+  where ${signedIn(ctx)}
+    and rp.scope = 'global'${andLine("    ", globalKindFilterSql(ctx, "r.role"))}${active}`;
+	if (custom === void 0) return declared;
+	const claim = subjectClaimJsonSql(ctx, GLOBAL_GRANTS_CLAIM);
+	return `${declared}
+  union
+  select ck.grant_key
+  from ${roleRows(ctx)}
+  cross join lateral (select ${claim} -> r.role as g) cg
+${customKeysJoin(ctx, "global", claimEntries("left(e, 1) not in ('-', '@')", "e"), claimEntries("left(e, 1) = '-'", "substr(e, 2)"), claimEntries("left(e, 1) = '@'", "substr(e, 2)"))}
+  where ${signedIn(ctx)}
+    and jsonb_typeof(cg.g) = 'array'
+    and not (r.role = any(${sqlTextArray(custom.declared)}))${active}`;
+}
+function hasBody(ctx) {
+	if (ctx.grantSet === true) return hasSetBody(ctx);
+	const rp = qualified(ctx, "role_permissions");
+	const active = userActive(ctx, "      ").map((line) => `\n${line}`).join("");
+	const custom = ctx.customRoles;
+	if (ctx.authorize === "database") {
+		const ur = globalRoleRows(ctx);
+		const declared = `  select exists (
+    select 1
+    from ${ur.from}
+    join ${rp} rp on rp.role = ${ur.roleSql}
+    where ${ur.userSql} = ${subjectIdSql(ctx)}
+      and rp.grant_key = p_grant
+      and rp.scope = 'global'${andLine("      ", globalKindFilterSql(ctx, ur.roleSql))}${active}
+  )`;
+		if (custom === void 0) return declared;
+		const match = `c.tenant_id is null and c.scope = 'global' and c.scope_id is null and c.role = ${ur.roleSql}`;
+		const rows = (source, value, extra) => `array(select c.${value} from ${qualified(ctx, source)} c where ${match}${extra})`;
+		return `${declared}
+  or exists (
+    select 1
+    from ${ur.from}
+    where ${ur.userSql} = ${subjectIdSql(ctx)}
+      and not (${ur.roleSql} = any(${sqlTextArray(custom.declared)}))${active}
+      ${customKeysSql(ctx, "global", rows(CUSTOM_ROLES.permissions, allowEntry(ctx), " and c.effect = 'allow'"), rows(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'deny'"), rows(CUSTOM_ROLES.includes, "include_role", "")).trimStart()}
+  )`;
 	}
-	const rename = renamesSql(renames);
-	chunks.push(`-- one custom role: included ceiling keys and same-scope denies, plus every ceiling key of an allowed permission, minus denied permissions
-create or replace function ${keys}(p_allow text[], p_deny text[], p_include text[], p_scope text)
-returns setof text
-language sql
-stable
-set search_path = ''
-as $$
-  with ${rename.prelude}ceiling as (
-    select c.role, ${rename.permission("c")}, c.grant_key, c.effect
-    from ${ceiling} c${rename.join("c")}
-    where c.scope = p_scope
-  ),
-  included as (
-    select rp.role, ${rename.permission("rp")}, rp.grant_key, rp.scope, rp.effect
-    from ${rp} rp${rename.join("rp")}
-    where rp.role = any(coalesce(p_include, '{}'::text[]))
-  ),
-  kept as (
-    select i.permission, i.grant_key
-    from included i
-    where i.effect = 'allow'
-      and i.scope = p_scope
-      and exists (
-        select 1 from ceiling c
-        where c.role = i.role and c.grant_key = i.grant_key and c.effect = 'allow'
-      )
-  ),
-  wanted as (
-    ${rename.allow}
-    union
-    select i.permission
-    from included i
-    where i.effect = 'allow'
-      and not (i.scope = p_scope and exists (
-        select 1 from ceiling c
-        where c.role = i.role and c.grant_key = i.grant_key and c.effect = 'allow'
-      ))
-  ),
-  allowed as (
-    select w.permission
-    from wanted w
-    where not (${rename.denied("w")})
-      and not exists (select 1 from kept k where k.permission = w.permission)
-  )
-  select k.grant_key from kept k
-  where not (${rename.denied("k")})
+	const declared = `  select ${signedIn(ctx)} and exists (
+    select 1
+    from ${roleRows(ctx)}
+    join ${rp} rp on rp.role = r.role
+    where rp.grant_key = p_grant
+      and rp.scope = 'global'${andLine("      ", globalKindFilterSql(ctx, "r.role"))}${active}
+  )`;
+	if (custom === void 0) return declared;
+	const claim = subjectClaimJsonSql(ctx, GLOBAL_GRANTS_CLAIM);
+	return `${declared}
+  or (${signedIn(ctx)} and exists (
+    select 1
+    from ${roleRows(ctx)}
+    cross join lateral (select ${claim} -> r.role as g) cg
+    where jsonb_typeof(cg.g) = 'array'
+      and not (r.role = any(${sqlTextArray(custom.declared)}))${active}
+      ${customKeysSql(ctx, "global", claimEntries("left(e, 1) not in ('-', '@')", "e"), claimEntries("left(e, 1) = '-'", "substr(e, 2)"), claimEntries("left(e, 1) = '@'", "substr(e, 2)")).trimStart()}
+  ))`;
+}
+/** The claim `jwt` mode reads platform custom roles from: `customRoleClaim(globalRoles)`. */
+const GLOBAL_GRANTS_CLAIM = "role_grants";
+function memberColumn(name) {
+	return `m.${quoteIdent(name)}`;
+}
+function disabledColumn(table) {
+	return table.disabledAt === void 0 ? void 0 : memberColumn(table.disabledAt);
+}
+function claimKeptLines(ctx, indent, permission) {
+	return disabledKeep(ctx).length === 0 ? [] : [`${indent}and ${keptRowSql("m -> 'keep'", permission)}`];
+}
+/** Entries of a compact custom-role claim (`cg.g`) that match `where`. */
+function claimEntries(where, value) {
+	return `array(select ${value} from jsonb_array_elements_text(cg.g) e where ${where})`;
+}
+/** `p_grant in (select permdock_custom_keys(allows, denies, includes, scope))`. */
+function customKeysSql(ctx, scope, allows, denies, includes) {
+	return `    and p_grant in (select ${qualified(ctx, CUSTOM_ROLES.keys)}(
+      ${allows},
+      ${denies},
+      ${includes},
+      ${quoteLiteral(scope)}
+    ))`;
+}
+function tableBody(ctx, scope, type) {
+	const mapped = scopeTable(ctx, scope);
+	if (mapped === void 0) return `  select null::${type} where false -- no ${scope} memberships table configured`;
+	const { table, column, tenantColumn } = mapped;
+	const set = ctx.grantSet === true;
+	const filtersFor = (grant) => {
+		const filters = [`  where ${memberColumn(table.user)} = ${subjectIdSql(ctx)}`];
+		if (table.expiresAt !== void 0) {
+			const expires = memberColumn(table.expiresAt);
+			filters.push(`    and (${expires} is null or ${expires} > now())`);
+		}
+		filters.push(...activeMembershipSql(ctx, disabledColumn(table), grantPermissionSql(grant)).map((part) => `    and ${part}`));
+		if (tenantColumn !== void 0 && ctx.tenants !== "all") filters.push(`    and (${activeTenant(ctx)} is null or ${memberColumn(tenantColumn)}::text = ${activeTenant(ctx)})`);
+		const keyed = keyTenantSql(ctx, tenantColumn === void 0 ? void 0 : memberColumn(tenantColumn));
+		if (keyed !== void 0) filters.push(`    and ${keyed}`);
+		filters.push(...userActive(ctx, "    "), ...instancesActive(ctx, scope, (name) => {
+			const held = scopeColumn(table, ctx.scopes, name);
+			return held === void 0 ? void 0 : memberColumn(held);
+		}, "    ", grantPermissionSql(grant)));
+		return filters;
+	};
+	const filters = filtersFor(set ? "rp.grant_key" : "p_grant");
+	const [owner, ...rest] = filters;
+	const role = memberRoleOf(table, "m", "  ");
+	const kind = kindFilterSql(ctx, role.sql, memberVia(table));
+	const lines = [
+		`  select${role.lateral ? " distinct" : ""} ${memberColumn(column)}::${type}${set ? ", rp.grant_key" : ""}`,
+		`  from ${quoteQualified(table.table)} m${role.join}`,
+		`  join ${qualified(ctx, "role_permissions")} rp on rp.role = ${role.sql}`,
+		owner ?? "",
+		...set ? [] : ["    and rp.grant_key = p_grant"],
+		`    and rp.scope = ${quoteLiteral(scope)}`,
+		...kind === void 0 ? [] : [`    and ${kind}`],
+		...rest
+	];
+	const custom = ctx.customRoles;
+	if (custom === void 0) return lines.join("\n");
+	const match = [
+		customTenantMatch(ctx, `${memberColumn(tenantColumn ?? column)}::text`, scope, role.sql),
+		`c.scope = ${quoteLiteral(scope)}`,
+		`(c.scope_id is null or c.scope_id = ${memberColumn(column)}::text)`,
+		`c.role = ${role.sql}`
+	].join(" and ");
+	const rows = (source, value, extra) => `array(select c.${value} from ${qualified(ctx, source)} c where ${match}${extra})`;
+	const entries = [
+		rows(CUSTOM_ROLES.permissions, allowEntry(ctx), " and c.effect = 'allow'"),
+		rows(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'deny'"),
+		rows(CUSTOM_ROLES.includes, "include_role", "")
+	];
+	if (set) return [
+		...lines,
+		"  union",
+		`  select ${memberColumn(column)}::${type}, ck.grant_key`,
+		`  from ${quoteQualified(table.table)} m${role.join}`,
+		customKeysJoin(ctx, scope, ...entries),
+		...filtersFor("ck.grant_key"),
+		`    and not (${role.sql} = any(${sqlTextArray(custom.declared)}))`
+	].join("\n");
+	return [
+		...lines,
+		"  union",
+		`  select ${memberColumn(column)}::${type}`,
+		`  from ${quoteQualified(table.table)} m${role.join}`,
+		...filters,
+		`    and not (${role.sql} = any(${sqlTextArray(custom.declared)}))`,
+		customKeysSql(ctx, scope, ...entries)
+	].join("\n");
+}
+/** The membership's instance of the first scope, from the canonical claim. */
+function claimTenant(ctx, scope) {
+	const root = rootName(ctx);
+	return scope === root ? `m ->> 'id'` : `m -> 'within' ->> ${quoteLiteral(root)}`;
+}
+function claimBody(ctx, scope, type) {
+	const set = ctx.grantSet === true;
+	const narrow = narrowsTo(ctx, scope) ? `
+    and (${activeTenant(ctx)} is null or ${claimTenant(ctx, scope)} = ${activeTenant(ctx)})` : "";
+	const filtersFor = (grant) => `    and m ->> 'scope' = ${quoteLiteral(scope)}
+    and m ->> 'id' is not null${narrow}${keyTenantLine(ctx, scope, claimTenant(ctx, scope))}
+    and case jsonb_typeof(m -> 'expires_at')
+      when 'number' then (m ->> 'expires_at')::numeric > extract(epoch from now())
+      else true
+    end${[
+		...claimKeptLines(ctx, "    ", grantPermissionSql(grant)),
+		...userActive(ctx, "    "),
+		...instancesActive(ctx, scope, (name) => name === scope ? `m ->> 'id'` : `m -> 'within' ->> ${quoteLiteral(name)}`, "    ", grantPermissionSql(grant))
+	].map((line) => `\n${line}`).join("")}`;
+	const filters = filtersFor(set ? "rp.grant_key" : "p_grant");
+	const declared = `  select (m ->> 'id')::${type}${set ? ", rp.grant_key" : ""}
+  from ${membershipRows(ctx)}
+  join ${qualified(ctx, "role_permissions")} rp on rp.role = r.role
+  where ${signedIn(ctx)}${set ? "" : "\n    and rp.grant_key = p_grant"}
+    and rp.scope = ${quoteLiteral(scope)}${andLine("    ", kindFilterSql(ctx, "r.role", "m ->> 'via'"))}
+${filters}`;
+	const custom = ctx.customRoles;
+	if (custom === void 0) return declared;
+	if (set) return `${declared}
   union
-  select i.grant_key from included i
-  where i.effect = 'deny' and i.scope = p_scope
+  select (m ->> 'id')::${type}, ck.grant_key
+  from ${membershipRows(ctx)}
+  cross join lateral (select m -> 'grants' -> r.role as g) cg
+${customKeysJoin(ctx, scope, claimEntries("left(e, 1) not in ('-', '@')", "e"), claimEntries("left(e, 1) = '-'", "substr(e, 2)"), claimEntries("left(e, 1) = '@'", "substr(e, 2)"))}
+  where ${signedIn(ctx)}
+    and jsonb_typeof(cg.g) = 'array'
+    and not (r.role = any(${sqlTextArray(custom.declared)}))
+${filtersFor("ck.grant_key")}`;
+	return `${declared}
   union
-  select c.grant_key from ceiling c
-  where c.permission in (select a.permission from allowed a)
-$$;
-revoke execute on function ${keys}(text[], text[], text[], text) from public, anon, authenticated;`);
-	return chunks.join("\n\n");
+  select (m ->> 'id')::${type}
+  from ${membershipRows(ctx)}
+  cross join lateral (select m -> 'grants' -> r.role as g) cg
+  where ${signedIn(ctx)}
+    and jsonb_typeof(cg.g) = 'array'
+    and not (r.role = any(${sqlTextArray(custom.declared)}))
+${filters}
+${customKeysSql(ctx, scope, claimEntries("left(e, 1) not in ('-', '@')", "e"), claimEntries("left(e, 1) = '-'", "substr(e, 2)"), claimEntries("left(e, 1) = '@'", "substr(e, 2)"))}`;
 }
 /**
-* `permdock_custom_keys` when resources declare levels. An allow entry is
-* `key` or `key@level`. A level reaches only the ceiling's `<grant key>@<level>`
-* keys, plus the ceiling denies of that permission; a level no ceiling key
-* carries removes the permission, as `resolveCustomRole` drops it with
-* `unknown-level`.
+* The rows the membership sources select for the subject, one per instance
+* (`scope`, `id`, `within`, `roles`, `via`), with each source's own expiry
+* and suspension filters: the statements the token hook runs.
 */
-function leveledKeysSql(ctx, renames) {
-	const rp = qualified(ctx, "role_permissions");
-	const ceiling = qualified(ctx, CUSTOM_ROLES.ceiling);
-	const keys = qualified(ctx, CUSTOM_ROLES.keys);
-	const renamed = renames.length > 0;
-	const prelude = renamed ? `renamed (former, key) as (values ${renames.map(([former, current]) => `(${quoteLiteral(former)}, ${quoteLiteral(current)})`).join(", ")}),
-  ` : "";
-	const current = (raw, alias) => renamed ? `coalesce(r_${alias}.key, ${raw})` : raw;
-	const join = (raw, alias) => renamed ? ` left join renamed r_${alias} on r_${alias}.former = ${raw}` : "";
-	return `-- one custom role: as above, where an allow entry key@level reaches only the ceiling keys of that level
-create or replace function ${keys}(p_allow text[], p_deny text[], p_include text[], p_scope text)
-returns setof text
-language sql
-stable
-set search_path = ''
-as $$
-  with ${prelude}entries as (
-    select ${current("split_part(e.entry, '@', 1)", "e")} as permission, nullif(split_part(e.entry, '@', 2), '') as level
-    from unnest(coalesce(p_allow, '{}'::text[])) as e(entry)${join("split_part(e.entry, '@', 1)", "e")}
-  ),
-  ceiling as (
-    select c.role, ${current("c.permission", "c")} as permission, c.grant_key, c.effect
-    from ${ceiling} c${join("c.permission", "c")}
-    where c.scope = p_scope
-  ),
-  levels as (
-    select distinct c.permission, split_part(c.grant_key, '@', 2) as level
-    from ceiling c
-    where c.effect = 'allow' and strpos(c.grant_key, '@') > 0
-  ),
-  denied as (
-    select ${current("d.permission", "d")} as permission
-    from unnest(coalesce(p_deny, '{}'::text[])) as d(permission)${join("d.permission", "d")}
-    union
-    select e.permission from entries e
-    where e.level is not null
-      and not exists (select 1 from levels l where l.permission = e.permission and l.level = e.level)
-  ),
-  included as (
-    select rp.role, ${current("rp.permission", "rp")} as permission, rp.grant_key, rp.scope, rp.effect
-    from ${rp} rp${join("rp.permission", "rp")}
-    where rp.role = any(coalesce(p_include, '{}'::text[]))
-  ),
-  kept as (
-    select i.permission, i.grant_key
-    from included i
-    where i.effect = 'allow'
-      and i.scope = p_scope
-      and exists (
-        select 1 from ceiling c
-        where c.role = i.role and c.grant_key = i.grant_key and c.effect = 'allow'
-      )
-  ),
-  wanted as (
-    select e.permission from entries e where e.level is null
-    union
-    select i.permission
-    from included i
-    where i.effect = 'allow'
-      and not (i.scope = p_scope and exists (
-        select 1 from ceiling c
-        where c.role = i.role and c.grant_key = i.grant_key and c.effect = 'allow'
-      ))
-  ),
-  allowed as (
-    select w.permission
-    from wanted w
-    where w.permission not in (select d.permission from denied d)
-      and not exists (select 1 from kept k where k.permission = w.permission)
-  ),
-  allowed_levels as (
-    select e.permission, e.level
-    from entries e
-    where e.level is not null
-      and e.permission not in (select d.permission from denied d)
-      and e.permission not in (select a.permission from allowed a)
-      and not exists (select 1 from kept k where k.permission = e.permission)
-  )
-  select k.grant_key from kept k
-  where k.permission not in (select d.permission from denied d)
-  union
-  select i.grant_key from included i
-  where i.effect = 'deny' and i.scope = p_scope
-  union
-  select c.grant_key from ceiling c
-  where c.permission in (select a.permission from allowed a)
-  union
-  select c.grant_key from ceiling c
-  join allowed_levels a on a.permission = c.permission
-  where c.effect = 'deny' or split_part(c.grant_key, '@', 2) = a.level
-$$;
-revoke execute on function ${keys}(text[], text[], text[], text) from public, anon, authenticated;`;
+function sourcesKeep(sources) {
+	return sources.some((source) => source.sql.keeps);
 }
-function currentKeysSql(array) {
-	return `select coalesce(r.key, e.permission) as permission
-    from unnest(coalesce(${array}, '{}'::text[])) as e(permission)
-    left join renamed r on r.former = e.permission`;
+function sourceRows(sources) {
+	const keep = sourcesKeep(sources);
+	return sources.map((source, index) => source.sql.select(sourceUser(index), keep).replaceAll(/^/gmu, "    ")).join("\n    union all\n");
 }
-/**
-* SQL fragments that read a stored former key as its current key inside
-* `permdock_custom_keys`. Without renames they are the plain column and
-* array reads.
-*/
-function renamesSql(renames) {
-	if (renames.length === 0) return {
-		prelude: "",
-		permission: (alias) => `${alias}.permission`,
-		join: () => "",
-		allow: "select unnest(coalesce(p_allow, '{}'::text[])) as permission",
-		denied: (alias) => `${alias}.permission = any(coalesce(p_deny, '{}'::text[]))`
-	};
+function sourceUser(index) {
+	return `v_user_${String(index)}`;
+}
+function sqlBody(sql) {
 	return {
-		prelude: `renamed (former, key) as (values ${renames.map(([former, current]) => `(${quoteLiteral(former)}, ${quoteLiteral(current)})`).join(", ")}),
-  denied as (
-    ${currentKeysSql("p_deny")}
-  ),
-  `,
-		permission: (alias) => `coalesce(r_${alias}.key, ${alias}.permission) as permission`,
-		join: (alias) => ` left join renamed r_${alias} on r_${alias}.former = ${alias}.permission`,
-		allow: currentKeysSql("p_allow"),
-		denied: (alias) => `${alias}.permission in (select d.permission from denied d)`
+		sql,
+		vars: []
+	};
+}
+function sourcesBodyOf(sql, sources, user) {
+	return {
+		sql,
+		vars: sources.map((source, index) => `${sourceUser(index)} ${source.sql.userType} := ${user};`)
 	};
 }
-/**
-* The catalog reader `permdock_permission_keys()` and the role reader
-* `permdock_role_permissions(p_role, p_scope, p_tenant, p_scope_id)`, both
-* for `authenticated`. A declared role answers from `role_permissions`, which
-* is the catalog. A custom role (`database` mode) answers from the tenant's
-* own rows through `permdock_custom_keys`, only to a member of the tenant or
-* a holder of a `meta.manageRoles` permission for a platform role. The
-* effect is `deny` for a deny the role carries after the ceiling, as
-* `resolveCustomRole` returns it, never for a deny that merely removes an allow.
-*/
-function roleReadersSql(ctx, permissions, trustedReaders) {
-	const rp = qualified(ctx, "role_permissions");
-	const reader = qualified(ctx, READERS.roles);
-	const tenantType = tenantTypeOf(ctx);
-	const custom = ctx.customRoles;
-	const root = ctx.scopes[0]?.name;
-	const database = ctx.authorize === "database";
-	const chunks = [];
-	if (permissions !== void 0) {
-		const catalog = qualified(ctx, READERS.keys);
-		chunks.push(`-- every declared permission key
-create or replace function ${catalog}()
-returns setof text
-language sql
-stable
-set search_path = ''
-as $$
-  select k.permission from unnest(${sqlTextArray(permissions.toSorted())}) k(permission) order by 1
-$$;
-revoke execute on function ${catalog}() from public, anon;
-grant execute on function ${catalog}() to authenticated;
-
-create or replace function ${catalog}(p_scope text)
-returns setof text
-language sql
-stable
-security definer
-set search_path = ''
-as $$
-  select distinct rp.permission
-  from ${rp} rp
-  where rp.scope = p_scope
-    and rp.effect = 'allow'
-    and rp.permission = any(${sqlTextArray(permissions.toSorted())})
-  order by 1
-$$;
-revoke execute on function ${catalog}(text) from public, anon;
-grant execute on function ${catalog}(text) to authenticated;`);
-	}
-	const declared = `  select distinct rp.permission, rp.effect
-  from ${rp} rp
-  where rp.role = p_role and rp.scope = p_scope
-  order by 1, 2`;
-	let body = `begin
-  perform p_tenant, p_scope_id; -- only a custom role reads them
-  return query
-${declared};
-end;`;
-	let trustedBody = body;
-	if (custom !== void 0 && database && root !== void 0) {
-		const tenant = qualified(ctx, CUSTOM_ROLES.permissions);
-		const includes = qualified(ctx, CUSTOM_ROLES.includes);
-		const keys = qualified(ctx, CUSTOM_ROLES.keys);
-		const shape = qualified(ctx, CUSTOM_ROLES.shape);
-		const ids = (helper) => `(select x::text from ${qualified(ctx, helper)}() x)`;
-		const memberOf = `p_tenant::text in ${ids(memberIdsHelper(root))}
-      or ${perScope(ctx, (scope) => scope === root ? "false" : `p_scope_id in ${ids(memberIdsHelper(scope))}`)}`;
-		const manage = custom.manage ?? [];
-		const platform = manage.length === 0 ? "false" : `exists (
-        select 1 from ${rp} m
-        where m.effect = 'allow'
-          and m.permission = any(${sqlTextArray(manage)})
-          and ${qualified(ctx, HELPERS.has)}(m.grant_key)
-      )`;
-		const match = `c.tenant_id is not distinct from p_tenant and c.scope = p_scope and c.scope_id is not distinct from p_scope_id and c.role = p_role`;
-		const allowEntryOf = custom.levels === true ? "c.permission || coalesce('@' || c.level, '')" : "c.permission";
-		const checked = (gate) => `begin
-  if p_role = any(${sqlTextArray(custom.declared)}) then
-    return query
-${declared};
-    return;
-  end if;
-  perform ${shape}(p_tenant, p_scope, p_scope_id, p_role);${gate}
-  return query
-  select distinct rp.permission, rp.effect
-  from ${keys}(
-    array(select ${allowEntryOf} from ${tenant} c where ${match} and c.effect = 'allow'),
-    array(select c.permission from ${tenant} c where ${match} and c.effect = 'deny'),
-    array(select c.include_role from ${includes} c where ${match}),
-    p_scope
-  ) k(grant_key)
-  join ${rp} rp on rp.grant_key = k.grant_key and rp.scope = p_scope
-  order by 1, 2;
-end;`;
-		body = checked(`
-  if not (${signedIn(ctx)} and (
-    ${platform}
-    or (p_scope <> 'global' and (${memberOf}))
-  )) then
-${raiseSql("    ", "42501", `'permdock: the caller is not a member of ' || coalesce(p_tenant::text, 'the platform')`, "not-member")}
-  end if;`);
-		trustedBody = checked("");
-	}
-	chunks.push(`-- the permission keys a role holds on a scope, with effect allow or deny; a custom role is read for its tenant and, below the first scope, its instance
-create or replace function ${reader}(p_role text, p_scope text, p_tenant ${tenantType} default null, p_scope_id text default null)
-returns table (permission text, effect text)
-language plpgsql
+/** `language sql`, or `plpgsql` returning the query when the body declares variables. */
+function functionBody(body) {
+	if (body.vars.length === 0) return `language sql
 stable
 security definer
 set search_path = ''
 as $$
-${body}
-$$;
-revoke execute on function ${reader}(text, text, ${tenantType}, text) from public, anon;
-grant execute on function ${reader}(text, text, ${tenantType}, text) to authenticated;`);
-	const trusted = qualified(ctx, READERS.trusted);
-	const signature = `text, text, ${tenantType}, text`;
-	const grants = trustedReaders === void 0 || trustedReaders.length === 0 ? "" : `\ngrant execute on function ${trusted}(${signature}) to ${trustedReaders.map(quoteIdent).join(", ")};`;
-	chunks.push(`create or replace function ${trusted}(p_role text, p_scope text, p_tenant ${tenantType} default null, p_scope_id text default null)
-returns table (permission text, effect text)
-language plpgsql
+${body.sql}
+$$;`;
+	return `language plpgsql
 stable
 security definer
 set search_path = ''
 as $$
-${trustedBody}
-$$;
-revoke execute on function ${trusted}(${signature}) from public, anon, authenticated;${grants}`);
-	return chunks.join("\n\n");
+declare
+${body.vars.map((line) => `  ${line}`).join("\n")}
+begin
+  return query
+${body.sql};
+end;
+$$;`;
 }
-/** `expr` read as its current key: a former key maps to the key it was renamed to. */
-function currentKeyExpr(renames, expr) {
-	if (renames.length === 0) return expr;
-	return `(case ${expr} ${renames.map(([former, current]) => `when ${quoteLiteral(former)} then ${quoteLiteral(current)}`).join(" ")} else ${expr} end)`;
+/**
+* `ms.id` for the scope itself and `ms.within ->> name` for an ancestor. The
+* alias is not `s`, which `activeRowSql` binds inside its `exists`.
+*/
+function sourceIdOf(scope) {
+	return (name) => name === scope ? "ms.id" : `ms.within ->> ${quoteLiteral(name)}`;
 }
-/** `case p_scope when '<scope>' then <sql for scope> ... else false end` over the declared scopes. */
-function perScope(ctx, sql) {
-	const arms = ctx.scopes.map((scope) => `when ${quoteLiteral(scope.name)} then ${sql(scope.name)}`).join(" ");
-	return arms === "" ? "false" : `(case p_scope ${arms} else false end)`;
+function sourceFilters(ctx, scope, user = subjectIdSql(ctx), permission, keeps = false) {
+	return [
+		...keeps ? [`    and ${keptRowSql("ms.keep", permission)}`] : [],
+		...userActive(ctx, "    ", user),
+		...instancesActive(ctx, scope, sourceIdOf(scope), "    ", permission)
+	].map((line) => `\n${line}`).join("");
 }
-function raiseSql(indent, errcode, message, hint) {
-	return `${indent}raise exception using
-${indent}  errcode = '${errcode}',
-${indent}  message = ${message},
-${indent}  hint = ${quoteLiteral(hint)};`;
+function sourcesBody(ctx, scope, type) {
+	const root = rootName(ctx);
+	const tenant = sourceIdOf(scope)(root);
+	const narrow = narrowsTo(ctx, scope) ? `\n    and (${activeTenant(ctx)} is null or ${tenant} = ${activeTenant(ctx)})${keyTenantLine(ctx, scope, tenant)}` : keyTenantLine(ctx, scope, tenant);
+	const sources = scopeSources(ctx, scope);
+	const set = ctx.grantSet === true;
+	const rows = `  from (
+${sourceRows(sources)}
+  ) ms
+  cross join lateral jsonb_array_elements_text(
+    case jsonb_typeof(ms.roles) when 'array' then ms.roles else '[]'::jsonb end
+  ) r(role)`;
+	const declared = `  select (ms.id)::${type}${set ? ", rp.grant_key" : ""}
+${rows}
+  join ${qualified(ctx, "role_permissions")} rp on rp.role = r.role
+  where ${signedIn(ctx)}
+    and ms.scope = ${quoteLiteral(scope)}${set ? "" : "\n    and rp.grant_key = p_grant"}
+    and rp.scope = ${quoteLiteral(scope)}${andLine("    ", kindFilterSql(ctx, "r.role", "ms.via"))}${narrow}${sourceFilters(ctx, scope, subjectIdSql(ctx), grantPermissionSql(set ? "rp.grant_key" : "p_grant"), sourcesKeep(sources))}`;
+	const custom = ctx.customRoles;
+	if (custom === void 0) return sourcesBodyOf(declared, sources, subjectIdSql(ctx));
+	const match = [
+		customTenantMatch(ctx, `(${tenant})::text`, scope, "r.role"),
+		`c.scope = ${quoteLiteral(scope)}`,
+		"(c.scope_id is null or c.scope_id = (ms.id)::text)",
+		"c.role = r.role"
+	].join(" and ");
+	const entries = (source, value, extra) => `array(select c.${value} from ${qualified(ctx, source)} c where ${match}${extra})`;
+	if (set) return sourcesBodyOf(`${declared}
+  union
+  select (ms.id)::${type}, ck.grant_key
+${rows}
+${customKeysJoin(ctx, scope, entries(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'allow'"), entries(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'deny'"), entries(CUSTOM_ROLES.includes, "include_role", ""))}
+  where ${signedIn(ctx)}
+    and ms.scope = ${quoteLiteral(scope)}
+    and not (r.role = any(${sqlTextArray(custom.declared)}))${narrow}${sourceFilters(ctx, scope, subjectIdSql(ctx), grantPermissionSql("ck.grant_key"), sourcesKeep(sources))}`, sources, subjectIdSql(ctx));
+	return sourcesBodyOf(`${declared}
+  union
+  select (ms.id)::${type}
+${rows}
+  where ${signedIn(ctx)}
+    and ms.scope = ${quoteLiteral(scope)}
+    and not (r.role = any(${sqlTextArray(custom.declared)}))${narrow}${sourceFilters(ctx, scope, subjectIdSql(ctx), grantPermissionSql("p_grant"), sourcesKeep(sources))}
+${customKeysSql(ctx, scope, entries(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'allow'"), entries(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'deny'"), entries(CUSTOM_ROLES.includes, "include_role", ""))}`, sources, subjectIdSql(ctx));
 }
-function hasCustomRoleChecksFor(ctx) {
-	return ctx.authorize === "database" && ctx.customRoles !== void 0 && ctx.scopes.length > 0 && ctx.scopes.every((scope) => hasMemberFor(ctx, scope.name));
+function scopedBody(ctx, scope, type) {
+	if (ctx.authorize !== "database") return sqlBody(claimBody(ctx, scope, type));
+	return scopeSources(ctx, scope).length > 0 ? sourcesBody(ctx, scope, type) : sqlBody(tableBody(ctx, scope, type));
+}
+//#endregion
+//#region src/cli/rls/capabilities.ts
+/** The helper `--capabilities` adds: ids of one resource a link capability claim reaches. Part of the SQL contract. */
+const CAPABILITIES = { ids: "permdock_capability_ids" };
+/**
+* The `anon` branch access for a resource-scoped grant reached through a link
+* capability: the row's `field` holds an id the capability claim names for
+* `resource`, `role` and `permission`. Uncorrelated, so it runs once per
+* statement; the column is compared as text because the claim holds text.
+*/
+function capabilityAccessSql(ctx, field, resource, role, permission) {
+	const args = [
+		resource,
+		role,
+		permission
+	].map(quoteLiteral).join(", ");
+	return `${quoteIdent(field)}::text in (select ${qualified(ctx, CAPABILITIES.ids)}(${args}))`;
+}
+function capabilitiesSql(ctx) {
+	if (ctx.capabilities !== true) return "";
+	const fn = qualified(ctx, CAPABILITIES.ids);
+	return `-- link capabilities: the capability claim exchangeCapability mints (role anon, short-lived)
+create or replace function ${fn}(p_resource text, p_role text, p_permission text)
+returns setof text
+language sql
+stable
+set search_path = ''
+as $$
+  select c -> 'on' ->> 'id'
+  from (select ${subjectClaimJsonSql(ctx, "capability")} as c) capability
+  where jsonb_typeof(c) = 'object'
+    and c ->> 'v' = '1'
+    and c ->> 'holder' = 'link'
+    and c -> 'on' ->> 'resource' = p_resource
+    and jsonb_typeof(c -> 'roles') = 'array'
+    and c -> 'roles' @> jsonb_build_array(p_role)
+    and (c -> 'permissions' is null or c -> 'permissions' @> jsonb_build_array(p_permission))
+    and jsonb_typeof(c -> 'expires_at') = 'number'
+    and (c ->> 'expires_at')::numeric > extract(epoch from now())
+$$;
+revoke execute on function ${fn}(text, text, text) from public;
+grant execute on function ${fn}(text, text, text) to anon, authenticated;`;
 }
 //#endregion
 //#region src/cli/rls/custom-role-cascade.ts
@@ -1775,7 +1829,7 @@ function customRoleCascadeSql(ctx) {
 	const fn = qualified(ctx, CUSTOM_ROLES.cascade);
 	const target = quoteTable(qualifySqlTable(table.table));
 	const tenant = (row) => table.tenant === void 0 ? `null::${tenantType}` : `${rowColumn(row, table.tenant)}::${tenantType}`;
-	const scope = (row) => table.scope === void 0 ? `case when ${tenant(row)} is null then 'global' else ${quoteLiteral(root)} end` : `case when ${tenant(row)} is null then 'global' else ${rowColumn(row, table.scope)}::text end`;
+	const scope = (row) => rolesTableScope(table, tenant(row), root, (name) => rowColumn(row, name));
 	const id = (row) => table.id === void 0 ? "null::text" : `${rowColumn(row, table.id)}::text`;
 	const skipped = (row) => table.skip === void 0 ? "false" : `coalesce(${rowColumn(row, table.skip)}, false)`;
 	const guard = qualified(ctx, CUSTOM_ROLES.guard);
@@ -1909,7 +1963,7 @@ ${raiseSql("    ", "42501", `'permdock: the caller may not manage roles in ' ||
       )` : "";
 	const reachCte = leveled && reachRows !== "" ? `,
     reach (grant_key, level) as (values ${reachRows})` : "";
-	const match = `c.tenant_id is not distinct from p_tenant and c.scope = p_scope and c.scope_id is not distinct from p_scope_id`;
+	const match = `${storedTenant(ctx)} and c.scope = p_scope and c.scope_id is not distinct from p_scope_id`;
 	const memberOf = `p_tenant::text in ${members(root)}
       or ${perScope(ctx, (scope) => scope === root ? "false" : `p_scope_id in ${members(scope)}`)}`;
 	return {
@@ -1961,7 +2015,7 @@ begin
   perform ${shape}(p_tenant, p_scope, p_scope_id, p_role);
   if not (${signedIn(ctx, user)} and (
     ${platform}
-    or (p_scope <> 'global' and (${memberOf}))
+    or (p_scope <> 'global' and coalesce(${memberOf}, false))
   )) then
 ${raiseSql("    ", "42501", `'permdock: the caller is not a member of ' || coalesce(p_tenant::text, 'the platform')`, "not-member")}
   end if;${requires}
@@ -1989,8 +2043,9 @@ revoke execute on function ${guard}(${userArg}${tenantType}, text, text, text) f
 * \`assignablePermissions\`: entries inside the ceiling of the role's scope,
 * includes naming declared roles, and only permissions and levels the caller
 * may hand out, for the new definition and the stored one alike. A platform
-* custom role (\`p_scope = 'global'\`, no tenant) is written by a caller who
-* holds a \`meta.manageRoles\` permission through a global role. The
+* custom role (\`p_scope = 'global'\`, no tenant) and a shared custom role (no
+* tenant at a lower scope) are written by a caller who holds a
+* \`meta.manageRoles\` permission through a global role. The
 * \`permdock_trusted_*\` variants skip the caller checks and keep the
 * definition checks; no client role may execute them.
 */
@@ -2016,9 +2071,15 @@ function customRoleWritesSql(ctx, levelReach) {
 	const scopes = sqlTextArray(ctx.scopes.map((scope) => scope.name));
 	const roleName = (param) => `coalesce(${param}, '') = '' or ${param} = any(${sqlTextArray(custom.declared)})`;
 	const levelOf = leveled ? ", nullif(split_part(e, '@', 2), '')" : "";
-	const write = `  delete from ${perms} c where ${match} and c.role = p_role;
+	const levelColumn = leveled ? ", level" : "";
+	const sharedRole = qualified(ctx, CUSTOM_ROLES.shared);
+	const taken = (param) => `  if p_tenant is not null and ${sharedRole}(p_scope, ${param}) then
+${raiseSql("    ", "22023", `'permdock: ' || ${param} || ' is the name of a shared custom role'`, "name-taken")}
+  end if;
+`;
+	const write = `${taken("p_role")}  delete from ${perms} c where ${match} and c.role = p_role;
   delete from ${includes} c where ${match} and c.role = p_role;
-  insert into ${perms} (tenant_id, scope, scope_id, role, permission, effect${leveled ? ", level" : ""})
+  insert into ${perms} (tenant_id, scope, scope_id, role, permission, effect${levelColumn})
   select distinct p_tenant, p_scope, p_scope_id, p_role, ${current(leveled ? "split_part(e, '@', 1)" : "e")}, 'allow'${levelOf}
   from unnest(coalesce(p_allow, '{}'::text[])) e
   union
@@ -2027,7 +2088,7 @@ function customRoleWritesSql(ctx, levelReach) {
   insert into ${includes} (tenant_id, scope, scope_id, role, include_role)
   select distinct p_tenant, p_scope, p_scope_id, p_role, e
   from unnest(coalesce(p_include, '{}'::text[])) e;`;
-	const move = `  if ${roleName("p_to")} then
+	const move = `${taken("p_to")}  if ${roleName("p_to")} then
 ${raiseSql("    ", "22023", `'permdock: ' || coalesce(p_to, 'null') || ' is not a custom role name'`, "declared-role")}
   end if;
   if exists (select 1 from ${perms} c where ${match} and c.role = p_to)
@@ -2058,7 +2119,7 @@ grant execute on function ${qualified(ctx, name)}(${args}) to authenticated;` :
 	const removeParams = `p_tenant ${tenantType}, p_scope text, p_scope_id text, p_role text`;
 	return `${caller.beyond}
 
--- where a custom role may live: a scope of a tenant, or the platform (scope global, no tenant or instance), under an undeclared name
+-- where a custom role may live: a scope of a tenant, a scope of every tenant (shared: no tenant or instance), or the platform (scope global, no tenant or instance), under an undeclared name
 create or replace function ${shape}(p_tenant ${tenantType}, p_scope text, p_scope_id text, p_role text)
 returns void
 language plpgsql
@@ -2070,8 +2131,10 @@ begin
     if p_tenant is not null or p_scope_id is not null then
 ${raiseSql("      ", "22023", `'permdock: a platform custom role has no tenant or instance'`, "unknown-scope")}
     end if;
-  elsif p_tenant is null or not (p_scope = any(${scopes})) then
+  elsif not (p_scope = any(${scopes})) then
 ${raiseSql("    ", "22023", `'permdock: custom roles are held at a scope of a tenant or at global, not ' || coalesce(p_scope, 'null')`, "unknown-scope")}
+  elsif p_tenant is null and p_scope_id is not null then
+${raiseSql("    ", "22023", `'permdock: a shared custom role has no instance'`, "unknown-scope")}
   end if;
   if ${roleName("p_role")} then
 ${raiseSql("    ", "22023", `'permdock: ' || coalesce(p_role, 'null') || ' is not a custom role name'`, "declared-role")}
@@ -2217,7 +2280,7 @@ function globalRolesSql(ctx) {
 		const id = quoteIdent(through.id);
 		const key = quoteIdent(through.key);
 		const ref = quoteIdent(through.ref);
-		const global = source.tenant === void 0 ? "" : ` and k.${quoteIdent(source.tenant)} is null`;
+		const global = source.tenant === void 0 ? "" : ` and k.${quoteIdent(source.tenant)} is null${source.shared === void 0 ? "" : ` and k.${quoteIdent(source.shared)} is not true`}`;
 		body = `  select string_agg(w.r, ', ' order by w.r) into v_unknown
   from (${wanted}) w(r)
   where not exists (select 1 from ${keys} k where k.${key}::text = w.r${global});
@@ -2909,7 +2972,7 @@ function canAssignCustomSql(ctx, forUser = false) {
 	const guard = qualified(ctx, forUser ? CUSTOM_ROLES.guardFor : CUSTOM_ROLES.guard);
 	const userParam = forUser ? "p_user uuid, " : "";
 	const userArg = forUser ? "uuid, " : "";
-	const stored = `c.tenant_id is not distinct from p_tenant and c.scope = p_scope and c.role = p_role and (c.scope_id is null or c.scope_id = p_scope_id)`;
+	const stored = `${storedTenant(ctx)} and c.scope = p_scope and c.role = p_role and (c.scope_id is null or c.scope_id = p_scope_id)`;
 	const grants = forUser ? `revoke execute on function ${fn}(${userArg}${tenantType}, text, text, text) from public, anon, authenticated;` : `revoke execute on function ${fn}(${tenantType}, text, text, text) from public, anon;
 grant execute on function ${fn}(${tenantType}, text, text, text) to authenticated;`;
 	return `-- whether ${forUser ? "user p_user" : "the caller"} may assign custom role p_role at instance p_scope_id (a platform role: null tenant, scope global): the custom-role write checks on its stored definition${forUser ? "; no client role may execute it" : ""}
@@ -3631,4 +3694,4 @@ function ownershipSql(ctx) {
 	return chunks.length === 0 ? "" : `${chunks.join("\n\n")}\n`;
 }
 //#endregion
-export { checkSuspension as $, roleNames as A, linkHelper as B, API_KEY_ALLOWS as C, breakGlassHolder as D, apiKeysPlan as E, graphHelper as F, memberRoleOf as G, memberForSources as H, graphSqlName as I, restrictedHelper as J, permittedForHelper as K, graphSqlText as L, contextRefs as M, sqlFunctionNames as N, breakGlassKey as O, CLOSURE as P, activeUserSql as Q, hasMemberFor as R, byKey as S, apiKeyFields as T, memberForTable as U, memberForHelper as V, memberIdsHelper as W, scopeTable as X, scopeSources as Y, activeRowSql as Z, currentKeyExpr as _, guardedTables as a, globalRoleSource as b, PERMISSION_HELPERS as c, permissionKeysForHelper as d, permittedByPermissionHelper as f, seedSql as g, helpersSql as h, assignmentSql as i, compileConditionSql as j, collectGrants as k, checkName as l, accessSql as m, ownershipSql as n, ASSIGNMENTS as o, requiresSql as p, permittedIdsHelper as q, holderSources as r, OWNERSHIP as s, ownershipRules as t, permissionHelpersSql as u, capabilityAccessSql as v, apiKeyAllowsCall as w, byCodeUnit as x, globalRoleRows as y, hasPermittedUsers as z };
+export { activeUserSql as $, collectGrants as A, hasPermittedUsers as B, byKey as C, apiKeysPlan as D, apiKeyFields as E, CLOSURE as F, memberIdsHelper as G, memberForHelper as H, graphHelper as I, permittedIdsHelper as J, memberRoleOf as K, graphSqlName as L, compileConditionSql as M, contextRefs as N, breakGlassHolder as O, sqlFunctionNames as P, activeRowSql as Q, graphSqlText as R, byCodeUnit as S, apiKeyAllowsCall as T, memberForSources as U, linkHelper as V, memberForTable as W, scopeSources as X, restrictedHelper as Y, scopeTable as Z, capabilityAccessSql as _, guardedTables as a, currentKeyExpr as b, PERMISSION_HELPERS as c, permissionKeysForHelper as d, checkSuspension as et, permittedByPermissionHelper as f, seedSql as g, helpersSql as h, assignmentSql as i, roleNames as j, breakGlassKey as k, checkName as l, accessSql as m, ownershipSql as n, ASSIGNMENTS as o, requiresSql as p, permittedForHelper as q, holderSources as r, OWNERSHIP as s, ownershipRules as t, permissionHelpersSql as u, globalRoleRows as v, API_KEY_ALLOWS as w, rolesTableScope as x, globalRoleSource as y, hasMemberFor as z };