permdock 0.5.0 → 0.7.0

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

@@ -1,17 +1,19 @@
 import { a as sole, n as isReadonlyArray, r as isRecord } from "./compact-CAf557ZB.js";
 import { n as isForbiddenKey } from "./paths-DXSHAMIa.js";
-import { l as isSqlFunctionField } from "./refs-K6eWUJ0H.js";
+import { u as isSqlFunctionField } from "./refs-CNJBiTFo.js";
+import { c as listPermissions, h as formerKeys } from "./permission-registry-DpPtSKNZ.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 { f as scopeList, l as rootScope, s as resolveScope, u as scopeChain } from "./scopes-BHsc-wp-.js";
 import { t as isoInstant } from "./instant-BluqDvyS.js";
-import { m as findRole, v as listRoles } from "./grantee-Cn1HyUsI.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 { m as findRole, v as listRoles } from "./grantee-BrRANrpT.js";
+import { r as relationCondition, t as inheritCondition } from "./grantee-conditions-C6P1Tvol.js";
+import { l as partitionsOf, p as scopeField } from "./tenancy-CmeBQ6Nv.js";
+import { a as delegatedScopeMap } from "./permdock-BfWEeMqk.js";
+import { i as configError } from "./errors-DpP_U6Bf.js";
+import { d as sqlTextArray, i as qualifySqlTable, t as SQL_IDENT } from "./sql-B96movIM.js";
+import { i as scopeMembershipTable, o as relatedSql, r as scopeColumn } from "./compile-BAEO5bOk.js";
+import { d as keptKeys, l as roleColumn, u as roleManifest } from "./sources-B-zYB4GS.js";
+import { A as quoteQualified, D as qualified, E as helperSchema, F as scopeTypeOf, I as sqlType, L as tenantTypeOf, M as textArrayLiteral, O as quoteIdent, S as CLAIM, T as declaredArray, _ as subjectClaimJsonSql, b as tenantClaimSql, d as keyTenantSql, f as kindFilterSql, h as roleKindSql, i as allowEntry, j as quoteTable, k as quoteLiteral, 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, w as CLI, x as userIdHelperSql, y as subjectIdSql } from "./shared-fMKOv8hP.js";
 //#region src/cli/sql/active.ts
 function checkActiveRow(label, row) {
 	quoteTable(row.table);
@@ -699,6 +701,10 @@ function collectGrants(policy) {
 		};
 	});
 }
+/** The declared roles a custom role may draw grants from: the custom-role ceiling. */
+function assignableRoles(policy) {
+	return [...roleNames(policy)].toSorted().filter((name) => policy.rolesByName.get(name)?.assignable ?? listRoles(policy.vocabulary.roles).some((leaf) => leaf.key === name && leaf.assignable));
+}
 /** Declared role names (bindings and `defineRoles` leaves) plus any role a top-level grant names. */
 function roleNames(policy) {
 	const names = new Set(policy.roles.map((item) => item.name));
@@ -840,909 +846,1105 @@ 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)`;
+//#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 "";
+	const rp = qualified(ctx, "role_permissions");
+	const ceiling = qualified(ctx, CUSTOM_ROLES.ceiling);
+	const keys = qualified(ctx, CUSTOM_ROLES.keys);
+	const chunks = [];
+	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}
+);
+-- 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;`);
 		}
-		default: return ctx.dialect;
 	}
+	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 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)
+$$;
+revoke execute on function ${keys}(text[], text[], text[], text) from public, anon, authenticated;`);
+	if (shared !== "") chunks.push(shared);
+	return chunks.join("\n\n");
 }
-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)`;
+/** `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;`;
 }
-//#endregion
-//#region src/cli/rls/helper-bodies.ts
-function hasSetBody(ctx) {
+/**
+* `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 leveledKeysSql(ctx, renames) {
 	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 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}
+	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 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}
+  select i.grant_key from included i
+  where i.effect = 'deny' and i.scope = p_scope
   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}`;
+  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 hasBody(ctx) {
-	if (ctx.grantSet === true) return hasSetBody(ctx);
+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`;
+}
+/**
+* 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[]))`
+	};
+	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)`
+	};
+}
+/**
+* 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 active = userActive(ctx, "      ").map((line) => `\n${line}`).join("");
+	const reader = qualified(ctx, READERS.roles);
+	const tenantType = tenantTypeOf(ctx);
 	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 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 ${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 = [
-		`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}
-  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}
-  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)"))}`;
-}
-/**
-* 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 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 sourceUser(index) {
-	return `v_user_${String(index)}`;
-}
-function sqlBody(sql) {
-	return {
-		sql,
-		vars: []
-	};
-}
-function sourcesBodyOf(sql, sources, user) {
-	return {
-		sql,
-		vars: sources.map((source, index) => `${sourceUser(index)} ${source.sql.userType} := ${user};`)
-	};
-}
-/** `language sql`, or `plpgsql` returning the query when the body declares variables. */
-function functionBody(body) {
-	if (body.vars.length === 0) return `language sql
+	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 = `c.${allowEntry(ctx)}`;
+		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 ? "" : `\n${trustedReaderGrants(ctx, `${trusted}(${signature})`, trustedReaders)}`;
+	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.
+* The grants a `rls.trustedReaders` role needs for one reader: usage on the
+* helper schema, which no client role reaches through these lines, and
+* execute on the function.
 */
-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 trustedReaderGrants(ctx, fn, readers) {
+	const to = readers.map(quoteIdent).join(", ");
+	return `grant usage on schema ${quoteIdent(helperSchema(ctx))} to ${to};
+grant execute on function ${fn} to ${to};`;
 }
-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/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,
+		nullable: role.nullable,
+		role: roleManifest(role),
+		...role.through === void 0 ? {} : { through: role.through },
+		...tenant === void 0 ? {} : { tenant },
+		...shared === void 0 ? {} : { shared }
+	};
 }
 //#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 "";
-	const rp = qualified(ctx, "role_permissions");
-	const ceiling = qualified(ctx, CUSTOM_ROLES.ceiling);
-	const keys = qualified(ctx, CUSTOM_ROLES.keys);
-	const chunks = [];
-	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;`);
-		}
+//#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);
 	}
