permdock 0.4.0 → 0.6.0

package/dist/{permission-keys-B26jeyUv.js → ownership-DqaJNJPn.js}

@@ -1,79 +1,17 @@
 import { a as sole, n as isReadonlyArray, r as isRecord } from "./compact-CAf557ZB.js";
-import { o as isForbiddenKey } from "./thenable-QSmvt-vZ.js";
-import { l as isSqlFunctionField } from "./refs-f3imMjNW.js";
-import { c as rootScope, d as scopeList, l as scopeChain, o as resolveScope } from "./scopes-tvpa34ep.js";
-import { v as listRoles } from "./grantee-CXY-0C87.js";
-import { r as relationCondition, t as inheritCondition } from "./grantee-conditions-MQs5NIuX.js";
-import { l as partitionsOf, p as scopeField } from "./tenancy-DshjqY0n.js";
-import { t as CliError } from "./errors-CWfoNg9N.js";
-import { i as scopeMembershipTable, o as relatedSql, r as scopeColumn } from "./compile-CcEu2ZQ1.js";
-import { l as sqlTextArray, r as qualifySqlTable, t as SQL_IDENT } from "./sql-t8teWOfo.js";
-import { d as keptKeys, l as roleColumn, u as roleManifest } from "./sources-B1-b-R0t.js";
-import { n as requirePeer } from "./peer-BOr_kJE1.js";
-import { D as sqlType, E as scopeTypeOf, F as quoteQualified, I as quoteTable, 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-1uhI-e-b.js";
-//#region src/cli/pg.ts
-const CONNECT_TIMEOUT_MS = 1e4;
-const STATEMENT_TIMEOUT_MS = 6e4;
-function loadPg(command) {
-	return requirePeer(() => import("pg"), "pg", command);
-}
-function options(db) {
-	return {
-		connectionString: db,
-		connectionTimeoutMillis: CONNECT_TIMEOUT_MS,
-		statement_timeout: STATEMENT_TIMEOUT_MS
-	};
-}
-/** Ctrl-C ends the connection, so a query that hangs cannot keep the process alive. */
-function endOnInterrupt(end) {
-	const interrupt = () => {
-		end().catch(() => void 0);
-		process.exitCode = 130;
-	};
-	process.once("SIGINT", interrupt);
-	return async () => {
-		process.off("SIGINT", interrupt);
-		await end();
-	};
-}
-function unreachable(command, cause) {
-	return new CliError("unavailable", `PermDock CLI: ${command.replace(/^permdock /u, "")} could not connect`, { cause });
-}
-/** The default `connect` of a command: one connection, failing with a message that names `command`. */
-function pgConnector(command) {
-	return (db) => connectPg(db, command);
-}
-/** One connection, for commands that run a transaction. */
-async function connectPg(db, command) {
-	const client = new (await (loadPg(command))).Client(options(db));
-	try {
-		await client.connect();
-	} catch (cause) {
-		throw unreachable(command, cause);
-	}
-	return {
-		query: (sql, values) => client.query(sql, values),
-		end: endOnInterrupt(() => client.end())
-	};
-}
-/** A small pool, for independent catalog reads that can run in parallel. */
-async function connectPgPool(db, command) {
-	const pool = new (await (loadPg(command))).Pool({
-		...options(db),
-		max: 4
-	});
-	try {
-		(await pool.connect()).release();
-	} catch (cause) {
-		await pool.end();
-		throw unreachable(command, cause);
-	}
-	return {
-		query: (sql, values) => pool.query(sql, values),
-		end: endOnInterrupt(() => pool.end())
-	};
-}
-//#endregion
+import { n as isForbiddenKey } from "./paths-DXSHAMIa.js";
+import { l as isSqlFunctionField } from "./refs-K6eWUJ0H.js";
+import { u as isoAt } from "./time-DkWjdL98.js";
+import { c as rootScope, d as scopeList, l as scopeChain, o as resolveScope } from "./scopes-CUPSjo9q.js";
+import { t as isoInstant } from "./instant-BluqDvyS.js";
+import { m as findRole, v as listRoles } from "./grantee-hxrUsbpM.js";
+import { r as relationCondition, t as inheritCondition } from "./grantee-conditions-CcXf8hMM.js";
+import { l as partitionsOf, p as scopeField } from "./tenancy-DN2QAx9z.js";
+import { i as configError } from "./errors-CWTY6uih.js";
+import { i as scopeMembershipTable, o as relatedSql, r as scopeColumn } from "./compile-CMqMx_IN.js";
+import { i as qualifySqlTable, t as SQL_IDENT, u as sqlTextArray } from "./sql-B5T1IL83.js";
+import { d as keptKeys, l as roleColumn, u as roleManifest } from "./sources-vs5dGOsS.js";
+import { A as declaredArray, D as sqlType, E as scopeTypeOf, F as quoteQualified, I as quoteTable, L as textArrayLiteral, M as qualified, N as quoteIdent, O as tenantTypeOf, P as quoteLiteral, S as CLAIM, _ as subjectClaimJsonSql, b as tenantClaimSql, d as keyTenantSql, f as kindFilterSql, h as roleKindSql, i as allowEntry, j as helperSchema, k as CLI, m as memberVia, n as GLOBAL_ROLES, o as rootName, p as liveSessionSql, r as HELPERS, s as signedIn, t as CUSTOM_ROLES, u as globalKindFilterSql, v as subjectClaimSql, x as userIdHelperSql, y as subjectIdSql } from "./shared-BAK8t4Uo.js";
 //#region src/cli/sql/active.ts
 function checkActiveRow(label, row) {
 	quoteTable(row.table);
@@ -81,9 +19,9 @@ function checkActiveRow(label, row) {
 	if (row.disabledAt !== void 0) quoteIdent(row.disabledAt);
 	if (row.status !== void 0) {
 		quoteIdent(row.status);
-		if (row.active === void 0 || row.active.length === 0) throw new Error(`PermDock CLI: ${label}.status needs the active values in ${label}.active`);
+		if (row.active === void 0 || row.active.length === 0) throw configError(`PermDock CLI: ${label}.status needs the active values in ${label}.active`);
 	}
-	if (row.disabledAt === void 0 && row.status === void 0) throw new Error(`PermDock CLI: ${label} needs disabledAt or status to tell an active row`);
+	if (row.disabledAt === void 0 && row.status === void 0) throw configError(`PermDock CLI: ${label} needs disabledAt or status to tell an active row`);
 }
 /** Validates `rls.suspension` and keys its scopes by declared name. */
 function checkSuspension(suspension, scopes) {
@@ -92,9 +30,9 @@ function checkSuspension(suspension, scopes) {
 	const byName = {};
 	for (const [key, row] of Object.entries(suspension.scopes ?? {})) {
 		const name = resolveScope(scopes, key);
-		if (name === void 0) throw new Error(`PermDock CLI: rls.suspension.scopes.${key} names a scope the policy does not declare`);
+		if (name === void 0) throw configError(`PermDock CLI: rls.suspension.scopes.${key} names a scope the policy does not declare`);
 		checkActiveRow(`rls.suspension.scopes.${key}`, row);
-		if (row.keep !== void 0 && !Array.isArray(row.keep)) throw new Error(`PermDock CLI: rls.suspension.scopes.${key}.keep is a list of permissions or permission keys`);
+		if (row.keep !== void 0 && !Array.isArray(row.keep)) throw configError(`PermDock CLI: rls.suspension.scopes.${key}.keep is a list of permissions or permission keys`);
 		const keep = keptKeys(row);
 		const { keep: _given, ...active } = row;
 		byName[name] = keep.length === 0 ? active : {
@@ -103,7 +41,7 @@ function checkSuspension(suspension, scopes) {
 		};
 	}
 	const memberships = suspension.memberships;
-	if (memberships?.keep !== void 0 && !Array.isArray(memberships.keep)) throw new Error("PermDock CLI: rls.suspension.memberships.keep is a list of permissions or permission keys");
+	if (memberships?.keep !== void 0 && !Array.isArray(memberships.keep)) throw configError("PermDock CLI: rls.suspension.memberships.keep is a list of permissions or permission keys");
 	const keep = keptKeys(memberships);
 	return {
 		...suspension.users === void 0 ? {} : { users: suspension.users },
@@ -126,18 +64,20 @@ function keptRowSql(keep, permission) {
 	return `case ${kind} when 'null' then true when 'array' then ${keep} @> jsonb_build_array(${"key" in permission ? quoteLiteral(permission.key) : permission.sql}) else false end`;
 }
 /**
-* `exists` over an active row whose id column equals `id`: a missing row is
-* suspended, so the check fails closed.
+* Whether `id` is among the active rows' ids: a missing row is suspended, so
+* the check fails closed, and so does a null `id`. `id` stays outside the
+* subquery so a column of the same name on `row.table` cannot capture it.
 */
 function activeRowSql(row, id) {
 	const table = quoteTable(qualifySqlTable(row.table));
-	const parts = [`s.${quoteIdent(row.id)} = ${id}`];
+	const parts = [];
 	if (row.disabledAt !== void 0) parts.push(`s.${quoteIdent(row.disabledAt)} is null`);
 	if (row.status !== void 0) {
 		const values = (row.active ?? []).map(quoteLiteral).join(", ");
 		parts.push(`s.${quoteIdent(row.status)}::text = any(array[${values}]::text[])`);
 	}
-	return `exists (select 1 from ${table} s where ${parts.join(" and ")})`;
+	const where = parts.length === 0 ? "" : ` where ${parts.join(" and ")}`;
+	return `coalesce(${id} in (select s.${quoteIdent(row.id)} from ${table} s${where}), false)`;
 }
 /** The active-user check for `user`; empty without `rls.suspension.users`. */
 function activeUserSql(ctx, user = subjectIdSql(ctx)) {
@@ -161,7 +101,7 @@ function activeInstancesSql(ctx, scope, idOf, permission = ctx.permission === vo
 		const row = ctx.suspension?.scopes?.[name];
 		if (row === void 0) continue;
 		const id = idOf(name);
-		if (id === void 0) throw new Error(`PermDock CLI: rls.suspension.scopes.${name} needs the ${name} id on ${scope} memberships: add columns.${name} to the ${scope} memberships table`);
+		if (id === void 0) throw configError(`PermDock CLI: rls.suspension.scopes.${name} needs the ${name} id on ${scope} memberships: add columns.${name} to the ${scope} memberships table`);
 		const keep = keptKeys(row);
 		if (permission !== void 0 && "key" in permission && keep.includes(permission.key)) continue;
 		const active = activeRowSql(row, `(${id})::${scopeTypeOf(ctx, name)}`);
@@ -184,7 +124,7 @@ function graphSqlName(name) {
 }
 function sqlNameOf(name, label) {
 	const sql = graphSqlName(name);
-	if (sql === void 0) throw new Error(`PermDock CLI: ${label} is not a SQL name (letters, digits and underscores, starting with a letter), so rls generate cannot name its helper`);
+	if (sql === void 0) throw configError(`PermDock CLI: ${label} is not a SQL name (letters, digits and underscores, starting with a letter), so rls generate cannot name its helper`);
 	return sql;
 }
 /** The helper returning the ids of `resource` the subject holds a relation on: `permitted_<snake_case resource>_ids`. */
@@ -225,7 +165,7 @@ function memberRoleOf(table, alias = "m", indent) {
 /** The schema-qualified name of a table under `search_path = ''`. */
 /** The helper returning the ids of scope `name` a grant key reaches. */
 function permittedIdsHelper(name) {
-	if (!/^[a-z][a-z0-9_]*$/u.test(name)) throw new Error(`PermDock CLI: unsafe scope name '${name}'`);
+	if (!/^[a-z][a-z0-9_]*$/u.test(name)) throw configError(`PermDock CLI: unsafe scope name '${name}'`);
 	return `permitted_${name}_ids`;
 }
 /** `permitted_<scope>_ids_for(p_user, p_grant)`: the same ids for a user the caller names. */
@@ -234,7 +174,7 @@ function permittedForHelper(name) {
 }
 /** The helper returning the ids of scope `name` the subject holds any live membership of. */
 function memberIdsHelper(name) {
-	if (!/^[a-z][a-z0-9_]*$/u.test(name)) throw new Error(`PermDock CLI: unsafe scope name '${name}'`);
+	if (!/^[a-z][a-z0-9_]*$/u.test(name)) throw configError(`PermDock CLI: unsafe scope name '${name}'`);
 	return `member_${name}_ids`;
 }
 /** `member_<scope>_ids_for(p_user uuid)`: the same rows for a user the caller names; the token hook's helper. */
@@ -250,6 +190,15 @@ function hasMemberFor(input, name) {
 	if (input.dialect !== "supabase") return false;
 	return memberForTable(input, name) !== void 0 || memberForSources(input, name).length > 0;
 }
+/**
+* Whether `permitted_<scope>_users` can list the members of one instance of
+* `name`: a mapped membership table, or sources that all read a table.
+*/
+function hasPermittedUsers(input, name) {
+	if (memberForTable(input, name) !== void 0) return true;
+	const sources = memberForSources(input, name);
+	return sources.length > 0 && sources.every((source) => source.sql.holders !== void 0);
+}
 /** The table `member_<scope>_ids_for` reads for scope `name`, when `memberships` maps one with its id column. */
 function memberForTable(input, name) {
 	const table = scopeMembershipTable(input.memberships, input.scopes, name);
@@ -262,7 +211,7 @@ function memberForSources(input, name) {
 }
 /**
 * The membership sources that can hold scope `name` when `memberships` maps
-* no table for it: every `fromTable` source and the `fromJunction` sources of
+* no table for it: every `tableMembershipSource` source and the `junctionMembershipSource` sources of
 * that scope. Empty outside `database` mode.
 */
 function scopeSources(ctx, name) {
@@ -297,8 +246,8 @@ function claimPath(ref) {
 	const prefix = ["principal.claim.", "principal.claims."].find((item) => ref.startsWith(item));
 	if (prefix === void 0) return;
 	const segments = ref.slice(prefix.length).split(".");
-	if (segments.length > MAX_CLAIM_DEPTH) throw new Error(`PermDock CLI: claim path '${ref}' is deeper than ${MAX_CLAIM_DEPTH}`);
-	for (const segment of segments) if (!CLAIM.test(segment) || isForbiddenKey(segment)) throw new Error(`PermDock CLI: unsafe claim name '${segment}'`);
+	if (segments.length > MAX_CLAIM_DEPTH) throw configError(`PermDock CLI: claim path '${ref}' is deeper than ${MAX_CLAIM_DEPTH}`);
+	for (const segment of segments) if (!CLAIM.test(segment) || isForbiddenKey(segment)) throw configError(`PermDock CLI: unsafe claim name '${segment}'`);
 	return segments;
 }
 function jsonPath(base, keys, last) {
@@ -312,7 +261,7 @@ function jsonPath(base, keys, last) {
 */
 function claimRoot(ctx, path) {
 	const [head, ...rest] = path;
-	if (head === void 0) throw new Error("PermDock CLI: empty claim path");
+	if (head === void 0) throw configError("PermDock CLI: empty claim path");
 	switch (ctx.dialect) {
 		case "supabase": return {
 			root: "(select auth.jwt())",
@@ -372,13 +321,16 @@ function claimArraySql(ctx, path, type) {
 }
 function sqlValue(value, ctx, field) {
 	if (value !== null && typeof value === "object" && "ref" in value) return compileRef(value.ref, ctx, field);
-	if (value !== null && typeof value === "object" && "date" in value) return quoteLiteral(value.date);
+	if (value !== null && typeof value === "object" && "date" in value) {
+		const instant = isoInstant(value.date);
+		return instant === void 0 ? "null" : quoteLiteral(isoAt(instant));
+	}
 	if (isReadonlyArray(value)) return `array[${value.map((item) => sqlValue(item, ctx)).join(", ")}]`;
 	if (value === null) return "null";
 	if (typeof value === "boolean") return value ? "true" : "false";
 	if (typeof value === "number") return Number.isFinite(value) ? String(value) : "null";
 	if (typeof value === "string") return quoteLiteral(value);
-	throw new Error("PermDock CLI: non-portable condition value");
+	throw configError("PermDock CLI: non-portable condition value");
 }
 function compileRef(ref, ctx, field) {
 	if (ref === "principal.id") return subjectIdSql(ctx);
@@ -386,8 +338,8 @@ function compileRef(ref, ctx, field) {
 	const path = claimPath(ref);
 	if (ref === "principal.tenant" || path?.length === 1 && path[0] === ctx.tenantClaim) return tenantClaimSql(ctx);
 	if (path !== void 0) return typedClaimSql(ctx, path, field === void 0 ? void 0 : ctx.columnTypes?.[field]);
-	if (ref === "context" || ref.startsWith("context.")) throw new Error(`PermDock CLI: '${ref}' is request context, which is not in the token; RLS cannot read it (permdock doctor PD027)`);
-	throw new Error(`PermDock CLI: non-portable subject ref '${ref}'`);
+	if (ref === "context" || ref.startsWith("context.")) throw configError(`PermDock CLI: '${ref}' is request context, which is not in the token; RLS cannot read it (permdock doctor PD027)`);
+	throw configError(`PermDock CLI: non-portable subject ref '${ref}'`);
 }
 /** `value` with `\`, `%` and `_` escaped for `like ... escape '\'`, as `escapeLike` does in process. */
 function likeLiteralSql(value) {
@@ -406,13 +358,18 @@ function compareSql(op, field, value) {
 		default: return op;
 	}
 }
-function existsSql(table, rowColumn, rowField, roles, ctx, tenantColumn, scope) {
-	const parts = [`m.${quoteIdent(rowColumn)} = ${quoteIdent(rowField)}`, `m.${quoteIdent(table.user)} = ${subjectIdSql(ctx)}`];
+/**
+* Whether the row's `rowField` is among the ids in `table.rowColumn` the
+* subject holds a matching membership on. The row field stays outside the
+* subquery: inside it, an unqualified name resolves to the membership table
+* first, so `m.org_id = "org_id"` would compare the membership with itself.
+*/
+function membershipSql(table, rowColumn, rowField, roles, ctx, tenantColumn, scope) {
+	const parts = [`m.${quoteIdent(table.user)} = ${subjectIdSql(ctx)}`];
 	const role = memberRoleOf(table);
 	if (roles.length > 0) {
-		const roleList = roles.map((name) => name.replaceAll("'", "''")).join(",");
 		const held = role.through === void 0 && !role.lateral ? `m.${quoteIdent(role.column)}` : role.lookup;
-		parts.push(`${held} = any('{${roleList}}')`);
+		parts.push(`${held} = any(${textArrayLiteral(roles)})`);
 		const via = memberVia(table);
 		const single = sole(roles);
 		const kind = single === void 0 ? kindFilterSql(ctx, role.lookup, via) : roleKindSql(ctx, single, via);
@@ -432,23 +389,23 @@ function existsSql(table, rowColumn, rowField, roles, ctx, tenantColumn, scope)
 		}));
 	}
 	const expand = roles.length > 0 && role.lateral ? role.join : "";
-	return `exists (select 1 from ${quoteTable(table.table)} m${expand} where ${parts.join(" and ")})`;
+	return `${quoteIdent(rowField)} in (select m.${quoteIdent(rowColumn)} from ${quoteTable(table.table)} m${expand} where ${parts.join(" and ")})`;
 }
 function compileMemberOf(condition, ctx) {
 	const scope = condition.scope === "resource" ? void 0 : resolveScope(ctx.scopes, condition.scope);
-	if (condition.scope !== "resource" && scope === void 0) throw new Error(`PermDock CLI: memberOf ${condition.scope} names a scope the policy does not declare`);
+	if (condition.scope !== "resource" && scope === void 0) throw configError(`PermDock CLI: memberOf ${condition.scope} names a scope the policy does not declare`);
 	const mapping = scope === void 0 ? condition.resource === void 0 ? void 0 : ctx.memberships?.resource?.[condition.resource] : scopeMembershipTable(ctx.memberships, ctx.scopes, scope);
 	if (mapping !== void 0) {
 		const named = scope === void 0 ? void 0 : scopeTable(ctx, scope);
 		const rowColumn = scope === void 0 ? mapping.id : named?.column;
-		if (rowColumn === void 0) throw new Error(`PermDock CLI: memberships mapping for ${condition.scope} is missing the row column`);
+		if (rowColumn === void 0) throw configError(`PermDock CLI: memberships mapping for ${condition.scope} is missing the row column`);
 		const tenantColumn = scope === void 0 || scope === rootScope(ctx.scopes) ? void 0 : named?.tenantColumn;
-		const primary = existsSql(mapping, rowColumn, condition.field, condition.roles, ctx, tenantColumn, scope);
+		const primary = membershipSql(mapping, rowColumn, condition.field, condition.roles, ctx, tenantColumn, scope);
 		if (condition.scope !== "resource" || condition.parents === void 0) return primary;
 		return `(${[primary, ...condition.parents.flatMap((parent) => {
-			if (typeof parent === "string") return [existsSql(mapping, rowColumn, parent, condition.roles, ctx, tenantColumn)];
+			if (typeof parent === "string") return [membershipSql(mapping, rowColumn, parent, condition.roles, ctx, tenantColumn)];
 			const hopTable = ctx.memberships?.resource?.[parent.resource];
-			return hopTable?.id === void 0 ? [] : [existsSql(hopTable, hopTable.id, parent.field, condition.roles, ctx)];
+			return hopTable?.id === void 0 ? [] : [membershipSql(hopTable, hopTable.id, parent.field, condition.roles, ctx)];
 		})].join(" or ")})`;
 	}
 	if (scope !== void 0 && condition.roles.length === 0 && scopeSources(ctx, scope).length > 0) return `${quoteIdent(condition.field)} in (select ${qualified(ctx, memberIdsHelper(scope))}())`;
@@ -461,7 +418,7 @@ function compileMemberOf(condition, ctx) {
 		];
 		return parts.length === 1 ? parts.join("") : `(${parts.join(" and ")})`;
 	}
-	throw new Error(`PermDock CLI: memberOf ${condition.scope} needs a memberships table mapping`);
+	throw configError(`PermDock CLI: memberOf ${condition.scope} needs a memberships table mapping`);
 }
 function compileConditionSql(condition, ctx) {
 	switch (condition.op) {
@@ -489,13 +446,14 @@ function compileConditionSql(condition, ctx) {
 				const path = claimPath(condition.value.ref);
 				if (path === void 0) {
 					compileRef(condition.value.ref, ctx);
-					throw new Error(`PermDock CLI: non-portable ${condition.op} against '${condition.value.ref}'`);
+					throw configError(`PermDock CLI: non-portable ${condition.op} against '${condition.value.ref}'`);
 				}
 				const column = quoteIdent(condition.field);
 				const list = claimArraySql(ctx, path, ctx.columnTypes?.[condition.field]);
 				return condition.op === "in" ? `${column} = any (${list})` : `(${column} is not null and not (${column} = any (${list})))`;
 			}
 			const values = condition.value.map((item) => sqlValue(item, ctx));
+			if (values.length === 0) return condition.op === "in" ? "false" : `${quoteIdent(condition.field)} is not null`;
 			return `${quoteIdent(condition.field)} ${keyword} (${values.join(", ")})`;
 		}
 		case "isNull": return `${quoteIdent(condition.field)} is ${condition.value ? "" : "not "}null`;
@@ -609,7 +567,7 @@ function compileRelatedSql(condition, ctx) {
 */
 function compileHoppedSql(condition, ctx) {
 	const resources = ctx.graph?.resources;
-	if (resources === void 0) throw new Error("PermDock CLI: a related condition with link hops needs the policy resources in the RLS context");
+	if (resources === void 0) throw configError("PermDock CLI: a related condition with link hops needs the policy resources in the RLS context");
 	const schema = quoteIdent(helperSchema(ctx));
 	return graphSqlText(relatedSql(condition, {
 		resources,
@@ -661,17 +619,17 @@ function relationWhere(policy, grant, grantee) {
 		resources: policy.resources,
 		now: { ref: "now" }
 	});
-	if (where === void 0) throw new Error(`PermDock CLI: grant ${grant.permission.key} names relation '${grantee.relation}', which ${grant.permission.resource} does not declare`);
+	if (where === void 0) throw configError(`PermDock CLI: grant ${grant.permission.key} names relation '${grantee.relation}', which ${grant.permission.resource} does not declare`);
 	return where;
 }
 function inheritWhere(policy, grant, grantee) {
 	const where = inheritCondition(grantee, policy.resources.get(grant.permission.resource), policy.resources);
-	if (where === void 0) throw new Error(`PermDock CLI: grant ${grant.permission.key} inherits ${grantee.permission}, which ${grant.permission.resource} cannot reach`);
+	if (where === void 0) throw configError(`PermDock CLI: grant ${grant.permission.key} inherits ${grantee.permission}, which ${grant.permission.resource} cannot reach`);
 	return where;
 }
 /** Only a deny for `oauth-client` actors compiles: Postgres sees `client_id` and `act`, not other actor kinds. */
 function actorAccess(grant, grantee, others) {
-	if (grant.effect !== "deny" || grantee.actor !== "oauth-client" || others > 0) throw new Error(`PermDock CLI: grant ${grant.permission.key} is limited to an actor grantee; RLS compiles only deny(…, { to: actor('oauth-client') }) on its own, so enforce it in the application`);
+	if (grant.effect !== "deny" || grantee.actor !== "oauth-client" || others > 0) throw configError(`PermDock CLI: grant ${grant.permission.key} is limited to an actor grantee; RLS compiles only deny(…, { to: actor('oauth-client') }) on its own, so enforce it in the application`);
 	return {
 		kind: "actor",
 		actor: "oauth-client"
@@ -679,7 +637,7 @@ function actorAccess(grant, grantee, others) {
 }
 function accessOf(grant, roles, anyone) {
 	const [held, ...more] = roles;
-	if (more.length > 0) throw new Error(`PermDock CLI: grant ${grant.permission.key} requires several roles at once (${roles.map((item) => item.role).join(", ")}); RLS compiles one role per grant`);
+	if (more.length > 0) throw configError(`PermDock CLI: grant ${grant.permission.key} requires several roles at once (${roles.map((item) => item.role).join(", ")}); RLS compiles one role per grant`);
 	if (held === void 0) return anyone ? { kind: "anyone" } : { kind: "authenticated" };
 	if (typeof held.scope === "object") return {
 		kind: "resource",
@@ -724,7 +682,7 @@ function collectGrants(policy) {
 				delegated = actorAccess(grant, item, items.length - 1);
 				break;
 			case "plan":
-			case "assurance": throw new Error(`PermDock CLI: grant ${grant.permission.key} is limited to a ${item.kind} grantee, which RLS cannot compile; enforce it in the application`);
+			case "assurance": throw configError(`PermDock CLI: grant ${grant.permission.key} is limited to a ${item.kind} grantee, which RLS cannot compile; enforce it in the application`);
 			default: return item;
 		}
 		const access = delegated ?? accessOf(grant, roles, anyone);
@@ -759,7 +717,7 @@ const DEFAULTS = {
 };
 function field(settings, name) {
 	const value = settings[name] ?? DEFAULTS[name];
-	if (typeof value !== "string" || !SQL_IDENT.test(value)) throw new Error(`PermDock CLI: rls.apiKeys.${name} must be a claim field name matching ${SQL_IDENT.source}`);
+	if (typeof value !== "string" || !SQL_IDENT.test(value)) throw configError(`PermDock CLI: rls.apiKeys.${name} must be a claim field name matching ${SQL_IDENT.source}`);
 	return value;
 }
 function apiKeyFields(setting) {
@@ -776,7 +734,7 @@ function apiKeysPlan(setting, declared, renamed) {
 	if (setting === void 0) return;
 	const fields = apiKeyFields(setting);
 	const unknown = fields.serviceRoles.filter((role) => !declared.has(role));
-	if (unknown.length > 0) throw new Error(`PermDock CLI: rls.apiKeys.serviceRoles names roles the policy does not declare: ${unknown.join(", ")}`);
+	if (unknown.length > 0) throw configError(`PermDock CLI: rls.apiKeys.serviceRoles names roles the policy does not declare: ${unknown.join(", ")}`);
 	return {
 		...fields,
 		...Object.keys(renamed).length === 0 ? {} : { renamed }
@@ -873,6 +831,15 @@ ${body}
   ), false)`;
 }
 //#endregion
+//#region src/cli/shared/compare.ts
+/** UTF-16 code-unit order, never `localeCompare`: generated SQL must match byte for byte on every machine. */
+function byCodeUnit(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+function byKey([a], [b]) {
+	return byCodeUnit(a, b);
+}
+//#endregion
 //#region src/cli/rls/custom-roles.ts
 /** The readers every helpers file ends with. Names are part of the SQL contract. */
 const READERS = {
@@ -916,9 +883,14 @@ create unique index if not exists ${quoteIdent(`${name}_level_key`)}` : `create
   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)
+  ${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});
@@ -941,9 +913,11 @@ where rp.role = any(${sqlTextArray(custom.assignable)})
       and a.effect = 'allow'
   );
 revoke all on table ${ceiling} from anon, authenticated, public;`);
-	const renames = Object.entries(custom.renamed ?? {}).toSorted(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+	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);
@@ -1001,8 +975,30 @@ as $$
   where c.permission in (select a.permission from allowed a)
 $$;
 revoke execute on function ${keys}(text[], text[], text[], text) from public, anon, authenticated;`);
+	if (shared !== "") chunks.push(shared);
 	return chunks.join("\n\n");
 }
+/** `permdock_is_shared_role(p_scope, p_role)` (`database` mode): whether a shared custom role of that name exists at the scope. */
+function sharedRoleSql(ctx) {
+	if (ctx.authorize !== "database") return "";
+	const perms = qualified(ctx, CUSTOM_ROLES.permissions);
+	const includes = qualified(ctx, CUSTOM_ROLES.includes);
+	const shared = qualified(ctx, CUSTOM_ROLES.shared);
+	return `-- a shared custom role: rows with no tenant at a scope below global; its name wins over a tenant role's in every tenant
+create or replace function ${shared}(p_scope text, p_role text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select p_scope <> 'global' and (
+    exists (select 1 from ${perms} c where c.tenant_id is null and c.scope = p_scope and c.role = p_role)
+    or exists (select 1 from ${includes} c where c.tenant_id is null and c.scope = p_scope and c.role = p_role)
+  )
+$$;
+revoke execute on function ${shared}(text, text) from public, anon, authenticated;`;
+}
 /**
 * `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>`
@@ -1139,7 +1135,8 @@ function renamesSql(renames) {
 * 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
+* 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.
 */
@@ -1230,6 +1227,7 @@ 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")}
@@ -1263,6 +1261,27 @@ $$;
 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`;
+}
+/**
+* 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 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`;
+}
+/**
+* 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`;
+}
 /** `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;
@@ -1301,7 +1320,8 @@ function globalRoleSource(source, schema, alias, roles) {
 		indent: "    "
 	});
 	const tenant = role.lateral ? void 0 : throughTenant(role.through, roles);
-	const global = tenant === void 0 ? "" : ` and ${alias}k.${quoteIdent(tenant)} is null`;
+	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,
@@ -1310,7 +1330,8 @@ function globalRoleSource(source, schema, alias, roles) {
 		roleSql: role.sql,
 		role: roleManifest(role),
 		...role.through === void 0 ? {} : { through: role.through },
-		...tenant === void 0 ? {} : { tenant }
+		...tenant === void 0 ? {} : { tenant },
+		...shared === void 0 ? {} : { shared }
 	};
 }
 //#endregion
@@ -1544,7 +1565,7 @@ function tableBody(ctx, scope, type) {
 	const custom = ctx.customRoles;
 	if (custom === void 0) return lines.join("\n");
 	const match = [
-		`c.tenant_id::text = ${memberColumn(tenantColumn ?? column)}::text`,
+		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}`
@@ -1585,8 +1606,8 @@ function claimBody(ctx, scope, type) {
     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 -> 'expiresAt')
-      when 'number' then (m ->> 'expiresAt')::numeric > extract(epoch from now())
+    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)),
@@ -1707,7 +1728,7 @@ ${rows}
 	const custom = ctx.customRoles;
 	if (custom === void 0) return sourcesBodyOf(declared, sources, subjectIdSql(ctx));
 	const match = [
-		`c.tenant_id::text = (${tenant})::text`,
+		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"
@@ -1771,8 +1792,8 @@ as $$
     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 -> 'expiresAt') = 'number'
-    and (c ->> 'expiresAt')::numeric > extract(epoch from now())
+    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;`;
@@ -1808,7 +1829,7 @@ function customRoleCascadeSql(ctx) {
 	const fn = qualified(ctx, CUSTOM_ROLES.cascade);
 	const target = quoteTable(qualifySqlTable(table.table));
 	const tenant = (row) => table.tenant === void 0 ? `null::${tenantType}` : `${rowColumn(row, table.tenant)}::${tenantType}`;
-	const scope = (row) => table.scope === void 0 ? `case when ${tenant(row)} is null then 'global' else ${quoteLiteral(root)} end` : `case when ${tenant(row)} is null then 'global' else ${rowColumn(row, table.scope)}::text end`;
+	const scope = (row) => rolesTableScope(table, tenant(row), root, (name) => rowColumn(row, name));
 	const id = (row) => table.id === void 0 ? "null::text" : `${rowColumn(row, table.id)}::text`;
 	const skipped = (row) => table.skip === void 0 ? "false" : `coalesce(${rowColumn(row, table.skip)}, false)`;
 	const guard = qualified(ctx, CUSTOM_ROLES.guard);
@@ -1942,7 +1963,7 @@ ${raiseSql("    ", "42501", `'permdock: the caller may not manage roles in ' ||
       )` : "";
 	const reachCte = leveled && reachRows !== "" ? `,
     reach (grant_key, level) as (values ${reachRows})` : "";
-	const match = `c.tenant_id is not distinct from p_tenant and c.scope = p_scope and c.scope_id is not distinct from p_scope_id`;
+	const match = `${storedTenant(ctx)} and c.scope = p_scope and c.scope_id is not distinct from p_scope_id`;
 	const memberOf = `p_tenant::text in ${members(root)}
       or ${perScope(ctx, (scope) => scope === root ? "false" : `p_scope_id in ${members(scope)}`)}`;
 	return {
@@ -1994,7 +2015,7 @@ begin
   perform ${shape}(p_tenant, p_scope, p_scope_id, p_role);
   if not (${signedIn(ctx, user)} and (
     ${platform}
-    or (p_scope <> 'global' and (${memberOf}))
+    or (p_scope <> 'global' and coalesce(${memberOf}, false))
   )) then
 ${raiseSql("    ", "42501", `'permdock: the caller is not a member of ' || coalesce(p_tenant::text, 'the platform')`, "not-member")}
   end if;${requires}
@@ -2022,8 +2043,9 @@ revoke execute on function ${guard}(${userArg}${tenantType}, text, text, text) f
 * \`assignablePermissions\`: entries inside the ceiling of the role's scope,
 * includes naming declared roles, and only permissions and levels the caller
 * may hand out, for the new definition and the stored one alike. A platform
-* custom role (\`p_scope = 'global'\`, no tenant) is written by a caller who
-* holds a \`meta.manageRoles\` permission through a global role. The
+* custom role (\`p_scope = 'global'\`, no tenant) and a shared custom role (no
+* tenant at a lower scope) are written by a caller who holds a
+* \`meta.manageRoles\` permission through a global role. The
 * \`permdock_trusted_*\` variants skip the caller checks and keep the
 * definition checks; no client role may execute them.
 */
@@ -2041,7 +2063,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 renames = Object.entries(custom.renamed ?? {}).toSorted(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+	const renames = Object.entries(custom.renamed ?? {}).toSorted(byKey);
 	const current = (expr) => currentKeyExpr(renames, expr);
 	const known = sqlTextArray([...custom.permissions ?? [], ...renames.map(([former]) => former)]);
 	const caller = callerFunctionsSql(ctx, custom, root, levelReach, false);
@@ -2049,9 +2071,15 @@ function customRoleWritesSql(ctx, levelReach) {
 	const scopes = sqlTextArray(ctx.scopes.map((scope) => scope.name));
 	const roleName = (param) => `coalesce(${param}, '') = '' or ${param} = any(${sqlTextArray(custom.declared)})`;
 	const levelOf = leveled ? ", nullif(split_part(e, '@', 2), '')" : "";
-	const write = `  delete from ${perms} c where ${match} and c.role = p_role;
+	const levelColumn = leveled ? ", level" : "";
+	const sharedRole = qualified(ctx, CUSTOM_ROLES.shared);
+	const taken = (param) => `  if p_tenant is not null and ${sharedRole}(p_scope, ${param}) then
+${raiseSql("    ", "22023", `'permdock: ' || ${param} || ' is the name of a shared custom role'`, "name-taken")}
+  end if;
+`;
+	const write = `${taken("p_role")}  delete from ${perms} c where ${match} and c.role = p_role;
   delete from ${includes} c where ${match} and c.role = p_role;
-  insert into ${perms} (tenant_id, scope, scope_id, role, permission, effect${leveled ? ", level" : ""})
+  insert into ${perms} (tenant_id, scope, scope_id, role, permission, effect${levelColumn})
   select distinct p_tenant, p_scope, p_scope_id, p_role, ${current(leveled ? "split_part(e, '@', 1)" : "e")}, 'allow'${levelOf}
   from unnest(coalesce(p_allow, '{}'::text[])) e
   union
@@ -2060,7 +2088,7 @@ function customRoleWritesSql(ctx, levelReach) {
   insert into ${includes} (tenant_id, scope, scope_id, role, include_role)
   select distinct p_tenant, p_scope, p_scope_id, p_role, e
   from unnest(coalesce(p_include, '{}'::text[])) e;`;
-	const move = `  if ${roleName("p_to")} then
+	const move = `${taken("p_to")}  if ${roleName("p_to")} then
 ${raiseSql("    ", "22023", `'permdock: ' || coalesce(p_to, 'null') || ' is not a custom role name'`, "declared-role")}
   end if;
   if exists (select 1 from ${perms} c where ${match} and c.role = p_to)
@@ -2091,7 +2119,7 @@ grant execute on function ${qualified(ctx, name)}(${args}) to authenticated;` :
 	const removeParams = `p_tenant ${tenantType}, p_scope text, p_scope_id text, p_role text`;
 	return `${caller.beyond}
 
--- where a custom role may live: a scope of a tenant, or the platform (scope global, no tenant or instance), under an undeclared name
+-- where a custom role may live: a scope of a tenant, a scope of every tenant (shared: no tenant or instance), or the platform (scope global, no tenant or instance), under an undeclared name
 create or replace function ${shape}(p_tenant ${tenantType}, p_scope text, p_scope_id text, p_role text)
 returns void
 language plpgsql
@@ -2103,8 +2131,10 @@ begin
     if p_tenant is not null or p_scope_id is not null then
 ${raiseSql("      ", "22023", `'permdock: a platform custom role has no tenant or instance'`, "unknown-scope")}
     end if;
-  elsif p_tenant is null or not (p_scope = any(${scopes})) then
+  elsif not (p_scope = any(${scopes})) then
 ${raiseSql("    ", "22023", `'permdock: custom roles are held at a scope of a tenant or at global, not ' || coalesce(p_scope, 'null')`, "unknown-scope")}
+  elsif p_tenant is null and p_scope_id is not null then
+${raiseSql("    ", "22023", `'permdock: a shared custom role has no instance'`, "unknown-scope")}
   end if;
   if ${roleName("p_role")} then
 ${raiseSql("    ", "22023", `'permdock: ' || coalesce(p_role, 'null') || ' is not a custom role name'`, "declared-role")}
@@ -2250,7 +2280,7 @@ function globalRolesSql(ctx) {
 		const id = quoteIdent(through.id);
 		const key = quoteIdent(through.key);
 		const ref = quoteIdent(through.ref);
-		const global = source.tenant === void 0 ? "" : ` and k.${quoteIdent(source.tenant)} is null`;
+		const global = source.tenant === void 0 ? "" : ` and k.${quoteIdent(source.tenant)} is null${source.shared === void 0 ? "" : ` and k.${quoteIdent(source.shared)} is not true`}`;
 		body = `  select string_agg(w.r, ', ' order by w.r) into v_unknown
   from (${wanted}) w(r)
   where not exists (select 1 from ${keys} k where k.${key}::text = w.r${global});
@@ -2298,7 +2328,7 @@ grant execute on function ${fn}(${args}) to authenticated;`;
 * a live membership of, with any role. Not narrowed to the active tenant, and
 * no cascade: a membership of a child scope is not one of its parent.
 */
-function memberBody(ctx, scope, type) {
+function memberBody(ctx, scope, type, roles) {
 	if (ctx.authorize !== "database") return sqlBody(`  select distinct (m ->> 'id')::${type}
   from jsonb_array_elements(
     case jsonb_typeof(${membershipClaim(ctx)}) when 'array' then ${membershipClaim(ctx)} else '[]'::jsonb end
@@ -2307,22 +2337,22 @@ function memberBody(ctx, scope, type) {
     and m ->> 'scope' = ${quoteLiteral(scope)}
     and m ->> 'id' is not null${keyTenantLine(ctx, scope, claimTenant(ctx, scope))}
     and jsonb_typeof(m -> 'roles') = 'array'
-    and jsonb_array_length(m -> 'roles') > 0
-    and case jsonb_typeof(m -> 'expiresAt')
-      when 'number' then (m ->> 'expiresAt')::numeric > extract(epoch from now())
+    and jsonb_array_length(m -> 'roles') > 0${roles === void 0 ? "" : `\n    and (m -> 'roles') ?| ${roles}`}
+    and case jsonb_typeof(m -> 'expires_at')
+      when 'number' then (m ->> 'expires_at')::numeric > extract(epoch from now())
       else true
     end${[
 		...claimKeptLines(ctx, "    "),
 		...userActive(ctx, "    "),
 		...instancesActive(ctx, scope, (name) => name === scope ? `m ->> 'id'` : `m -> 'within' ->> ${quoteLiteral(name)}`, "    ")
 	].map((line) => `\n${line}`).join("")}`);
-	return memberRowsBody(ctx, scope, type, subjectIdSql(ctx), scopeSources(ctx, scope), true);
+	return memberRowsBody(ctx, scope, type, subjectIdSql(ctx), scopeSources(ctx, scope), true, roles);
 }
 /**
 * The membership rows of `user` for `scope`, from the sources or else the
 * mapped table, with the same expiry and suspension filters either way.
 */
-function memberRowsBody(ctx, scope, type, user, sources, keyed = false) {
+function memberRowsBody(ctx, scope, type, user, sources, keyed = false, roles) {
 	if (sources.length > 0) {
 		const narrow = keyed ? keyTenantLine(ctx, scope, sourceIdOf(scope)(rootName(ctx))) : "";
 		return sourcesBodyOf(`  select distinct (ms.id)::${type}
@@ -2332,7 +2362,7 @@ ${sourceRows(sources)}
   where ${signedIn(ctx, user)}
     and ms.scope = ${quoteLiteral(scope)}
     and jsonb_typeof(ms.roles) = 'array'
-    and jsonb_array_length(ms.roles) > 0${narrow}${sourceFilters(ctx, scope, user, void 0, sourcesKeep(sources))}`, sources, user);
+    and jsonb_array_length(ms.roles) > 0${roles === void 0 ? "" : `\n    and ms.roles ?| ${roles}`}${narrow}${sourceFilters(ctx, scope, user, void 0, sourcesKeep(sources))}`, sources, user);
 	}
 	const mapped = scopeTable(ctx, scope);
 	if (mapped === void 0) return sqlBody(`  select null::${type} where false -- no ${scope} memberships table configured`);
@@ -2344,6 +2374,7 @@ ${sourceRows(sources)}
 		`  where ${memberColumn(table.user)} = ${user}`,
 		`    and ${role.through === void 0 && !role.lateral ? memberColumn(role.column) : role.sql} is not null`
 	];
+	if (roles !== void 0) lines.push(`    and (${role.through === void 0 && !role.lateral ? memberColumn(role.column) : role.sql})::text = any(${roles})`);
 	const narrow = keyed ? keyTenantSql(ctx, tenantColumn === void 0 ? void 0 : memberColumn(tenantColumn)) : void 0;
 	if (narrow !== void 0) lines.push(`    and ${narrow}`);
 	if (table.expiresAt !== void 0) {
@@ -2377,6 +2408,22 @@ ${functionBody(keyed)}
 ${grants}`;
 }
 /**
+* `member_<scope>_ids(p_roles text[])`: `member_<scope>_ids()` narrowed to
+* memberships holding one of `p_roles` by name, for `rls migrate`'s `role`
+* helpers. Generated only for a scope such a helper names.
+*/
+function memberRolesFunction(ctx, scope, type, anonExecute) {
+	const fn = qualified(ctx, memberIdsHelper(scope));
+	const body = memberBody(ctx, scope, type, "p_roles");
+	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 `create or replace function ${fn}(p_roles text[])
+returns setof ${type}
+${functionBody(body)}
+${grants}`;
+}
+/**
 * `member_<scope>_ids_for(p_user uuid)`: `member_<scope>_ids()` for a user the
 * caller names, read from the membership sources (or the mapped table) in
 * either mode, so a token hook can call it before any claim exists. Naming
@@ -2400,7 +2447,7 @@ revoke execute on function ${fn}(uuid) from public, anon, authenticated;`;
 function accessSql(ctx, scope, grantKey, column) {
 	const key = quoteLiteral(grantKey);
 	if (scope === "global") return `(select ${qualified(ctx, HELPERS.has)}(${key}))`;
-	if (column === void 0) throw new Error(`PermDock CLI: ${scope}-scoped grant needs definePolicy({ scopes.${scope} })`);
+	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}))`;
 }
 function userIdSql(ctx, anonExecute) {
@@ -2534,6 +2581,7 @@ revoke all on table ${ur} from anon, authenticated, public;`);
 		const type = scopeTypeOf(ctx, scope.name);
 		chunks.push(helperFunction(ctx, permittedIdsHelper(scope.name), `setof ${type}`, bodies.ids(scope.name), anon));
 		chunks.push(memberFunction(ctx, scope.name, type, anon));
+		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));
 	}
 	const forUser = forUserSql(ctx);
@@ -2620,12 +2668,12 @@ function requiresSql(ctx, key, resource) {
 }
 /** Postgres truncates an identifier past 63 bytes, which would merge two helpers. */
 function checkName(name) {
-	if (new TextEncoder().encode(name).length > 63) throw new Error(`PermDock CLI: the helper name ${name} is longer than 63 bytes; use a shorter scope name`);
+	if (new TextEncoder().encode(name).length > 63) throw configError(`PermDock CLI: the helper name ${name} is longer than 63 bytes; use a shorter scope name`);
 	return name;
 }
 function grantsFunction(ctx, grants, renamed, anonExecute) {
 	const fn = qualified(ctx, PERMISSION_HELPERS.grantKeys);
-	const map = Object.fromEntries([...grants].toSorted(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+	const map = Object.fromEntries([...grants].toSorted(byKey));
 	const current = Object.keys(renamed).length === 0 ? "p_permission" : `coalesce(${quoteLiteral(JSON.stringify(renamed))}::jsonb ->> p_permission, p_permission)`;
 	return `-- the grant keys a permission key reaches on one scope: its unconditional allows, with p_effect 'deny' every deny, and with 'conditioned-allow' or 'conditioned-deny' the allows or denies that carry a row condition
 create or replace function ${fn}(p_permission text, p_scope text, p_effect text default 'allow')
@@ -2712,7 +2760,7 @@ function permissionHelpersSql(ctx, grants, renamed, anonExecute) {
   ) g
   cross join lateral ${helper}(${user}g.grant_key) d(id)`;
 	const keysBody = (scope, bodies, filtered) => {
-		const rows = ["global", scope].flatMap((at) => Object.entries(grants.get(at) ?? {}).toSorted(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).flatMap(([key, effects]) => ["allow", "deny"].flatMap((effect) => effects[effect].map((grant) => `(${[
+		const rows = ["global", scope].flatMap((at) => Object.entries(grants.get(at) ?? {}).toSorted(byKey).flatMap(([key, effects]) => ["allow", "deny"].flatMap((effect) => effects[effect].map((grant) => `(${[
 			key,
 			at,
 			effect,
@@ -2802,4 +2850,848 @@ ${keysFunction(keysFor, `p_user ${user}, p_id ${type}, p_keys text[]`, keysBody(
 	return `${chunks.join("\n\n")}\n`;
 }
 //#endregion
-export { sqlFunctionNames as A, memberIdsHelper as B, apiKeysPlan as C, roleNames as D, collectGrants as E, hasMemberFor as F, scopeSources as G, permittedForHelper as H, linkHelper as I, activeUserSql as J, scopeTable as K, memberForHelper as L, graphHelper as M, graphSqlName as N, compileConditionSql as O, graphSqlText as P, memberForSources as R, apiKeyFields as S, breakGlassKey as T, permittedIdsHelper as U, memberRoleOf as V, restrictedHelper as W, connectPgPool as X, checkSuspension as Y, pgConnector as Z, globalRoleSource as _, accessSql as a, API_KEY_ALLOWS as b, capabilityAccessSql as c, memberColumn as d, sourceFilters as f, roleRows as g, membershipRows as h, requiresSql as i, CLOSURE as j, contextRefs as k, claimKeptLines as l, globalRoleRows as m, permissionKeysForHelper as n, helpersSql as o, sourcesKeep as p, activeRowSql as q, permittedByPermissionHelper as r, seedSql as s, permissionHelpersSql as t, disabledColumn as u, currentKeyExpr as v, breakGlassHolder as w, apiKeyAllowsCall as x, hasCustomRoleChecksFor as y, memberForTable as z };
+//#region src/cli/rls/ownership-names.ts
+/** Objects the ownership rules add next to the helpers. Names are part of the SQL contract. */
+const OWNERSHIP = {
+	canAssign: "permdock_can_assign",
+	canAssignFor: "permdock_can_assign_for",
+	canAssignAny: "permdock_can_assign_any",
+	canAssignAnyFor: "permdock_can_assign_any_for",
+	holders: "permdock_holders",
+	transferOnly: "permdock_transfer_only"
+};
+/** Objects `rls.assignments` adds. Names are part of the SQL contract. */
+const ASSIGNMENTS = {
+	custom: "permdock_can_assign_custom_role",
+	customFor: "permdock_can_assign_custom_role_for",
+	trigger: "permdock_assignment"
+};
+//#endregion
+//#region src/cli/rls/assignments.ts
+/** The client roles whose writes the assignment triggers check; any other role is a trusted path. */
+const CLIENT_ROLES = [
+	"anon",
+	"anonymous",
+	"authenticated"
+];
+/** The mapped membership tables, `rls.assignments.tables` and the global-roles table `rls.roles`. */
+function assignedTables(ctx) {
+	const out = [];
+	for (const { name } of ctx.scopes) {
+		const mapped = scopeTable(ctx, name);
+		if (mapped === void 0) continue;
+		out.push({
+			table: mapped.table.table,
+			scope: name,
+			id: mapped.column,
+			tenant: mapped.tenantColumn ?? mapped.column,
+			role: mapped.table.role,
+			user: mapped.table.user
+		});
+	}
+	if (ctx.roles !== void 0) out.push({
+		table: ctx.roles.table,
+		scope: "global",
+		role: ctx.roles.role ?? "role",
+		user: ctx.roles.user ?? "user_id"
+	});
+	for (const extra of ctx.assignments?.tables ?? []) {
+		const scope = resolveScope(ctx.scopes, extra.scope);
+		if (scope === void 0) throw configError(`PermDock CLI: rls.assignments.tables names scope '${extra.scope}', which the policy does not declare`);
+		if (scope !== ctx.scopes[0]?.name && extra.tenant === void 0) throw configError(`PermDock CLI: rls.assignments.tables entry ${extra.table} assigns at ${scope}, below the first scope: name its tenant column`);
+		out.push({
+			table: extra.table,
+			scope,
+			id: extra.id,
+			tenant: extra.tenant ?? extra.id,
+			role: extra.role,
+			...extra.user === void 0 ? {} : { user: extra.user }
+		});
+	}
+	return out;
+}
+/** The tables `rls.assignments.ownRole` refuses a caller's own rows on, by table key. */
+function ownRoleTables(ctx, tables) {
+	const own = ctx.assignments?.ownRole;
+	if (own === void 0) return /* @__PURE__ */ new Set();
+	if (own === "refuse") return new Set(tables.filter((entry) => entry.user !== void 0).map((entry) => qualifySqlTable(entry.table)));
+	const out = /* @__PURE__ */ new Set();
+	for (const [name, value] of Object.entries(own)) {
+		const entry = tables.find((table) => qualifySqlTable(table.table) === qualifySqlTable(name));
+		if (entry === void 0) throw configError(`PermDock CLI: rls.assignments.ownRole names ${name}, which no assignment trigger guards`);
+		if (value !== "refuse") throw configError(`PermDock CLI: rls.assignments.ownRole.${name} must be 'refuse'`);
+		if (entry.user === void 0) throw configError(`PermDock CLI: rls.assignments.ownRole names ${name}, which has no user column: set its user in rls.assignments.tables`);
+		out.add(qualifySqlTable(entry.table));
+	}
+	return out;
+}
+/**
+* The tables `rls.assignments` guards, schema-qualified: each scope's mapped
+* membership table, the global-roles table (`rls.roles`, else
+* `supabase.hook.roles`) and `rls.assignments.tables`. Empty without
+* `rls.assignments`.
+*/
+function guardedTables(config, scopes) {
+	const rls = config.rls;
+	if (rls?.assignments === void 0) return [];
+	const hook = config.supabase?.hook?.roles;
+	const roles = rls.roles ?? (hook === false ? void 0 : hook);
+	const tables = [
+		...scopes.flatMap((scope) => {
+			const mapped = memberForTable({
+				scopes,
+				...rls.memberships === void 0 ? {} : { memberships: rls.memberships }
+			}, scope.name);
+			return mapped === void 0 ? [] : [mapped.table];
+		}),
+		...roles === void 0 ? [] : [roles.table],
+		...(rls.assignments === true ? [] : rls.assignments.tables ?? []).map((entry) => entry.table)
+	];
+	return [...new Set(tables.map(qualifySqlTable))];
+}
+function isRoleList(role) {
+	return Array.isArray(role);
+}
+/** The role keys a row variable holds, one scalar per role source. */
+function rowRoles(entry, row) {
+	return (isRoleList(entry.role) ? entry.role : [entry.role]).map((part) => roleColumn(part, qualifySqlTable(entry.table), row, {
+		label: `rls.assignments ${entry.table} role`,
+		prefix: "PermDock CLI"
+	}).lookup);
+}
+/**
+* `permdock_can_assign_custom_role`: whether the signed-in caller may assign a
+* custom role of the tenant at the instance, by the checks the custom-role
+* write functions run on its stored definition.
+*/
+function canAssignCustomSql(ctx, forUser = false) {
+	const tenantType = tenantTypeOf(ctx);
+	const fn = qualified(ctx, forUser ? ASSIGNMENTS.customFor : ASSIGNMENTS.custom);
+	const perms = qualified(ctx, CUSTOM_ROLES.permissions);
+	const includes = qualified(ctx, CUSTOM_ROLES.includes);
+	const guard = qualified(ctx, forUser ? CUSTOM_ROLES.guardFor : CUSTOM_ROLES.guard);
+	const userParam = forUser ? "p_user uuid, " : "";
+	const userArg = forUser ? "uuid, " : "";
+	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" : ""}
+create or replace function ${fn}(${userParam}p_tenant ${tenantType}, p_scope text, p_scope_id text, p_role text)
+returns boolean
+language plpgsql
+stable
+security definer
+set search_path = ''
+as $$
+declare
+  v_scope_id text;
+  v_found boolean := false;
+begin
+  select true, c.scope_id into v_found, v_scope_id
+  from (
+    select c.scope_id from ${perms} c where ${stored}
+    union all
+    select c.scope_id from ${includes} c where ${stored}
+  ) c
+  order by c.scope_id nulls first
+  limit 1;
+  if not coalesce(v_found, false) then
+    return false;
+  end if;
+  perform ${guard}(${forUser ? "p_user, " : ""}p_tenant, p_scope, v_scope_id, p_role);
+  return true;
+exception
+  when insufficient_privilege or invalid_parameter_value then
+    return false;
+end;
+$$;
+${grants}`;
+}
+/**
+* The assignment triggers (\`rls.assignments\`): before a client role inserts,
+* updates or deletes a row that assigns a role, every role the old and new
+* row hold must be one the caller may assign at that instance, by
+* \`permdock_can_assign\` for a declared role and
+* \`permdock_can_assign_custom_role\` for a custom one. The functions run as
+* the invoker, so \`current_user\` tells a client write from a trusted one.
+*/
+function assignmentSql(ctx) {
+	const own = ctx.ownership;
+	if (ctx.assignments === void 0 || own === void 0 || own.assigns.length === 0) return "";
+	const canAssign = qualified(ctx, OWNERSHIP.canAssign);
+	const custom = ctx.customRoles !== void 0 && ctx.authorize === "database";
+	const declared = ctx.customRoles?.declared;
+	const tenantType = tenantTypeOf(ctx);
+	const chunks = [];
+	const clients = `current_user::text = any(array[${CLIENT_ROLES.map(quoteLiteral).join(", ")}])`;
+	const tables = assignedTables(ctx);
+	const ownRole = ownRoleTables(ctx, tables);
+	for (const entry of tables) {
+		const table = quoteQualified(entry.table);
+		const suffix = entry.table.replaceAll(/[^a-z0-9_]/gu, "_");
+		const fn = qualified(ctx, quoteIdent(`${ASSIGNMENTS.trigger}_${suffix}`));
+		const ownUser = entry.user !== void 0 && ownRole.has(qualifySqlTable(entry.table)) ? entry.user : void 0;
+		const ownCheck = (row, reason) => ownUser === void 0 ? "" : `    if ${row}.${quoteIdent(ownUser)}::text = (${subjectIdSql(ctx)})::text then
+      raise exception using
+        errcode = '42501',
+        message = 'permdock: the caller may not change their own roles',
+        hint = '${reason}';
+    end if;
+`;
+		const check = (row) => {
+			const id = entry.id === void 0 ? "null::text" : `${row}.${quoteIdent(entry.id)}::text`;
+			const customFn = qualified(ctx, ASSIGNMENTS.custom);
+			let allowed = `${canAssign}(v_role, ${id})`;
+			if (custom && declared !== void 0) {
+				const platform = `${customFn}(null, 'global', null, v_role)`;
+				allowed = entry.id === void 0 || entry.tenant === void 0 ? `case when v_role = any(${declaredArray(declared)}) then ${canAssign}(v_role, ${id}) else ${platform} end` : `case when v_role = any(${declaredArray(declared)}) then ${canAssign}(v_role, ${id}) when ${id} is null then ${platform} else ${customFn}(${row}.${quoteIdent(entry.tenant)}::${tenantType}, ${quoteLiteral(entry.scope)}, ${id}, v_role) end`;
+			}
+			return `    foreach v_role in array array[${rowRoles(entry, row).join(", ")}]::text[] loop
+      if v_role is not null and not coalesce(${allowed}, false) then
+        raise exception using
+          errcode = '42501',
+          message = 'permdock: the caller may not assign ' || v_role || ' in ' || coalesce(${id}, 'null'),
+          hint = 'not-assignable-by';
+      end if;
+    end loop;`;
+		};
+		const what = entry.id === void 0 ? "global roles" : `${entry.scope} roles`;
+		chunks.push(`-- ${entry.table}: a client role may write only the ${what} it may assign${ownUser === void 0 ? "" : ", and none on its own rows"}
+create or replace function ${fn}()
+returns trigger
+language plpgsql
+volatile
+set search_path = ''
+as $$
+declare
+  v_role text;
+begin
+  if not (${clients}) then
+    return coalesce(new, old);
+  end if;
+  if tg_op in ('UPDATE', 'DELETE') then
+${ownCheck("old", "self-demotion")}${check("old")}
+  end if;
+  if tg_op in ('INSERT', 'UPDATE') then
+${ownCheck("new", "not-assignable-by")}${check("new")}
+  end if;
+  return coalesce(new, old);
+end;
+$$;
+revoke execute on function ${fn}() from public, anon, authenticated;
+drop trigger if exists "permdock_assignment" on ${table};
+create trigger "permdock_assignment"
+  before insert or update or delete on ${table}
+  for each row execute function ${fn}();`);
+	}
+	return `${chunks.join("\n\n")}\n`;
+}
+//#endregion
+//#region src/cli/rls/ownership-triggers.ts
+function objectName(prefix, scope) {
+	return quoteIdent(`${prefix}_${scope}`);
+}
+/** Live holders of `roleExpr` in instance `idExpr`, with the same kind and expiry rules as the helpers. */
+function holdersSql(ctx, table, column, idExpr, role, into) {
+	const roleExpr = typeof role === "string" ? quoteLiteral(role) : role.expr;
+	const held = memberRoleOf(table, "m", "      ");
+	const filters = [`m.${quoteIdent(column)} = ${idExpr}`, `${held.sql} = ${roleExpr}`];
+	if (table.expiresAt !== void 0) {
+		const expires = memberColumn(table.expiresAt);
+		filters.push(`(${expires} is null or ${expires} > now())`);
+	}
+	const disabled = disabledColumn(table);
+	if (disabled !== void 0) filters.push(`${disabled} is null`);
+	const via = memberVia(table);
+	const kind = typeof role === "string" ? roleKindSql(ctx, role, via) : kindFilterSql(ctx, roleExpr, via);
+	if (kind !== void 0) filters.push(kind);
+	return `select count(distinct m.${quoteIdent(table.user)}) into ${into}
+      from ${quoteQualified(table.table)} m${held.join}
+      where ${filters.join("\n        and ")}`;
+}
+/**
+* `min` and `max` as a deferred constraint trigger: checked at commit, so a
+* transfer (demote one holder, promote another) passes in one transaction. An
+* instance with no memberships left is being torn down and skips `min`.
+*/
+function holdersTriggerSql(ctx, scope, table, column, counted) {
+	const fn = qualified(ctx, `${OWNERSHIP.holders}_${scope}`);
+	const col = quoteIdent(column);
+	const checks = counted.map((rule) => {
+		const lines = [`    select count(*) into v_total from ${quoteQualified(table.table)} m where m.${col} = v_key;`, `    ${holdersSql(ctx, table, column, "v_key", rule.role, "v_count")};`];
+		if (rule.min > 0) lines.push(`    if v_total > 0 and v_count < ${String(rule.min)} then
+      raise exception using
+        errcode = '23514',
+        message = ${quoteLiteral(`permdock: ${scope} `)} || v_id || ${quoteLiteral(` keeps at least ${String(rule.min)} ${rule.role}`)},
+        hint = 'last-holder';
+    end if;`);
+		if (rule.max !== void 0) lines.push(`    if v_count > ${String(rule.max)} then
+      raise exception using
+        errcode = '23514',
+        message = ${quoteLiteral(`permdock: ${scope} `)} || v_id || ${quoteLiteral(` has at most ${String(rule.max)} ${rule.role}`)},
+        hint = 'max-holders';
+    end if;`);
+		return lines.join("\n");
+	});
+	return `-- ${scope}: holder counts (min / max), checked at commit
+create or replace function ${fn}()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+  v_ids text[] := '{}';
+  v_id text;
+  v_key ${quoteQualified(table.table)}.${col}%type;
+  v_total bigint;
+  v_count bigint;
+begin
+  if tg_op in ('UPDATE', 'DELETE') then
+    v_ids := v_ids || old.${col}::text;
+  end if;
+  if tg_op in ('INSERT', 'UPDATE') then
+    v_ids := v_ids || new.${col}::text;
+  end if;
+  foreach v_id in array v_ids loop
+    continue when v_id is null;
+    v_key := v_id;
+${checks.join("\n")}
+  end loop;
+  return null;
+end;
+$$;
+drop trigger if exists ${objectName(OWNERSHIP.holders, scope)} on ${quoteQualified(table.table)};
+create constraint trigger ${objectName(OWNERSHIP.holders, scope)}
+  after insert or update or delete on ${quoteQualified(table.table)}
+  deferrable initially deferred
+  for each row execute function ${fn}();`;
+}
+/**
+* `transferOnly` as statement triggers over transition tables: a statement
+* that changes a role's holder count in an instance that had holders before
+* and still has some after is refused. Creating the first holder and removing
+* the last (which `min` guards) are not transfers.
+*/
+function transferTriggerSql(ctx, scope, table, column, roles) {
+	const fn = qualified(ctx, `${OWNERSHIP.transferOnly}_${scope}`);
+	const col = quoteIdent(column);
+	const list = `array[${roles.map(quoteLiteral).join(", ")}]::text[]`;
+	const rows = (alias, source, delta) => {
+		const role = memberRoleOf(table, alias);
+		return `select ${alias}.${col} as id, ${role.sql} as role, ${delta} as delta from ${source} ${alias}${role.join} where ${role.sql} = any(${list})`;
+	};
+	const loop = (source) => `    for v_change in
+      select c.id, c.role, sum(c.delta) as delta
+      from (${source}) c
+      group by c.id, c.role
+    loop
+      continue when v_change.delta = 0 or v_change.id is null;
+      ${holdersSql(ctx, table, column, "v_change.id", { expr: "v_change.role" }, "v_after")};
+      if v_after > 0 and v_after - v_change.delta > 0 then
+        raise exception using
+          errcode = '23514',
+          message = 'permdock: ' || v_change.role || ${quoteLiteral(` in ${scope} `)} || v_change.id || ' moves only by transfer',
+          hint = 'transfer-only';
+      end if;
+    end loop;`;
+	const inserted = rows("n", "permdock_new", "1");
+	const deleted = rows("o", "permdock_old", "-1");
+	const target = quoteQualified(table.table);
+	const trigger = (op) => {
+		const name = quoteIdent(`${OWNERSHIP.transferOnly}_${scope}_${op}`);
+		return `drop trigger if exists ${name} on ${target};
+create trigger ${name}
+  after ${op} on ${target}
+  referencing ${op === "insert" ? "new table as permdock_new" : op === "delete" ? "old table as permdock_old" : "old table as permdock_old new table as permdock_new"}
+  for each statement execute function ${fn}();`;
+	};
+	return `-- ${scope}: transfer-only roles (${roles.join(", ")}) keep their holder count per statement
+create or replace function ${fn}()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+  v_change record;
+  v_after bigint;
+begin
+  if tg_op = 'INSERT' then
+${loop(inserted)}
+  elsif tg_op = 'DELETE' then
+${loop(deleted)}
+  else
+${loop(`${inserted} union all ${deleted}`)}
+  end if;
+  return null;
+end;
+$$;
+${trigger("insert")}
+${trigger("update")}
+${trigger("delete")}`;
+}
+//#endregion
+//#region src/cli/rls/ownership-sources.ts
+/**
+* The membership sources holding scope `name`: `undefined` when there are
+* none, `'not-tables'` when one of them carries no table to put a trigger on.
+*/
+function holderSources(ctx, name) {
+	const sources = memberForSources(ctx, name);
+	if (sources.length === 0) return;
+	const held = [];
+	for (const source of sources) {
+		if (source.sql.holders === void 0) return "not-tables";
+		held.push({
+			table: source.sql.table,
+			holders: source.sql.holders
+		});
+	}
+	return held;
+}
+function indent(sql, by) {
+	return sql.replaceAll(/^/gmu, by);
+}
+/** Every source's rows of one instance, each compared with its own typed `v_key_<n>`. */
+function sourceRowsOf(scope, sources) {
+	return sources.map((source, index) => indent(source.holders.rows(scope, { id: `v_key_${String(index)}` }), "        ")).join("\n        union all\n");
+}
+function sourceKeys(sources) {
+	return {
+		declare: sources.map((source, index) => `  v_key_${String(index)} ${source.holders.idType};`).join("\n"),
+		assign: (value, by) => sources.map((_, index) => `${by}v_key_${String(index)} := ${value};`).join("\n")
+	};
+}
+function regclassOf(table) {
+	return `${quoteLiteral(quoteQualified(table))}::regclass`;
+}
+function sourceTables(sources) {
+	return [...new Set(sources.map((source) => quoteQualified(source.table)))];
+}
+/** `min` and `max` over membership sources: the same commit-time check as on a mapped table, counted over every source of the scope. */
+function sourceHoldersTriggerSql(ctx, scope, sources, counted) {
+	const fn = qualified(ctx, `${OWNERSHIP.holders}_${scope}`);
+	const keys = sourceKeys(sources);
+	const rows = sourceRowsOf(scope, sources);
+	const collect = sources.map((source) => `  if tg_relid = ${regclassOf(source.table)} then
+    if tg_op in ('UPDATE', 'DELETE') then
+      v_ids := v_ids || ${source.holders.id(scope, "old")};
+    end if;
+    if tg_op in ('INSERT', 'UPDATE') then
+      v_ids := v_ids || ${source.holders.id(scope, "new")};
+    end if;
+  end if;`);
+	const checks = counted.map((rule) => {
+		const filters = ["h.live", `h.role = ${quoteLiteral(rule.role)}`];
+		const kind = roleKindSql(ctx, rule.role, "h.via");
+		if (kind !== void 0) filters.push(kind);
+		const lines = [`    select count(distinct h.user_id) into v_count
+      from (
+${rows}
+      ) h
+      where ${filters.join("\n        and ")};`];
+		if (rule.min > 0) lines.push(`    if v_total > 0 and v_count < ${String(rule.min)} then
+      raise exception using
+        errcode = '23514',
+        message = ${quoteLiteral(`permdock: ${scope} `)} || v_id || ${quoteLiteral(` keeps at least ${String(rule.min)} ${rule.role}`)},
+        hint = 'last-holder';
+    end if;`);
+		if (rule.max !== void 0) lines.push(`    if v_count > ${String(rule.max)} then
+      raise exception using
+        errcode = '23514',
+        message = ${quoteLiteral(`permdock: ${scope} `)} || v_id || ${quoteLiteral(` has at most ${String(rule.max)} ${rule.role}`)},
+        hint = 'max-holders';
+    end if;`);
+		return lines.join("\n");
+	});
+	const triggers = sourceTables(sources).map((table) => `drop trigger if exists ${objectName(OWNERSHIP.holders, scope)} on ${table};
+create constraint trigger ${objectName(OWNERSHIP.holders, scope)}
+  after insert or update or delete on ${table}
+  deferrable initially deferred
+  for each row execute function ${fn}();`);
+	return `-- ${scope}: holder counts (min / max) over the membership sources, checked at commit
+create or replace function ${fn}()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+  v_ids text[] := '{}';
+  v_id text;
+${keys.declare}
+  v_total bigint;
+  v_count bigint;
+begin
+${collect.join("\n")}
+  foreach v_id in array v_ids loop
+    continue when v_id is null;
+${keys.assign("v_id", "    ")}
+    select count(*) into v_total
+      from (
+${rows}
+      ) h;
+${checks.join("\n")}
+  end loop;
+  return null;
+end;
+$$;
+${triggers.join("\n")}`;
+}
+function collectChangesSql(changed) {
+	return `      v_changes := v_changes || coalesce((select jsonb_agg(to_jsonb(c)) from (${changed}) c), '[]'::jsonb);`;
+}
+/** `transferOnly` over membership sources: each source table's statement triggers diff its transition tables, and the count after reads every source. */
+function sourceTransferTriggerSql(ctx, scope, sources, roles) {
+	const fn = qualified(ctx, `${OWNERSHIP.transferOnly}_${scope}`);
+	const keys = sourceKeys(sources);
+	const list = `array[${roles.map(quoteLiteral).join(", ")}]::text[]`;
+	const kind = kindFilterSql(ctx, "h.role", "h.via");
+	const changes = (source, from, delta) => `select h.id, h.role, ${delta} as delta from (${source.holders.rows(scope, { from }).replaceAll("\n", " ")}) h where h.role = any(${list})`;
+	const branches = sources.map((source) => `  if tg_relid = ${regclassOf(source.table)} then
+    if tg_op in ('INSERT', 'UPDATE') then
+${collectChangesSql(changes(source, "permdock_new", "1"))}
+    end if;
+    if tg_op in ('UPDATE', 'DELETE') then
+${collectChangesSql(changes(source, "permdock_old", "-1"))}
+    end if;
+  end if;`);
+	const triggers = sourceTables(sources).flatMap((table) => [
+		"insert",
+		"update",
+		"delete"
+	].map((op) => {
+		const name = quoteIdent(`${OWNERSHIP.transferOnly}_${scope}_${op}`);
+		return `drop trigger if exists ${name} on ${table};
+create trigger ${name}
+  after ${op} on ${table}
+  referencing ${op === "insert" ? "new table as permdock_new" : op === "delete" ? "old table as permdock_old" : "old table as permdock_old new table as permdock_new"}
+  for each statement execute function ${fn}();`;
+	}));
+	return `-- ${scope}: transfer-only roles (${roles.join(", ")}) keep their holder count per statement, over the membership sources
+create or replace function ${fn}()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+  v_changes jsonb := '[]'::jsonb;
+  v_change record;
+  v_after bigint;
+${keys.declare}
+begin
+${branches.join("\n")}
+  for v_change in
+    select x.id, x.role, sum(x.delta) as delta
+    from jsonb_to_recordset(v_changes) x(id text, role text, delta bigint)
+    group by x.id, x.role
+  loop
+    continue when v_change.delta = 0 or v_change.id is null;
+${keys.assign("v_change.id", "    ")}
+    select count(distinct h.user_id) into v_after
+      from (
+${sourceRowsOf(scope, sources)}
+      ) h
+      where h.live
+        and h.role = v_change.role${kind === void 0 ? "" : `\n        and ${kind}`};
+    if v_after > 0 and v_after - v_change.delta > 0 then
+      raise exception using
+        errcode = '23514',
+        message = 'permdock: ' || v_change.role || ${quoteLiteral(` in ${scope} `)} || v_change.id || ' moves only by transfer',
+        hint = 'transfer-only';
+    end if;
+  end loop;
+  return null;
+end;
+$$;
+${triggers.join("\n")}`;
+}
+function pairsSql(pairs) {
+	return `values ${pairs.map((pair) => `(${quoteLiteral(pair.assigner)}, ${quoteLiteral(pair.role)})`).join(", ")}`;
+}
+/**
+* Membership rows of the membership sources for scope `name`, each source's
+* `select` comparing its user column with a variable `user` names.
+*/
+function sourceRowsSql(sources, user) {
+	const keep = sources.some((source) => source.sql.keeps);
+	return sources.map((source) => source.sql.select(user(source), keep).replaceAll(/^/gmu, "        ")).join("\n        union all\n");
+}
+//#endregion
+//#region src/cli/rls/can-assign.ts
+/** Whether the signed-in user (or `p_user` in the `_for` form) holds, in instance `p_scope_id`, a role whose `assigns` lists `p_role`. */
+function canAssignSql(base, own, forUser = false) {
+	const ctx = forUser ? {
+		...base,
+		subjectId: "p_user",
+		tenants: "all"
+	} : base;
+	const fn = qualified(ctx, forUser ? OWNERSHIP.canAssignFor : OWNERSHIP.canAssign);
+	const parts = [];
+	const used = [];
+	const userOf = (source) => {
+		const index = used.includes(source) ? used.indexOf(source) : used.push(source) - 1;
+		return `v_user_${String(index)}`;
+	};
+	const global = own.assigns.filter((pair) => pair.scope === "global");
+	for (const [instance, pairs] of [["p_scope_id is not null", global.filter((pair) => pair.at !== "global")], ["p_scope_id is null", global.filter((pair) => pair.at === "global")]]) {
+		if (pairs.length === 0) continue;
+		if (ctx.authorize === "database") {
+			const ur = globalRoleRows(ctx);
+			const kind = globalKindFilterSql(ctx, ur.roleSql);
+			parts.push(`${instance} and exists (
+      select 1 from ${ur.from}
+      where ${ur.userSql} = ${subjectIdSql(ctx)}
+        and (${ur.roleSql}, p_role) in (${pairsSql(pairs)})${kind === void 0 ? "" : `\n        and ${kind}`}
+    )`);
+		} else {
+			const kind = globalKindFilterSql(ctx, "r.role");
+			parts.push(`${instance} and exists (
+      select 1 from ${roleRows(ctx)}
+      where (r.role, p_role) in (${pairsSql(pairs)})${kind === void 0 ? "" : `\n        and ${kind}`}
+    )`);
+		}
+	}
+	for (const { name } of ctx.scopes) {
+		const pairs = own.assigns.filter((pair) => pair.scope === name);
+		if (pairs.length === 0) continue;
+		const sources = scopeSources(ctx, name);
+		if (sources.length > 0) {
+			const kind = kindFilterSql(ctx, "r.role", "ms.via");
+			parts.push(`exists (
+      select 1
+      from (
+${sourceRowsSql(sources, userOf)}
+      ) ms
+      cross join lateral jsonb_array_elements_text(
+        case jsonb_typeof(ms.roles) when 'array' then ms.roles else '[]'::jsonb end
+      ) r(role)
+      where ms.scope = ${quoteLiteral(name)}
+        and ms.id = p_scope_id
+        and (r.role, p_role) in (${pairsSql(pairs)})${kind === void 0 ? "" : `\n        and ${kind}`}${sourceFilters(ctx, name, void 0, void 0, sourcesKeep(sources)).replaceAll("\n    and ", "\n        and ")}
+    )`);
+			continue;
+		}
+		if (ctx.authorize === "database") {
+			const mapped = scopeTable(ctx, name);
+			if (mapped === void 0) continue;
+			const { table, column } = mapped;
+			const role = memberRoleOf(table, "m", "      ");
+			const filters = [
+				`${memberColumn(table.user)} = ${subjectIdSql(ctx)}`,
+				`${memberColumn(column)}::text = p_scope_id`,
+				`(${role.sql}, p_role) in (${pairsSql(pairs)})`
+			];
+			if (table.expiresAt !== void 0) {
+				const expires = memberColumn(table.expiresAt);
+				filters.push(`(${expires} is null or ${expires} > now())`);
+			}
+			const disabled = disabledColumn(table);
+			if (disabled !== void 0) filters.push(`${disabled} is null`);
+			const kind = kindFilterSql(ctx, role.sql, memberVia(table));
+			if (kind !== void 0) filters.push(kind);
+			parts.push(`exists (
+      select 1 from ${quoteQualified(table.table)} m${role.join}
+      where ${filters.join("\n        and ")}
+    )`);
+		} else {
+			const kind = kindFilterSql(ctx, "r.role", "m ->> 'via'");
+			parts.push(`exists (
+      select 1 from ${membershipRows(ctx)}
+      where m ->> 'scope' = ${quoteLiteral(name)}
+        and m ->> 'id' = p_scope_id
+        and (r.role, p_role) in (${pairsSql(pairs)})
+        and case jsonb_typeof(m -> 'expires_at')
+          when 'number' then (m ->> 'expires_at')::numeric > extract(epoch from now())
+          else true
+        end${kind === void 0 ? "" : `\n        and ${kind}`}${claimKeptLines(ctx, "        ").map((line) => `\n${line}`).join("")}
+    )`);
+		}
+	}
+	const body = parts.length === 0 ? "false" : parts.join("\n    or ");
+	const language = used.length === 0 ? `language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select ${signedIn(ctx)} and (
+    ${body}
+  )
+$$;` : `language plpgsql
+stable
+security definer
+set search_path = ''
+as $$
+declare
+${used.map((source, index) => `  v_user_${String(index)} ${source.sql.userType} := ${subjectIdSql(ctx)};`).join("\n")}
+begin
+  return ${signedIn(ctx)} and (
+    ${body}
+  );
+end;
+$$;`;
+	if (forUser) {
+		const user = ctx.dialect === "supabase" ? "uuid" : "text";
+		return `-- who may assign, for a user the caller names: trusted SQL acting later for a stored user; no client role may execute it
+create or replace function ${fn}(p_user ${user}, p_role text, p_scope_id text)
+returns boolean
+${language}
+revoke execute on function ${fn}(${user}, text, text) from public, anon, authenticated;`;
+	}
+	return `-- who may assign: a held role whose assigns lists p_role, in instance p_scope_id (its scope or an ancestor's); a null p_scope_id assigns a global role, which only global assigners may
+create or replace function ${fn}(p_role text, p_scope_id text)
+returns boolean
+${language}
+revoke execute on function ${fn}(text, text) from public, anon;
+grant execute on function ${fn}(text, text) to authenticated;`;
+}
+/** Whether the helpers keep custom roles in tables, so assigning one is checked against its stored definition. */
+function assignsCustomRoles(ctx) {
+	return ctx.customRoles !== void 0 && ctx.authorize === "database";
+}
+/** Whether `permdock_can_assign_any_for` is written: every function it calls has a `_for` form. */
+function hasCanAssignAnyFor(ctx) {
+	return ctx.authorize === "database" && (!assignsCustomRoles(ctx) || hasCustomRoleChecksFor(ctx));
+}
+/**
+* `permdock_can_assign_any`: one check for a declared or a custom role, so
+* SQL that assigns roles calls one function: `permdock_can_assign` for a
+* declared role, `permdock_can_assign_custom_role` for a custom one. `p_scope`
+* `'global'` (no tenant, no instance) assigns a platform role.
+*/
+function canAssignAnySql(ctx, custom, forUser = false) {
+	const tenantType = tenantTypeOf(ctx);
+	const fn = qualified(ctx, forUser ? OWNERSHIP.canAssignAnyFor : OWNERSHIP.canAssignAny);
+	const declaredFn = qualified(ctx, forUser ? OWNERSHIP.canAssignFor : OWNERSHIP.canAssign);
+	const customFn = qualified(ctx, forUser ? ASSIGNMENTS.customFor : ASSIGNMENTS.custom);
+	const userType = ctx.dialect === "supabase" ? "uuid" : "text";
+	const userParam = forUser ? `p_user ${userType}, ` : "";
+	const userArg = forUser ? `${userType}, ` : "";
+	const user = forUser ? "p_user, " : "";
+	const declared = `${declaredFn}(${user}p_role, case when p_scope = 'global' then null else p_scope_id end)`;
+	const body = custom && ctx.customRoles !== void 0 ? `case
+    when p_role = any(${declaredArray(ctx.customRoles.declared)}) then ${declared}
+    when p_scope = 'global' then ${customFn}(${user}null, 'global', null, p_role)
+    else ${customFn}(${user}p_tenant, p_scope, p_scope_id, p_role)
+  end` : declared;
+	const grants = forUser ? `revoke execute on function ${fn}(${userArg}text, ${tenantType}, text, text) from public, anon, authenticated;` : `revoke execute on function ${fn}(text, ${tenantType}, text, text) from public, anon;
+grant execute on function ${fn}(text, ${tenantType}, text, text) to authenticated;`;
+	return `-- whether ${forUser ? "user p_user" : "the caller"} may assign p_role at instance p_scope_id of p_scope in tenant p_tenant, declared or custom (p_scope 'global' for a platform role)${forUser ? "; no client role may execute it" : ""}
+create or replace function ${fn}(${userParam}p_role text, p_tenant ${tenantType}, p_scope text, p_scope_id text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select coalesce(${body}, false)
+$$;
+${grants}`;
+}
+//#endregion
+//#region src/cli/rls/ownership.ts
+function roleScope(policy, scopes, name) {
+	const on = policy.rolesByName.get(name)?.on ?? findRole(policy.vocabulary.roles, name)?.on;
+	return typeof on === "string" ? resolveScope(scopes, on) : void 0;
+}
+function isGlobalRole(policy, name) {
+	const binding = policy.rolesByName.get(name);
+	if (binding !== void 0) return binding.on === void 0;
+	const leaf = findRole(policy.vocabulary.roles, name);
+	return leaf !== void 0 && leaf.on === void 0;
+}
+/** The rules `rls generate` enforces; `undefined` when no role declares one. */
+function ownershipRules(policy, scopes) {
+	const kinds = {};
+	const assigns = [];
+	const counted = [];
+	for (const binding of policy.roles) {
+		const scope = roleScope(policy, scopes, binding.name);
+		if (binding.for !== void 0) kinds[binding.name] = binding.for;
+		const assigner = scope ?? (binding.on === void 0 ? "global" : void 0);
+		for (const target of binding.assigns ?? []) {
+			const at = roleScope(policy, scopes, target);
+			if (assigner !== void 0 && at !== void 0 && (assigner === "global" || scopeChain(scopes, at).includes(assigner))) assigns.push({
+				assigner: binding.name,
+				scope: assigner,
+				role: target,
+				at
+			});
+			else if (assigner === "global" && isGlobalRole(policy, target)) assigns.push({
+				assigner: binding.name,
+				scope: "global",
+				role: target,
+				at: "global"
+			});
+		}
+		const min = binding.min ?? 0;
+		const transferOnly = binding.transferOnly === true;
+		if (scope !== void 0 && (min > 0 || binding.max !== void 0 || transferOnly)) counted.push(binding.max === void 0 ? {
+			role: binding.name,
+			scope,
+			min,
+			transferOnly
+		} : {
+			role: binding.name,
+			scope,
+			min,
+			max: binding.max,
+			transferOnly
+		});
+	}
+	if (Object.keys(kinds).length === 0 && assigns.length === 0 && counted.length === 0) return;
+	return {
+		kinds,
+		assigns,
+		counted
+	};
+}
+/**
+* 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.
+*/
+function ownershipSql(ctx) {
+	const own = ctx.ownership;
+	if (own === void 0) return "";
+	const chunks = [];
+	const skipped = ctx.skipOwnershipTriggers;
+	for (const { name } of ctx.scopes) {
+		const counted = own.counted.filter((rule) => rule.scope === name);
+		if (counted.length === 0) continue;
+		if (skipped === "all" || skipped?.includes(name) === true) {
+			chunks.push(`-- ${name}: rls.ownershipTriggers leaves out the triggers, so min, max and transferOnly are checked only by decideRoleChange`);
+			continue;
+		}
+		const transfer = counted.filter((rule) => rule.transferOnly).map((rule) => rule.role);
+		const mapped = scopeTable(ctx, name);
+		if (mapped === void 0) {
+			const sources = holderSources(ctx, name);
+			if (sources === void 0) chunks.push(`-- ${name}: no memberships table configured, so min, max and transferOnly are checked only by decideRoleChange`);
+			else if (sources === "not-tables") chunks.push(`-- ${name}: a membership source is not a table, so min, max and transferOnly are checked only by decideRoleChange`);
+			else {
+				chunks.push(sourceHoldersTriggerSql(ctx, name, sources, counted));
+				if (transfer.length > 0) chunks.push(sourceTransferTriggerSql(ctx, name, sources, transfer));
+			}
+			continue;
+		}
+		chunks.push(holdersTriggerSql(ctx, name, mapped.table, mapped.column, counted));
+		if (transfer.length > 0) chunks.push(transferTriggerSql(ctx, name, mapped.table, mapped.column, transfer));
+	}
+	if (own.assigns.length > 0) {
+		chunks.push(canAssignSql(ctx, own));
+		if (ctx.authorize === "database") chunks.push(canAssignSql(ctx, own, true));
+		const custom = assignsCustomRoles(ctx);
+		if (custom) {
+			chunks.push(canAssignCustomSql(ctx));
+			if (hasCustomRoleChecksFor(ctx)) chunks.push(canAssignCustomSql(ctx, true));
+		}
+		chunks.push(canAssignAnySql(ctx, custom));
+		if (hasCanAssignAnyFor(ctx)) chunks.push(canAssignAnySql(ctx, custom, true));
+	}
+	return chunks.length === 0 ? "" : `${chunks.join("\n\n")}\n`;
+}
+//#endregion
+export { activeUserSql as $, collectGrants as A, hasPermittedUsers as B, byKey as C, apiKeysPlan as D, apiKeyFields as E, CLOSURE as F, memberIdsHelper as G, memberForHelper as H, graphHelper as I, permittedIdsHelper as J, memberRoleOf as K, graphSqlName as L, compileConditionSql as M, contextRefs as N, breakGlassHolder as O, sqlFunctionNames as P, activeRowSql as Q, graphSqlText as R, byCodeUnit as S, apiKeyAllowsCall as T, memberForSources as U, linkHelper as V, memberForTable as W, scopeSources as X, restrictedHelper as Y, scopeTable as Z, capabilityAccessSql as _, guardedTables as a, currentKeyExpr as b, PERMISSION_HELPERS as c, permissionKeysForHelper as d, checkSuspension as et, permittedByPermissionHelper as f, seedSql as g, helpersSql as h, assignmentSql as i, roleNames as j, breakGlassKey as k, checkName as l, accessSql as m, ownershipSql as n, ASSIGNMENTS as o, requiresSql as p, permittedForHelper as q, holderSources as r, OWNERSHIP as s, ownershipRules as t, permissionHelpersSql as u, globalRoleRows as v, API_KEY_ALLOWS as w, rolesTableScope as x, globalRoleSource as y, hasMemberFor as z };