-	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");
+	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;
 	}
-	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")})
+}
+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("");
+	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 i.grant_key from included i
-  where i.effect = 'deny' and i.scope = p_scope
+  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 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 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}`;
 }
-/**
-* `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 leveledKeysSql(ctx, renames) {
+function hasBody(ctx) {
+	if (ctx.grantSet === true) return hasSetBody(ctx);
 	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
+	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 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 c.grant_key from ceiling c
-  where c.permission in (select a.permission from allowed a)
+  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
-  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 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`;
+  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)"))}`;
 }
 /**
-* 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.
+* 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 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 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 sourceUser(index) {
+	return `v_user_${String(index)}`;
+}
+function sqlBody(sql) {
+	return {
+		sql,
+		vars: []
 	};
+}
+function sourcesBodyOf(sql, sources, user) {
 	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: 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
+/** `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 $$
-  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)
+${body.sql}
+$$;`;
+	return `language plpgsql
+stable
+security definer
+set search_path = ''
+as $$
+declare
+${body.vars.map((line) => `  ${line}`).join("\n")}
+begin
+  return query
+${body.sql};
+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)}`;
+}
+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 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, allowEntry(ctx), " 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, allowEntry(ctx), " and c.effect = 'allow'"), entries(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'deny'"), entries(CUSTOM_ROLES.includes, "include_role", ""))}`, sources, subjectIdSql(ctx));
+}
+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
-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
+  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 ${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;
+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-by-id.ts
+const PREFIX = "PermDock CLI";
+const col = (name) => `r.${quoteIdent(name)}`;
+/**
+* Custom-role functions keyed by the application's role row
+* (`rls.customRoleWrites.roles.primaryKey`): the tenant, scope, instance and
+* name come from the row, never from the caller. The writers delegate to
+* `permdock_replace_custom_role_grants` (or its trusted variant), so every
+* caller and definition check applies, and keep the stored denies and
+* includes. The reader returns declared allow keys only and is executable by
+* `rls.trustedReaders` alone.
+*/
+function customRoleByIdSql(ctx, trustedReaders) {
+	const custom = ctx.customRoles;
+	const roles = custom?.table;
+	const root = ctx.scopes[0]?.name;
+	if (custom === void 0 || roles?.primaryKey === void 0 || ctx.authorize !== "database" || root === void 0) return "";
+	const pk = roles.primaryKey;
+	if (pk === "") throw configError(`${PREFIX}: rls.customRoleWrites.roles.primaryKey names no column`);
+	const leveled = custom.levels === true;
+	const tenantType = tenantTypeOf(ctx);
+	const table = quoteQualified(roles.table);
+	const idType = `${table}.${quoteIdent(pk)}%type`;
+	const perms = qualified(ctx, CUSTOM_ROLES.permissions);
+	const includes = qualified(ctx, CUSTOM_ROLES.includes);
+	const replace = qualified(ctx, CUSTOM_ROLES.replace);
+	const trustedReplace = qualified(ctx, CUSTOM_ROLES.trustedReplace);
+	const byId = qualified(ctx, CUSTOM_ROLES.replaceById);
+	const trustedById = qualified(ctx, CUSTOM_ROLES.trustedReplaceById);
+	const reader = qualified(ctx, CUSTOM_ROLES.trustedReadById);
+	const renames = Object.entries(custom.renamed ?? {}).toSorted(byKey);
+	const current = (expr) => currentKeyExpr(renames, expr);
+	const declaredKeys = sqlTextArray(custom.permissions ?? []);
+	const declaredRoles = sqlTextArray(custom.declared);
+	const tenant = roles.tenant === void 0 ? `null::${tenantType}` : `${col(roles.tenant)}::${tenantType}`;
+	const scope = rolesTableScope(roles, tenant, root, col);
+	const scopeId = roles.id === void 0 || roles.tenant === void 0 ? "null::text" : `case when ${tenant} is null then null else ${col(roles.id)}::text end`;
+	const skipped = roles.skip === void 0 || roles.tenant === void 0 ? "false" : `(${tenant} is not null and coalesce(${col(roles.skip)}, false))`;
+	const match = "c.tenant_id is not distinct from v_tenant and c.scope = v_scope and c.scope_id is not distinct from v_scope_id and c.role = v_key";
+	const audit = custom.audit;
+	const auditCall = audit === void 0 ? "" : `
+  perform ${quoteQualified(audit.function)}(${[
+		"event_type => 'permdock.custom_role.replaced'",
+		"target_type => 'role'",
+		"record_id => p_role_id::text",
+		"tenant => v_tenant",
+		"metadata => jsonb_build_object('operation', 'replace', 'role', v_key, 'permissions', p_permissions)",
+		...Object.entries(audit.args ?? {}).toSorted(byKey).map(([name, value]) => `${quoteIdent(name)} => ${quoteLiteral(value)}`)
+	].join(", ")});`;
+	const body = (write) => `declare
+  v_tenant ${tenantType};
+  v_scope text;
+  v_scope_id text;
+  v_key text;
+  v_skipped boolean;
+  v_deny text[];
+  v_include text[];
+begin
+  select ${tenant}, ${scope}, ${scopeId}, ${col(roles.key)}::text, ${skipped}
+  into v_tenant, v_scope, v_scope_id, v_key, v_skipped
+  from ${table} r
+  where ${col(pk)} = p_role_id;
+  if not found then
+${raiseSql("    ", "P0002", "'permdock: no role row has id ' || coalesce(p_role_id::text, 'null')", "unknown-role")}
   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;
+  if v_skipped or v_key = any(${declaredRoles}) then
+${raiseSql("    ", "22023", "'permdock: ' || coalesce(v_key, 'null') || ' is a declared role, not a custom role'", "declared-role")}
+  end if;
+  select array_agg(c.permission) into v_deny
+  from ${perms} c
+  where ${match} and c.effect = 'deny';
+  select array_agg(c.include_role) into v_include
+  from ${includes} c
+  where ${match};
+  perform ${write}(v_tenant, v_scope, v_scope_id, v_key, p_permissions, v_deny, v_include);${auditCall}
 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)
+	const writer = (comment, name, write, member) => `-- ${comment}
+create or replace function ${name}(p_role_id ${idType}, p_permissions text[])
+returns void
 language plpgsql
-stable
+volatile
 security definer
 set search_path = ''
 as $$
-${body}
+${body(write)}
 $$;
-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)
+${member ? `revoke execute on function ${name}(${idType}, text[]) from public, anon;
+grant execute on function ${name}(${idType}, text[]) to authenticated;` : `revoke execute on function ${name}(${idType}, text[]) from public, anon, authenticated;`}`;
+	const readerEntry = leveled ? `${current("c.permission")} || coalesce('@' || c.level, '')` : current("c.permission");
+	const readerGrant = trustedReaders === void 0 || trustedReaders.length === 0 ? "" : `\n${trustedReaderGrants(ctx, `${reader}(text[], ${tenantType})`, trustedReaders)}`;
+	return `${writer("save a custom role by its row id: the row supplies tenant, scope, instance and name; the caller checks of permdock_replace_custom_role_grants apply, and stored denies and includes stay", byId, replace, true)}
+
+${writer("save a custom role by its row id for a trusted caller: the definition checks without the caller checks", trustedById, trustedReplace, false)}
+
+-- the declared allow keys of custom roles by their row ids as text, for a trusted reader; with p_tenant, an id of another tenant is refused
+create or replace function ${reader}(p_role_ids text[], p_tenant ${tenantType} default null)
+returns table (role_id text, permission text)
 language plpgsql
 stable
 security definer
 set search_path = ''
 as $$
-${trustedBody}
+begin
+  if p_tenant is not null and exists (
+    select 1 from ${table} r
+    where ${col(pk)}::text = any(p_role_ids) and ${tenant} is distinct from p_tenant
+  ) then
+${raiseSql("    ", "42501", "'permdock: a role id belongs to another tenant than ' || p_tenant::text", "not-member")}
+  end if;
+  return query
+  select distinct v.role_id, ${readerEntry}
+  from (
+    select ${col(pk)}::text as role_id, ${tenant} as tenant_id, ${scope} as scope, ${scopeId} as scope_id, ${col(roles.key)}::text as role
+    from ${table} r
+    where ${col(pk)}::text = any(p_role_ids)
+      and not ${skipped}
+      and not (${col(roles.key)}::text = any(${declaredRoles}))
+  ) v
+  join ${perms} c
+    on c.tenant_id is not distinct from v.tenant_id
+    and c.scope = v.scope
+    and c.scope_id is not distinct from v.scope_id
+    and c.role = v.role
+  where c.effect = 'allow'
+    and ${current("c.permission")} = any(${declaredKeys})
+  order by 1, 2;
+end;
 $$;
-revoke execute on function ${trusted}(${signature}) from public, anon, authenticated;${grants}`);
-	return chunks.join("\n\n");
-}
-/** `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)`;
-}
-/** `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));
+revoke execute on function ${reader}(text[], ${tenantType}) from public, anon, authenticated;${readerGrant}`;
 }
 //#endregion
 //#region src/cli/rls/custom-role-cascade.ts
@@ -1775,12 +1977,12 @@ 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 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 scope = (row) => rolesTableScope(table, tenant(row), root, (name) => rowColumn(row, name));
+	const id = (row) => table.id === void 0 || table.tenant === void 0 ? "null::text" : `case when ${tenant(row)} is null then null else ${rowColumn(row, table.id)}::text end`;
+	const skipped = (row) => table.skip === void 0 || table.tenant === void 0 ? "false" : `(${tenant(row)} is not null and coalesce(${rowColumn(row, table.skip)}, false))`;
 	const guard = qualified(ctx, CUSTOM_ROLES.guard);
 	const entries = qualified(ctx, CUSTOM_ROLES.entries);
-	const allowEntryOf = custom.levels === true ? "c.permission || coalesce('@' || c.level, '')" : "c.permission";
+	const allowEntryOf = `c.${allowEntry(ctx)}`;
 	return `-- the application's roles table: renames, moves and deletes of a custom role carry its grants and includes
 create or replace function ${fn}()
 returns trigger
@@ -1859,6 +2061,58 @@ create trigger "permdock_custom_role_cascade"
 `;
 }
 //#endregion
+//#region src/cli/rls/custom-role-guard.ts
+/** A column of the roles-table row a trigger sees as `new`. */
+function column(name) {
+	return `new.${quoteIdent(name)}`;
+}
+/**
+* The trigger on the application's roles table (`rls.customRoleWrites.roles`)
+* that refuses a tenant row named like a declared role (`declared-role`) or
+* like a shared custom role (`name-taken`). A row the `skip` column marks is
+* a system role of the tenant and passes. Empty without a tenant column: then
+* no row is a tenant row.
+*/
+function customRoleNameGuardSql(ctx) {
+	const custom = ctx.customRoles;
+	const table = custom?.table;
+	const root = ctx.scopes[0]?.name;
+	if (custom === void 0 || table?.tenant === void 0 || root === void 0) return "";
+	const tenant = `${column(table.tenant)}::${tenantTypeOf(ctx)}`;
+	const skipped = table.skip === void 0 ? "false" : `coalesce(${column(table.skip)}, false)`;
+	const fn = qualified(ctx, CUSTOM_ROLES.nameGuard);
+	const target = quoteTable(qualifySqlTable(table.table));
+	const key = `${column(table.key)}::text`;
+	const scope = rolesTableScope(table, tenant, root, column);
+	return `-- the application's roles table: a tenant row cannot take the name of a declared or a shared role
+create or replace function ${fn}()
+returns trigger
+language plpgsql
+volatile
+security definer
+set search_path = ''
+as $$
+begin
+  if ${tenant} is null or ${skipped} then
+    return new;
+  end if;
+  if ${key} = any(${sqlTextArray(custom.declared)}) then
+${raiseSql("    ", "22023", `'permdock: ' || ${key} || ' is a declared role'`, "declared-role")}
+  end if;
+  if ${qualified(ctx, CUSTOM_ROLES.shared)}(${scope}, ${key}) then
+${raiseSql("    ", "22023", `'permdock: ' || ${key} || ' is a shared role'`, "name-taken")}
+  end if;
+  return new;
+end;
+$$;
+revoke execute on function ${fn}() from public, anon, authenticated;
+drop trigger if exists "permdock_custom_role_name_guard" on ${target};
+create trigger "permdock_custom_role_name_guard"
+  before insert or update on ${target}
+  for each row execute function ${fn}();
+`;
+}
+//#endregion
 //#region src/cli/rls/custom-role-writes.ts
 function callerFunctionsSql(ctx, custom, root, levelReach, forUser) {
 	const leveled = custom.levels === true;
@@ -1909,7 +2163,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 +2215,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 +2243,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.
 */
@@ -2008,6 +2263,7 @@ function customRoleWritesSql(ctx, levelReach) {
 	const guard = qualified(ctx, CUSTOM_ROLES.guard);
 	const shape = qualified(ctx, CUSTOM_ROLES.shape);
 	const entries = qualified(ctx, CUSTOM_ROLES.entries);
+	const problem = qualified(ctx, CUSTOM_ROLES.entryProblem);
 	const renames = Object.entries(custom.renamed ?? {}).toSorted(byKey);
 	const current = (expr) => currentKeyExpr(renames, expr);
 	const known = sqlTextArray([...custom.permissions ?? [], ...renames.map(([former]) => former)]);
@@ -2016,9 +2272,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 +2289,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 +2320,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 +2332,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")}
@@ -2087,6 +2351,38 @@ ${callerFunctionsSql(ctx, custom, root, levelReach, true).beyond}
 
 ${callerFunctionsSql(ctx, custom, root, levelReach, true).guard}
 ` : ""}
+-- null when an allow entry is a declared permission inside the ceiling of the scope${leveled ? ", at a level the resource declares" : ""}; else unknown-permission, outside-ceiling${leveled ? " or unknown-level" : ""}
+create or replace function ${problem}(p_scope text, p_entry text)
+returns text
+language plpgsql
+stable
+security definer
+set search_path = ''
+as $$
+declare
+  v_key text := ${current(leveled ? "split_part(p_entry, '@', 1)" : "p_entry")};
+begin
+  if p_entry is null or not (v_key = any(${known})) then
+    return 'unknown-permission';
+  end if;
+  if not exists (
+    select 1 from ${ceiling} c
+    where c.scope = p_scope and c.effect = 'allow' and ${current("c.permission")} = v_key
+  ) then
+    return 'outside-ceiling';
+  end if;${leveled ? `
+  if strpos(p_entry, '@') > 0 and not exists (
+    select 1 from ${ceiling} c
+    where c.scope = p_scope and c.effect = 'allow' and ${current("c.permission")} = v_key
+      and split_part(c.grant_key, '@', 2) = split_part(p_entry, '@', 2)
+  ) then
+    return 'unknown-level';
+  end if;` : ""}
+  return null;
+end;
+$$;
+revoke execute on function ${problem}(text, text) from public, anon, authenticated;
+
 -- the entries of a definition: declared keys and levels inside the ceiling of the scope, and declared includes
 create or replace function ${entries}(p_scope text, p_allow text[], p_deny text[], p_include text[])
 returns void
@@ -2098,23 +2394,18 @@ as $$
 declare
   v_entry text;
   v_key text;
+  v_problem text;
 begin
   foreach v_entry in array coalesce(p_allow, '{}'::text[]) loop
     v_key := ${current(leveled ? "split_part(v_entry, '@', 1)" : "v_entry")};
-    if not (v_key = any(${known})) then
+    v_problem := ${problem}(p_scope, v_entry);
+    if v_problem = 'unknown-permission' then
 ${raiseSql("      ", "22023", `'permdock: ' || v_entry || ' is not a declared permission'`, "unknown-permission")}
     end if;
-    if not exists (
-      select 1 from ${ceiling} c
-      where c.scope = p_scope and c.effect = 'allow' and ${current("c.permission")} = v_key
-    ) then
+    if v_problem = 'outside-ceiling' then
 ${raiseSql("      ", "22023", `'permdock: ' || v_key || ' is outside the ceiling of ' || p_scope`, "outside-ceiling")}
     end if;${leveled ? `
-    if strpos(v_entry, '@') > 0 and not exists (
-      select 1 from ${ceiling} c
-      where c.scope = p_scope and c.effect = 'allow' and ${current("c.permission")} = v_key
-        and split_part(c.grant_key, '@', 2) = split_part(v_entry, '@', 2)
-    ) then
+    if v_problem = 'unknown-level' then
 ${raiseSql("      ", "22023", `'permdock: ' || v_entry || ' names a level the resource does not declare'`, "unknown-level")}
     end if;` : ""}
   end loop;
@@ -2217,7 +2508,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});
@@ -2375,17 +2666,103 @@ ${functionBody(memberRowsBody(ctx, scope, type, "p_user", memberForSources(ctx,
 revoke execute on function ${fn}(uuid) from public, anon, authenticated;`;
 }
 //#endregion
+//#region src/cli/rls/token-scopes.ts
+const TOKEN_SCOPE_ALLOWS = "permdock_token_scope_allows";
+/** `rls.tokenScopes` as the SQL generator needs it, or `undefined` when it is off. */
+function tokenScopesPlan(setting, policy) {
+	if (setting !== true) return;
+	const permissions = listPermissions(policy.permissions).map((leaf) => ({
+		key: leaf.key,
+		scope: leaf.scope,
+		renamedFrom: formerKeys(leaf)
+	}));
+	return { scopes: delegatedScopeMap(permissions, policy.oauthScopes) };
+}
+function tokenScopeAllowsCall(ctx, grant) {
+	return `${qualified(ctx, TOKEN_SCOPE_ALLOWS)}(${grant})`;
+}
+/** The token's scopes as rows of `s(scope)`: a space-separated string or, outside `guc`, a JSON array. */
+function tokenScopeRows(ctx) {
+	if (ctx.dialect === "guc") return `regexp_split_to_table(btrim(coalesce(${subjectClaimSql(ctx, "scope")}, '')), '\\s+') s(scope)`;
+	const scope = subjectClaimJsonSql(ctx, "scope");
+	return `unnest(case jsonb_typeof(${scope})
+      when 'string' then regexp_split_to_array(btrim(${scope} #>> '{}'), '\\s+')
+      when 'array' then array(select jsonb_array_elements_text(${scope}))
+      else '{}'::text[]
+    end) s(scope)`;
+}
+/**
+* `permdock_token_scope_allows(p_grant)`: a delegated token (a `client_id`, or
+* an `act` that is not a support or impersonation session) reaches a grant key
+* only when one of its scopes maps to the key's permission. better-supabase's
+* `cap_allows` reads the same tokens the same way.
+*/
+function tokenScopeAllowsSql(ctx, plan, anonExecute) {
+	const fn = qualified(ctx, TOKEN_SCOPE_ALLOWS);
+	const act = subjectClaimJsonSql(ctx, "act");
+	const grants = anonExecute ? `revoke execute on function ${fn}(text) from public;
+grant execute on function ${fn}(text) to anon, authenticated;` : `revoke execute on function ${fn}(text) from public, anon;
+grant execute on function ${fn}(text) to authenticated;`;
+	return `-- Token scopes: a delegated token holds only the permissions its scope claim maps to; denies always apply, and a token without client_id or an agent act is not limited
+create or replace function ${fn}(p_grant text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select case
+    when coalesce(${subjectClaimSql(ctx, "client_id")}, '') = ''
+      and (${act} is null
+        or ${act} = 'null'::jsonb
+        or (jsonb_typeof(${act}) = 'object'
+          and ${act} ->> 'kind' in ('support', 'impersonation'))) then true
+    when exists (
+      select 1 from ${qualified(ctx, "role_permissions")} rp
+      where rp.grant_key = p_grant and rp.effect = 'deny'
+    ) then true
+    else exists (
+      select 1
+      from ${tokenScopeRows(ctx)}
+      where s.scope <> ''
+        and coalesce(${quoteLiteral(JSON.stringify(plan.scopes))}::jsonb -> s.scope, '[]'::jsonb)
+          ? split_part(split_part(p_grant, '#', 1), '@', 1)
+    )
+  end
+$$;
+${grants}`;
+}
+//#endregion
 //#region src/cli/rls/helpers.ts
 /**
 * The policy-side call for a grant key. Every form is uncorrelated, so
 * Postgres runs the helper once per statement (an InitPlan, or a hashed
 * SubPlan for `in`), never once per row.
 */
-function accessSql(ctx, scope, grantKey, column) {
+function accessSql(ctx, scope, grantKey, column, helper) {
 	const key = quoteLiteral(grantKey);
 	if (scope === "global") return `(select ${qualified(ctx, HELPERS.has)}(${key}))`;
 	if (column === void 0) throw configError(`PermDock CLI: ${scope}-scoped grant needs definePolicy({ scopes.${scope} })`);
-	return `${quoteIdent(column)} in (select ${qualified(ctx, permittedIdsHelper(scope))}(${key}))`;
+	return `${quoteIdent(column)} in (select ${qualified(ctx, helper ?? permittedIdsHelper(scope))}(${key}))`;
+}
+/**
+* `permitted_<parent>_ids(p_grant)` for each \`rls.tables\` \`via\`: the parent
+* rows whose scope instance the grant reaches. \`security definer\`, so the
+* caller needs no read on the parent, and called uncorrelated like
+* \`permitted_<scope>_ids\`.
+*/
+function viaHelpersSql(ctx, anonExecute) {
+	const done = /* @__PURE__ */ new Set();
+	const chunks = [];
+	for (const via of Object.values(ctx.vias ?? {})) {
+		if (done.has(via.helper)) continue;
+		done.add(via.helper);
+		chunks.push(`-- rows of ${via.table} whose ${via.column} is a ${via.scope} the grant reaches
+${helperFunction(ctx, via.helper, `setof ${via.type}`, sqlBody(`  select p.${quoteIdent(via.id)}
+  from ${quoteQualified(via.table)} p
+  where p.${quoteIdent(via.column)} in (select ${qualified(ctx, permittedIdsHelper(via.scope))}(p_grant))`), anonExecute)}`);
+	}
+	return chunks;
 }
 function userIdSql(ctx, anonExecute) {
 	const fn = userIdHelperSql(ctx);
@@ -2473,6 +2850,40 @@ ${rows.map((row) => `  (${[
 );`;
 }
 /**
+* `role_permissions` as a view over the compiled rows (`rls.seeds: 'view'`).
+* `security_invoker` makes the view read as its caller, so it adds no
+* privilege; the table's revoke applies to the view the same way.
+*/
+function seedViewSql(ctx, rows) {
+	const view = qualified(ctx, "role_permissions");
+	const columns = "role, permission, grant_key, scope, effect";
+	return `-- rls.seeds: 'view': role_permissions is a view, so the rows travel with the schema
+create or replace view ${view} (${columns}) with (security_invoker = true) as
+${rows.length === 0 ? `select null::text, null::text, null::text, null::text, null::text where false` : `select * from (values\n${rows.map((row) => `  (${[
+		row.role,
+		row.permission,
+		row.grantKey,
+		row.scope,
+		row.effect
+	].map(quoteLiteral).join(", ")})`).join(",\n")}\n) as v(${columns})`};
+revoke all on table ${view} from anon, authenticated, public;`;
+}
+/** `<schema>.seed()`: the same upsert and delete as `seedSql`, for a declarative schema that carries no rows. */
+function seedFunctionSql(ctx, rows) {
+	const fn = qualified(ctx, "seed");
+	return `-- rls.seeds: 'function': the role_permissions rows are data, so a declarative diff leaves them out; run select ${fn}(); after each deploy
+create or replace function ${fn}()
+returns void
+language sql
+volatile
+security definer
+set search_path = ''
+as $permdock$
+${seedSql(ctx, rows)}
+$permdock$;
+revoke execute on function ${fn}() from public, anon, authenticated;`;
+}
+/**
 * `role_permissions`, its seeds, and the three `security definer` helpers
 * with `search_path = ''`. `execute` goes to `authenticated` only.
 */
@@ -2482,9 +2893,13 @@ function helpersSql(ctx, rows, options) {
 	const rp = qualified(ctx, "role_permissions");
 	const chunks = [`-- permdock helpers (${ctx.authorize === "database" ? "database: reads the membership and user_roles tables" : "jwt: reads the role and memberships claims"})
 -- policies call them uncorrelated, so Postgres evaluates each once per statement`];
-	if (schema !== "public") chunks.push(`create schema if not exists ${s};\nrevoke all on schema ${s} from public;\ngrant usage on schema ${s} to ${options.anonExecute === true ? "anon, authenticated" : "authenticated"};`);
+	if (schema !== "public") {
+		const anonUsage = options.anonExecute === true || ctx.capabilities === true;
+		chunks.push(`create schema if not exists ${s};\nrevoke all on schema ${s} from public;\ngrant usage on schema ${s} to ${anonUsage ? "anon, authenticated" : "authenticated"};`);
+	}
 	if (ctx.dialect === "supabase") chunks.push(userIdSql(ctx, options.anonExecute === true));
-	chunks.push(`create table if not exists ${rp} (
+	if (ctx.seeds === "view") chunks.push(seedViewSql(ctx, rows));
+	else chunks.push(`create table if not exists ${rp} (
   role text not null,
   permission text not null,
   grant_key text not null,
@@ -2494,7 +2909,8 @@ function helpersSql(ctx, rows, options) {
 );
 alter table ${rp} enable row level security;
 revoke all on table ${rp} from anon, authenticated, public;`);
-	if (options.withoutSeeds !== true) chunks.push(seedSql(ctx, rows));
+	if (ctx.seeds === "function") chunks.push(seedFunctionSql(ctx, rows));
+	else if (options.withoutSeeds !== true && ctx.seeds !== "view") chunks.push(seedSql(ctx, rows));
 	if (ctx.authorize === "database" && options.userRoles && ctx.roles === void 0) {
 		const ur = qualified(ctx, "user_roles");
 		chunks.push(`create table if not exists ${ur} (
@@ -2510,6 +2926,7 @@ revoke all on table ${ur} from anon, authenticated, public;`);
 	const anon = options.anonExecute === true;
 	const keys = ctx.apiKeys;
 	if (keys !== void 0) chunks.push(apiKeyAllowsSql(ctx, keys, anon));
+	if (ctx.tokenScopes !== void 0) chunks.push(tokenScopeAllowsSql(ctx, ctx.tokenScopes, anon));
 	const bodies = grantBodies(ctx);
 	chunks.push(helperFunction(ctx, HELPERS.has, "boolean", bodies.has, anon));
 	const capabilities = capabilitiesSql(ctx);
@@ -2521,6 +2938,7 @@ revoke all on table ${ur} from anon, authenticated, public;`);
 		if (ctx.roleMemberScopes?.includes(scope.name) === true) chunks.push(memberRolesFunction(ctx, scope.name, type, anon));
 		if (hasMemberFor(ctx, scope.name)) chunks.push(memberForFunction(ctx, scope.name, type));
 	}
+	chunks.push(...viaHelpersSql(ctx, anon));
 	const forUser = forUserSql(ctx);
 	if (forUser !== "") chunks.push(forUser);
 	const writes = customRoleWritesSql(ctx, options.levelReach ?? []);
@@ -2528,6 +2946,12 @@ revoke all on table ${ur} from anon, authenticated, public;`);
 		chunks.push(writes);
 		const cascade = customRoleCascadeSql(ctx);
 		if (cascade !== "") chunks.push(cascade);
+		const sync = ctx.customRoles?.sync;
+		if (sync !== void 0) chunks.push(sync);
+		const byId = customRoleByIdSql(ctx, options.trustedReaders);
+		if (byId !== "") chunks.push(byId);
+		const nameGuard = customRoleNameGuardSql(ctx);
+		if (nameGuard !== "") chunks.push(nameGuard);
 	}
 	const globalRoles = globalRolesSql(ctx);
 	if (globalRoles !== "") chunks.push(globalRoles);
@@ -2537,20 +2961,26 @@ revoke all on table ${ur} from anon, authenticated, public;`);
 }
 function grantBodies(ctx) {
 	const keys = ctx.apiKeys;
+	const scoped = ctx.tokenScopes !== void 0;
 	const set = ctx.grantSet === true;
-	const allows = apiKeyAllowsCall(ctx, set ? "ids.grant_key" : "p_grant");
-	const keyTenant = keyTenantSql(ctx, void 0) ?? "true";
+	const ceiling = (grant) => {
+		const calls = [...keys === void 0 ? [] : [apiKeyAllowsCall(ctx, grant)], ...scoped ? [tokenScopeAllowsCall(ctx, grant)] : []];
+		return calls.length === 0 ? void 0 : calls.join(" and ");
+	};
+	const allows = ceiling(set ? "ids.grant_key" : "p_grant");
+	const keyTenant = keys === void 0 ? "" : ` and ${keyTenantSql(ctx, void 0) ?? "true"}`;
+	const hasAllows = ceiling(set ? "g.grant_key" : "p_grant");
 	return {
-		has: sqlBody(keys === void 0 ? hasBody(ctx) : set ? `  select g.grant_key
+		has: sqlBody(hasAllows === void 0 ? hasBody(ctx) : set ? `  select g.grant_key
   from (
 ${hasBody(ctx)}
   ) g(grant_key)
-  where ${apiKeyAllowsCall(ctx, "g.grant_key")} and ${keyTenant}` : ceilingHasSql(hasBody(ctx), `${allows} and ${keyTenant}`)),
+  where ${hasAllows}${keyTenant}` : ceilingHasSql(hasBody(ctx), `${hasAllows}${keyTenant}`)),
 		ids: (scope) => {
 			const type = scopeTypeOf(ctx, scope);
 			const body = scopedBody(ctx, scope, type);
-			if (keys === void 0) return body;
-			const sql = scope === rootName(ctx) ? `${body.sql}\n  union\n${serviceKeyIdsSql(ctx, keys, scope, type)}` : body.sql;
+			if (allows === void 0) return body;
+			const sql = keys !== void 0 && scope === rootName(ctx) ? `${body.sql}\n  union\n${serviceKeyIdsSql(ctx, keys, scope, type)}` : body.sql;
 			return {
 				sql: set ? `  select ids.id, ids.grant_key
   from (
@@ -2563,7 +2993,7 @@ ${sql}
 	};
 }
 function forUserContext(ctx) {
-	const { apiKeys: _apiKeys, ...unkeyed } = ctx;
+	const { apiKeys: _apiKeys, tokenScopes: _tokenScopes, ...unkeyed } = ctx;
 	return {
 		...unkeyed,
 		subjectId: "p_user",
@@ -2909,7 +3339,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" : ""}
@@ -3586,6 +4016,42 @@ function ownershipRules(policy, scopes) {
 	};
 }
 /**
+* The roles whose `for` lists kinds that no membership source of the role's
+* scope can hold: such a role resolves to no one. A `via` read from a column
+* can hold any kind, and so does a source with no `via` (it is not
+* compared) and a scope with no table or source.
+*/
+function unsatisfiedKinds(ctx, policy) {
+	const out = [];
+	for (const [role, kinds] of Object.entries(ctx.ownership?.kinds ?? {})) {
+		const scope = roleScope(policy, ctx.scopes, role);
+		if (scope === void 0) continue;
+		const held = [];
+		const mapped = scopeTable(ctx, scope)?.table;
+		if (mapped !== void 0) {
+			const via = memberVia(mapped);
+			held.push({
+				label: mapped.table,
+				via: typeof via === "string" ? void 0 : via.value ?? void 0
+			});
+		} else for (const source of ctx.memberSources ?? ctx.sources ?? []) {
+			if (source.sql.scope !== void 0 && source.sql.scope !== scope) continue;
+			const via = source.sql.manifest.via;
+			held.push({
+				label: source.sql.table,
+				via: via === void 0 ? void 0 : "value" in via && typeof via.value === "string" ? via.value : void 0
+			});
+		}
+		if (held.length === 0 || held.some((entry) => entry.via === void 0 || kinds.includes(entry.via ?? ""))) continue;
+		out.push({
+			role,
+			for: kinds,
+			sources: held.map((entry) => `${entry.label} (via ${entry.via ?? ""})`)
+		});
+	}
+	return out;
+}
+/**
 * The ownership objects: holder-count and transfer-only triggers on each
 * scope's membership table, and `permdock_can_assign` for the application's
 * own policies on those tables. Empty when no role declares a rule.
@@ -3631,4 +4097,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 { permittedForHelper as $, apiKeyFields as A, sqlFunctionNames as B, globalRoleSource as C, byKey as D, byCodeUnit as E, collectGrants as F, hasMemberFor as G, graphHelper as H, roleNames as I, memberForHelper as J, hasPermittedUsers as K, andConditions as L, assignableRoles as M, breakGlassHolder as N, API_KEY_ALLOWS as O, breakGlassKey as P, memberRoleOf as Q, compileConditionSql as R, globalRoleRows as S, rolesTableScope as T, graphSqlName as U, CLOSURE as V, graphSqlText as W, memberForTable as X, memberForSources as Y, memberIdsHelper as Z, seedSql as _, assignmentSql as a, activeUserSql as at, tokenScopesPlan as b, OWNERSHIP as c, permissionHelpersSql as d, permittedIdsHelper as et, permissionKeysForHelper as f, helpersSql as g, accessSql as h, holderSources as i, activeRowSql as it, apiKeysPlan as j, apiKeyAllowsCall as k, PERMISSION_HELPERS as l, requiresSql as m, ownershipSql as n, scopeSources as nt, guardedTables as o, checkSuspension as ot, permittedByPermissionHelper as p, linkHelper as q, unsatisfiedKinds as r, scopeTable as rt, ASSIGNMENTS as s, ownershipRules as t, restrictedHelper as tt, checkName as u, TOKEN_SCOPE_ALLOWS as v, currentKeyExpr as w, capabilityAccessSql as x, tokenScopeAllowsCall as y, contextRefs as z };