permdock 0.6.0 → 0.7.0

package/dist/{rls-DTvYd-lI.js → rls-CxBZb4rZ.js}

@@ -1,30 +1,30 @@
 import { t as compact } from "./compact-CAf557ZB.js";
-import { c as listPermissions, u as renamedKeys } from "./permission-registry-Br4jSNVi.js";
+import { c as listPermissions, u as renamedKeys } from "./permission-registry-DpPtSKNZ.js";
 import { i as dateAt } from "./time-DkWjdL98.js";
-import { d as scopeList, o as resolveScope } from "./scopes-CUPSjo9q.js";
-import { o as flattenGrantee, v as listRoles } from "./grantee-hxrUsbpM.js";
-import { p as scopeField } from "./tenancy-DN2QAx9z.js";
-import { a as describeError, i as configError, o as exitCodeOfError, u as usageResult } from "./errors-CWTY6uih.js";
+import { p as scopeField } from "./tenancy-CmeBQ6Nv.js";
+import { a as describeError, i as configError, o as exitCodeOfError, u as usageResult } from "./errors-DpP_U6Bf.js";
 import { t as policyRowConditionKeys } from "./row-conditions-h2HythXQ.js";
-import { c as requirePolicy } from "./load-DFS_ry0W.js";
-import "./budget-NbEtbJC_.js";
-import { i as qualifySqlTable, r as escapeSqlIdent, u as sqlTextArray } from "./sql-B5T1IL83.js";
-import { l as roleColumn } from "./sources-vs5dGOsS.js";
-import { t as policyFromCatalog } from "./policy-from-catalog-C2gMa2Dj.js";
+import { o as sqlFiles } from "./files-D_JIzUrP.js";
+import { c as requirePolicy } from "./load-DxroEzH1.js";
+import { i as qualifySqlTable, r as escapeSqlIdent } from "./sql-B96movIM.js";
+import "./sources-B-zYB4GS.js";
+import { t as policyFromCatalog } from "./policy-from-catalog-DFWYkNdu.js";
 import { t as beforeFirst } from "./text-BMFRfBqc.js";
 import { i as INDEXES_MARKER, n as GRANTS_MARKER, o as SEEDS_MARKER, t as BACKFILL_MARKER } from "./markers-C6joDI3o.js";
-import { i as requirePeer, n as packageManagerOf, t as addLine } from "./peer-C8swJ2GH.js";
+import { i as requirePeer, n as packageManagerOf, t as addLine } from "./peer-12Q5I_RH.js";
 import { t as POLICY_NOT_PUBLISHED } from "./problem-types-CJ2325SZ.js";
-import { t as fetchProjectPolicy } from "./pull-jEwbf80J.js";
-import { a as isSeedsDirectory, c as parseSplit, d as seedsMigration, f as writeOutputFiles, l as partPath, n as dataMigrationFile, r as driftOf, u as pgDeltaPath } from "./output-files-DhRBBE4n.js";
-import { c as approvalsSql, d as resolveAuthorize, h as schemasRefusal, l as parseRbacAuthorize, m as resolveSchemas, o as supabaseHookSql, p as isSupabaseSchemas, s as permissionHoldersSql, t as grantsLabel, u as rbacScaffold } from "./supabase-hook-BMoEhZir.js";
-import { C as parseMembershipsFlag, E as scopeTypeOf, F as quoteQualified, I as quoteTable, M as qualified, N as quoteIdent$1, O as tenantTypeOf, P as quoteLiteral, _ as subjectClaimJsonSql, a as customRolesOn, c as SESSION_LIVE_HELPER, g as sessionLiveHelperSql, r as HELPERS, t as CUSTOM_ROLES, y as subjectIdSql } from "./shared-BAK8t4Uo.js";
-import { a as splitUndiffed } from "./deciding-columns-Sq12mEA6.js";
-import { a as readOnlyActorKinds, c as branchClauses, d as connectPgPool, i as orSql, n as actorMayWriteSql, o as readOnlyActorPolicies, r as assemblePolicies, t as ACTOR_MAY_WRITE } from "./policies-DP2nqRoF.js";
-import { A as collectGrants, C as byKey, D as apiKeysPlan, G as memberIdsHelper, I as graphHelper, J as permittedIdsHelper, L as graphSqlName, O as breakGlassHolder, S as byCodeUnit, X as scopeSources, Z as scopeTable, b as currentKeyExpr, et as checkSuspension, f as permittedByPermissionHelper, g as seedSql, h as helpersSql, i as assignmentSql, j as roleNames, k as breakGlassKey, m as accessSql, n as ownershipSql, t as ownershipRules, u as permissionHelpersSql, x as rolesTableScope } from "./ownership-DqaJNJPn.js";
-import { _ as indexesSql, a as graphSql, c as callsHelper, g as indexTargets, h as COLUMNS_SQL, i as graphPlan, l as helperCallKeys, m as tableFor, n as runRlsVerify, o as HELPER_TABLES, p as compileGrants, r as closureDepths, v as pruneIndexTargets, y as readTableIndexFacts } from "./verify-BaAKx7t6.js";
-import { a as fieldViewsSql, i as fieldViews, n as columnGrantSql, o as rowBranches, r as columnRevokeSql } from "./fields-OYG_JR78.js";
-import { t as supautilsRejections } from "./supautils-B6HYL9eL.js";
+import { t as fetchProjectPolicy } from "./pull-CN5OLxrF.js";
+import { n as MIGRATION_DIRS } from "./constants-DcJABbLW.js";
+import { a as isSeedsDirectory, c as parseSplit, d as seedsMigration, f as writeOutputFiles, l as partPath, n as dataMigrationFile, r as driftOf, u as pgDeltaPath } from "./output-files-CCMdcFWb.js";
+import { b as rbacScaffold, c as approvalsSql, d as resolveSchemas, f as schemasRefusal, o as supabaseHookSql, p as declarativeSql, s as permissionHoldersSql, t as grantsLabel, u as isSupabaseSchemas, y as parseRbacAuthorize } from "./supabase-hook-Dg0SrQWR.js";
+import { A as quoteQualified, D as qualified$1, F as scopeTypeOf, O as quoteIdent$1, _ as subjectClaimJsonSql, c as SESSION_LIVE_HELPER, g as sessionLiveHelperSql, j as quoteTable, k as quoteLiteral, r as HELPERS, t as CUSTOM_ROLES, y as subjectIdSql } from "./shared-fMKOv8hP.js";
+import { D as byKey, F as collectGrants, H as graphHelper, N as breakGlassHolder, P as breakGlassKey, Z as memberIdsHelper, _ as seedSql, a as assignmentSql, d as permissionHelpersSql, et as permittedIdsHelper, g as helpersSql, h as accessSql, n as ownershipSql, nt as scopeSources, p as permittedByPermissionHelper, rt as scopeTable } from "./ownership-Z2LpxsGa.js";
+import { a as splitUndiffed } from "./deciding-columns-DRo2QM6E.js";
+import { a as readOnlyActorKinds, d as connectPgPool, n as actorMayWriteSql, o as readOnlyActorPolicies, r as assemblePolicies, t as ACTOR_MAY_WRITE } from "./policies-B2lZIurj.js";
+import { C as INDEX_COLUMNS_SQL, D as readTableIndexFacts, E as pruneIndexTargets, S as COLUMNS_SQL, T as indexesSql, a as graphSql, b as compileGrants, c as verifyResult, d as tableNames, g as helperCallKeys, h as callsHelper, n as runRlsVerify, o as rlsFinding, p as HELPER_TABLES, s as verifyIgnores, w as indexTargets, x as tableFor } from "./verify-pe8rL_Qw.js";
+import { a as fieldViewsSql, i as fieldViews, n as columnGrantSql, o as rowBranches, r as columnRevokeSql } from "./fields-ClcQLrVc.js";
+import { a as generateOptions, c as buildContext, i as rowHelpersSql, l as DROPPED_LIST, n as inheritTargets, o as isRefusal, r as levelKeys, s as splitsPart, t as supautilsRejections, u as rebuildPlan } from "./supautils-MESd81bF.js";
+import { readFileSync } from "node:fs";
 import { basename, delimiter, join } from "node:path";
 import { spawn } from "node:child_process";
 //#region src/cli/rls/advisors.ts
@@ -159,142 +159,160 @@ async function runRlsAdvisors(input) {
 	};
 }
 //#endregion
-//#region src/cli/rls/generate-context.ts
-/** The scopes an `rls.migrate` `role` helper names, so `rls generate` writes their role-filtered member helper. */
-function roleMemberScopesOf(migrate) {
-	const scopes = [...new Set(Object.values(migrate?.helpers ?? {}).flatMap((helper) => helper.form === "role" ? [helper.scope] : []))].toSorted();
-	return scopes.length === 0 ? {} : { roleMemberScopes: scopes };
-}
-/** `rls.customRoleWrites.requires` as permission keys, or why it names none. */
-function writeRequirement(policy, requires) {
-	if (requires === void 0) return {};
-	const leaves = listPermissions(policy.permissions);
-	const keys = requires === "manageRoles" ? leaves.filter((leaf) => leaf.meta.manageRoles === true).map((leaf) => leaf.key) : [...requires];
-	if (keys.length === 0) return { error: requires === "manageRoles" ? "rls.customRoleWrites.requires is 'manageRoles', but no permission declares meta.manageRoles" : "rls.customRoleWrites.requires names no permission" };
-	const known = new Set(leaves.map((leaf) => leaf.key));
-	const unknown = keys.filter((key) => !known.has(key));
-	if (unknown.length > 0) return { error: `rls.customRoleWrites.requires names undeclared permissions: ${unknown.join(", ")}` };
-	return { keys: [...new Set(keys)].toSorted() };
-}
-/** Declared role names, and those a tenant admin may compose into custom roles. */
-function customRoleNames(policy, requires) {
-	const declared = [...roleNames(policy)].toSorted();
-	const assignable = declared.filter((name) => policy.rolesByName.get(name)?.assignable ?? listRoles(policy.vocabulary.roles).some((leaf) => leaf.key === name && leaf.assignable));
-	const renamed = renamedKeys(policy.vocabulary.permissions);
-	const leaves = listPermissions(policy.permissions);
-	const manage = leaves.filter((leaf) => leaf.meta.manageRoles === true).map((leaf) => leaf.key);
-	return {
-		declared,
-		assignable,
-		...renamed.size === 0 ? {} : { renamed: Object.fromEntries(renamed) },
-		permissions: leaves.map((leaf) => leaf.key).toSorted(),
-		...manage.length === 0 ? {} : { manage: manage.toSorted() },
-		...requires === void 0 ? {} : { requires },
-		...policy.levels === void 0 ? {} : { levels: true }
-	};
+//#region src/cli/rls/bindings.ts
+/**
+* The table each resource with row policies binds to. With `helpersOnly`,
+* a resource `rls.tables` does not name has no table and no binding.
+*/
+function tableBindings(resources, tables, helpersOnly) {
+	const out = [];
+	for (const resource of [...new Set(resources)].toSorted()) {
+		const named = tables !== void 0 && Object.hasOwn(tables, resource);
+		if (helpersOnly && !named) continue;
+		out.push({
+			resource,
+			table: qualifySqlTable(tableFor(resource, tables)),
+			inferred: !named
+		});
+	}
+	return out;
 }
-function skippedOwnershipTriggers(triggers, scopes) {
-	if (triggers === false) return "all";
-	return Object.keys(triggers).map((key) => {
-		const name = resolveScope(scopes, key);
-		if (name === void 0) throw configError(`PermDock CLI: rls.ownershipTriggers.${key} names a scope the policy does not declare`);
-		return name;
-	});
+/** The generate notes for `bindings`: the inferred ones, and where to see them all. */
+function bindingNotes(bindings, withDatabase) {
+	const inferred = bindings.filter((binding) => binding.inferred);
+	if (inferred.length === 0) return [];
+	return [`table bindings (no rls.tables entry, so the table is named after the resource): ${inferred.map((binding) => `${binding.resource} -> ${binding.table}`).join(", ")}${withDatabase ? "" : "; run permdock rls explain, or generate with --db-url-stdin, to check each table exists"}`];
 }
-/** The SQL context every emitter reads, from the flags, `rls` config and the policy. */
-function buildContext(input, policy, options) {
-	const rls = input.config.rls;
-	const memberships = parseMembershipsFlag(input.memberships) ?? rls?.memberships;
-	if (input.rbac && input.dialect !== "supabase") return { refusal: `rls generate --rbac supabase needs --dialect supabase (got ${input.dialect})` };
-	const schema = input.rbacSchema ?? rls?.schema ?? rls?.rbac?.schema ?? "permdock";
-	const authorize = resolveAuthorize(input.config, {
-		authorize: input.authorize,
-		rbac: input.rbac,
-		memberships
-	});
-	const memberSources = rls?.membershipSources ?? input.config.supabase?.hook?.memberships;
-	const sources = authorize === "database" ? memberSources : void 0;
-	const scopes = scopeList(policy.scopes);
-	const suspension = checkSuspension(rls?.suspension, scopes);
-	const hookRoles = input.config.supabase?.hook?.roles;
-	const roles = rls?.roles ?? (hookRoles === false ? void 0 : hookRoles);
-	if (roles !== void 0 && input.rbac) return { refusal: "rls generate --rbac supabase creates its own user_roles (user_id, role app_role); drop rls.roles (or supabase.hook.roles) or the --rbac flag" };
-	const requires = writeRequirement(policy, rls?.customRoleWrites?.requires);
-	if (requires.error !== void 0) return { refusal: requires.error };
-	const readers = rls?.trustedReaders;
-	if (readers !== void 0 && (!Array.isArray(readers) || !readers.every((name) => typeof name === "string" && name !== ""))) return { refusal: "rls.trustedReaders must list Postgres role names, such as ['service_role']" };
-	const ownership = ownershipRules(policy, scopes);
-	const graph = graphPlan(policy);
-	const apiKeys = apiKeysPlan(rls?.apiKeys, new Set(roleNames(policy)), Object.fromEntries(renamedKeys(policy.vocabulary.permissions)));
-	return {
-		ctx: {
-			dialect: input.dialect,
-			scopes,
-			tenantClaim: rls?.tenantClaim ?? "tenant_id",
-			...roleMemberScopesOf(rls?.migrate),
-			...rls?.roleValues === void 0 ? {} : { roleValues: rls.roleValues },
-			...rls?.tenants === "all" ? { tenants: "all" } : {},
-			gucPrefix: input.gucPrefix ?? rls?.gucPrefix ?? "app",
-			...rls?.actions === void 0 ? {} : { actions: rls.actions },
-			inlineFunctions: input.inlineFunctions || rls?.inlineFunctions === true,
-			schema,
-			authorize,
-			roleClaim: rls?.roleClaim ?? "user_role",
-			tenantType: input.tenantType ?? rls?.tenantType ?? "uuid",
-			...rls?.teamType === void 0 ? {} : { teamType: rls.teamType },
-			...rls?.scopeTypes === void 0 ? {} : { scopeTypes: rls.scopeTypes },
-			...memberships === void 0 ? {} : { memberships },
-			...sources === void 0 || sources.length === 0 ? {} : { sources },
-			...memberSources === void 0 || memberSources.length === 0 ? {} : { memberSources },
-			...suspension === void 0 ? {} : { suspension },
-			...roles === void 0 ? {} : { roles },
-			...input.customRoles === true || customRolesOn(rls) ? { customRoles: {
-				...customRoleNames(policy, requires.keys),
-				...rls?.customRoleWrites?.roles === void 0 ? {} : { table: rls.customRoleWrites.roles }
-			} } : {},
-			...input.capabilities === true || rls?.capabilities === true ? { capabilities: true } : {},
-			...apiKeys === void 0 ? {} : { apiKeys },
-			...rls?.anonymousSignIns === "deny" ? { anonymousSignIns: "deny" } : {},
-			...ownership === void 0 ? {} : { ownership },
-			...rls?.ownershipTriggers === void 0 ? {} : { skipOwnershipTriggers: skippedOwnershipTriggers(rls.ownershipTriggers, scopes) },
-			...rls?.assignments === void 0 ? {} : { assignments: rls.assignments === true ? { tables: [] } : {
-				tables: rls.assignments.tables ?? [],
-				...rls.assignments.ownRole === void 0 ? {} : { ownRole: rls.assignments.ownRole }
-			} },
-			...options.fieldsMode === void 0 ? {} : { fields: options.fieldsMode },
-			...graph.size === 0 ? {} : { graph: {
-				closures: closureDepths(graph),
-				resources: policy.resources,
-				...rls?.tables === void 0 ? {} : { tables: rls.tables }
-			} }
-		},
-		graph,
-		ownership,
-		schema,
-		authorize
-	};
+/**
+* The generate notes for the bindings whose table no project SQL file
+* creates. A project with no `create table` in those files gets none: its
+* schema lives elsewhere (an ORM, another repository).
+*/
+function unknownTableNotes(bindings, created) {
+	if (created.size === 0) return [];
+	return bindings.filter((binding) => !created.has(binding.table) && !created.has(binding.table.toLowerCase())).map((binding) => `resource ${binding.resource} is bound to ${binding.table}, which no SQL file in the migration or schema folders creates; name its table in rls.tables, or set rls.tables.${binding.resource}: false when it has none`);
+}
+/** The inferred bindings whose table `facts` shows missing. */
+function missingBindings(bindings, columns) {
+	return bindings.filter((binding) => binding.inferred && columns[binding.table] === void 0);
 }
 //#endregion
-//#region src/cli/rls/generate-options.ts
-function isRefusal(value) {
-	return "refusal" in value;
+//#region src/cli/rls/trigger-notes.ts
+const CREATE = /^create trigger\s+("[^"]+"|[\w$]+)[^;]*?\bon\s+("[^"]+"(?:\."[^"]+")?|[\w$.]+)/gmu;
+function unquote(name) {
+	return name.replaceAll("\"", "");
+}
+function reasonOf(name) {
+	if (name === "permdock_custom_role_name_guard") return "customRoleWrites.roles: a tenant role cannot take a declared or shared role's name";
+	if (name === "permdock_custom_role_cascade") return "customRoleWrites.roles: a rename or delete of a role carries its grants";
+	if (name.startsWith("permdock_sync_custom_role")) return "customRoles.from.sync: each write to the legacy table rebuilds the role's grants";
+	if (name.startsWith("permdock_holders") || name.startsWith("permdock_transfer_only")) return "ownershipTriggers; set rls.ownershipTriggers.<scope>: false to skip";
+	if (name === "permdock_assignment") return "assignments: a role assignment is checked against the caller's own roles";
+	if (name.startsWith("permdock_closure")) return "the relationship closure table follows its source table";
+	return "generated by rls generate";
+}
+/** The triggers `sql` creates, in order, each with the option behind it. */
+function generatedTriggers(sql) {
+	const found = [];
+	for (const match of sql.matchAll(CREATE)) {
+		const name = unquote(match.slice(1, 2).join(""));
+		const table = unquote(match.slice(2, 3).join(""));
+		found.push({
+			name,
+			table,
+			reason: reasonOf(name)
+		});
+	}
+	return found;
 }
-/** The checks that need no policy: `--fields` and `--revoke-columns`. */
-function generateOptions(input) {
-	const rls = input.config.rls;
-	const fieldsMode = input.fields ?? rls?.fields;
-	if (fieldsMode !== void 0 && fieldsMode !== "views") return { refusal: `rls generate --fields must be views (got ${fieldsMode})` };
-	const revokeColumns = input.revokeColumns === true || rls?.revokeColumns === true;
-	if (revokeColumns && fieldsMode === void 0) return { refusal: "rls generate --revoke-columns needs --fields views" };
+/** One generate note per trigger. */
+function triggerNotes(sql) {
+	return generatedTriggers(sql).map((trigger) => `generated trigger ${trigger.name} on ${trigger.table} (${trigger.reason})`);
+}
+//#endregion
+//#region src/cli/rls/explain.ts
+function holds(table) {
+	if (table.tenant === void 0) return ["global"];
+	return [
+		"tenant",
+		...table.shared === void 0 ? [] : ["shared"],
+		"global"
+	];
+}
+function explainRls(input) {
+	const { config, ctx, generated } = input;
+	const rls = config.rls;
+	const bindings = tableBindings(generated.compiled.rowColumns.map((item) => item.resource), tableNames(rls?.tables), generated.helpersOnly);
+	const sources = ctx.memberSources ?? ctx.sources ?? [];
+	const roles = rls?.customRoleWrites?.roles;
+	const wanted = rls?.rowHelpers;
+	const resources = wanted === void 0 ? [] : wanted === true ? [...new Set(generated.compiled.branches.flatMap((branch) => branch.resource === void 0 ? [] : [branch.resource]))].toSorted() : [...new Set(wanted)];
 	return {
-		fieldsMode,
-		revokeColumns
+		schema: input.schema,
+		authorize: input.authorize,
+		scopes: ctx.scopes.map((scope) => scope.within === void 0 ? {
+			name: scope.name,
+			key: scope.key ?? scope.name
+		} : {
+			name: scope.name,
+			key: scope.key ?? scope.name,
+			within: scope.within
+		}),
+		bindings: bindings.map((binding) => {
+			const via = ctx.vias?.[binding.resource];
+			return via === void 0 ? binding : Object.assign({}, binding, { via: `${via.helper} over ${via.table}.${via.column} (${binding.table}.${via.key})` });
+		}),
+		membershipSources: sources.map((source) => ({
+			table: source.sql.table,
+			select: source.sql.select("$1")
+		})),
+		...roles === void 0 ? {} : { customRoles: {
+			table: roles.table,
+			key: roles.key,
+			...roles.tenant === void 0 ? {} : { tenant: roles.tenant },
+			...roles.shared === void 0 ? {} : { shared: roles.shared },
+			...roles.skip === void 0 ? {} : { skip: roles.skip },
+			holds: holds(roles)
+		} },
+		rowHelpers: resources.map((resource) => ({
+			resource,
+			permissions: [...new Set(generated.compiled.branches.flatMap((branch) => branch.resource === resource && branch.coverage !== true ? [branch.permissionKey] : []))].toSorted()
+		})),
+		triggers: generatedTriggers(input.text)
 	};
 }
-/** Whether `--split` names `part`, which then leaves the helpers or the warnings. */
-function splitsPart(raw, part) {
-	const split = parseSplit(raw);
-	return typeof split !== "string" && split?.includes(part) === true;
+/** The text report of `explain`. */
+function describeExplain(explain) {
+	const lines = [
+		`schema ${explain.schema}, authorize ${explain.authorize}`,
+		`scopes: ${explain.scopes.map((scope) => `${scope.name} (${scope.key}${scope.within === void 0 ? "" : `, within ${scope.within}`})`).join(", ")}`,
+		"",
+		"table bindings:",
+		...explain.bindings.map((binding) => `  ${binding.resource} -> ${binding.table}${binding.inferred ? " (named after the resource; set rls.tables to change)" : ""}${binding.via === void 0 ? "" : ` via ${binding.via}`}${binding.exists === false ? " MISSING" : ""}`)
+	];
+	if (explain.membershipSources.length > 0) {
+		lines.push("", "membership sources:");
+		for (const source of explain.membershipSources) lines.push(`  ${source.table}`, `    ${source.select.replaceAll("\n", "\n    ")}`);
+	}
+	if (explain.customRoles !== void 0) {
+		const roles = explain.customRoles;
+		const columns = [
+			`key ${roles.key}`,
+			...roles.tenant === void 0 ? [] : [`tenant ${roles.tenant}`],
+			...roles.shared === void 0 ? [] : [`shared ${roles.shared}`],
+			...roles.skip === void 0 ? [] : [`skip ${roles.skip}`]
+		];
+		lines.push("", `custom roles: ${roles.table} (${columns.join(", ")}); holds ${roles.holds.join(", ")} roles`);
+	}
+	if (explain.rowHelpers.length > 0) {
+		lines.push("", "row helpers:");
+		for (const helper of explain.rowHelpers) lines.push(`  ${helper.resource}: ${helper.permissions.join(", ")}`);
+	}
+	if (explain.triggers.length > 0) {
+		lines.push("", "generated triggers:");
+		for (const trigger of explain.triggers) lines.push(`  ${trigger.name} on ${trigger.table} (${trigger.reason})`);
+	}
+	return lines.join("\n");
 }
 //#endregion
 //#region src/cli/rls/generate-output.ts
@@ -312,8 +330,8 @@ function moveUndiffed(sql, label, part) {
 }
 /** Why `--split` cannot be written for `mode`, or `undefined`. */
 function splitRefusal(mode, plan) {
-	const seedsWithoutOut = plan.split.includes("seeds") && plan.seedsOut === void 0;
-	const helpersWithoutSeeds = plan.split.includes("helpers") && !plan.split.includes("seeds");
+	const seedsWithoutOut = plan.split.includes("seeds") && plan.seedsOut === void 0 && !plan.noSeeds && !plan.seedView;
+	const helpersWithoutSeeds = plan.split.includes("helpers") && !plan.noSeeds && !plan.split.includes("seeds") && !plan.seedFunction && !plan.seedView;
 	switch (mode) {
 		case "pg-delta":
 			if (plan.explicitOut && !plan.placeholder) return `rls generate --split needs {part} in --out, or no --out for pg-delta's per-schema layout (got ${plan.outRel})`;
@@ -342,6 +360,7 @@ function outputFiles(plan) {
 	if (split === void 0) {
 		if (input.grantsOut !== void 0) return "rls generate --grants-out needs --split with the helpers or hook part";
 		if (input.seedsOut !== void 0) return "rls generate --seeds-out needs --split with the seeds part";
+		if (input.noSeeds === true) return "rls generate --no-seeds needs --split: without it the seeds are part of the one file";
 		return [{
 			part: "rls",
 			rel: plan.outRel,
@@ -358,11 +377,15 @@ function outputFiles(plan) {
 		explicitOut: input.out !== void 0,
 		outRel: plan.outRel,
 		grantsOut: input.grantsOut,
-		seedsOut: input.seedsOut
+		seedsOut: input.seedsOut,
+		noSeeds: input.noSeeds === true,
+		seedFunction: input.config.rls?.seeds === "function",
+		seedView: input.config.rls?.seeds === "view"
 	});
 	if (refused !== void 0) return refused;
 	const at = (part, schema = plan.schema) => pgDelta === void 0 || placeholder ? partPath(plan.outRel, part) : pgDeltaPath(pgDelta.schemaDir, part, schema);
 	if (input.grantsOut !== void 0 && !split.includes("hook") && !split.includes("helpers")) return "rls generate --grants-out needs the helpers or hook part in --split";
+	if (input.noSeeds === true && input.seedsOut !== void 0) return "rls generate --no-seeds and --seeds-out exclude each other: drop one";
 	if (input.seedsOut !== void 0 && !split.includes("seeds")) return "rls generate --seeds-out needs the seeds part in --split";
 	if (split.includes("hook") && input.config.supabase?.hook === void 0) return "rls generate --split hook needs supabase.hook in permdock.config.ts";
 	const sql = plan.sql();
@@ -393,6 +416,10 @@ function outputFiles(plan) {
 			break;
 		}
 		case "seeds": {
+			if (input.noSeeds === true) {
+				if (relocated !== void 0 && split.includes("policies")) return "rls generate --no-seeds cannot drop the seeds part under pg-delta with rls.realtime or rls.storage: their policies live in it";
+				break;
+			}
 			const out = input.seedsOut;
 			if (out !== void 0 && isSeedsDirectory(input.cwd, out)) {
 				const planned = seedsMigration(input.cwd, out, SEEDS_MARKER, seeds, input.io.now?.() ?? dateAt());
@@ -438,6 +465,12 @@ function outputFiles(plan) {
 		}
 		default: return part;
 	}
+	if (pgDelta !== void 0 && !placeholder) {
+		for (const [index, file] of files.entries()) if (file.part !== "seeds" || input.seedsOut === void 0) files[index] = {
+			...file,
+			text: declarativeSql(file.text)
+		};
+	}
 	if (input.grantsOut !== void 0) files.push({
 		part: "grants",
 		rel: input.grantsOut,
@@ -447,48 +480,6 @@ function outputFiles(plan) {
 }
 //#endregion
 //#region src/cli/rls/backfill.ts
-const PREFIX$1 = "PermDock CLI";
-/** A column of the roles-table row `r`. */
-function col(name) {
-	return `r.${quoteIdent$1(name)}`;
-}
-function schemaOf(table) {
-	return table.includes(".") ? beforeFirst(table, ".") : "public";
-}
-/** The roles-table column a reference joins on, after checking it points at `roles`. */
-function roleRef(role, table, roles, label) {
-	const pairs = Object.entries(role.on);
-	const [pair] = pairs;
-	if (pair === void 0 || pairs.length !== 1) throw configError(`${PREFIX$1}: ${label}.on must map exactly one column of ${table} to ${role.through}, for example { role_id: 'id' }`);
-	const through = role.through.includes(".") ? role.through : `${schemaOf(table)}.${role.through}`;
-	if (qualifySqlTable(through) !== qualifySqlTable(roles.table)) throw configError(`${PREFIX$1}: ${label}.through must be rls.customRoleWrites.roles.table (${roles.table}), got ${role.through}`);
-	if (role.column !== roles.key) throw configError(`${PREFIX$1}: ${label}.column must be rls.customRoleWrites.roles.key (${roles.key}), got ${role.column}`);
-	const [ref, id] = pair;
-	return {
-		ref,
-		id
-	};
-}
-/**
-* A legacy key as SQL the way `mapKey` maps it: `rls.migrate.keys`, then
-* `renamed`, then the longest `rls.migrate.prefixes` match, and a former key
-* read as its current key.
-*/
-function legacyKeySql(expr, migrate, renamed) {
-	const exact = new Map(Object.entries(renamed));
-	for (const [from, to] of Object.entries(migrate?.keys ?? {})) exact.set(from, to);
-	const prefixes = Object.entries(migrate?.prefixes ?? {}).toSorted(([a], [b]) => b.length - a.length || byCodeUnit(a, b));
-	const prefixed = prefixes.length === 0 ? expr : `(case ${prefixes.map(([from, to]) => `when left(${expr}, ${String(from.length)}) = ${quoteLiteral(from)} then ${quoteLiteral(to)} || substr(${expr}, ${String(from.length + 1)})`).join(" ")} else ${expr} end)`;
-	const mapped = exact.size === 0 ? prefixed : `(case ${expr} ${[...exact.entries()].toSorted(byKey).map(([from, to]) => `when ${quoteLiteral(from)} then ${quoteLiteral(to)}`).join(" ")} else ${prefixed} end)`;
-	const renames = Object.entries(renamed).toSorted(byKey);
-	return currentKeyExpr(renames, mapped);
-}
-function sourceSql(source, table, label) {
-	return roleColumn(source, table, "x", {
-		label,
-		prefix: PREFIX$1
-	}).lookup;
-}
 /**
 * The `--backfill-out` migration: every custom role in the application's
 * roles table that has no rows in `custom_role_permissions` or
@@ -498,73 +489,10 @@ function sourceSql(source, table, label) {
 * nothing, so a role edited after the copy keeps its edits.
 */
 function backfillSql(ctx, from, migrate) {
-	const custom = ctx.customRoles;
-	const root = ctx.scopes[0]?.name;
-	if (custom === void 0 || root === void 0) throw configError(`${PREFIX$1}: rls.customRoles.from needs custom roles on`);
-	if (ctx.authorize !== "database") throw configError(`${PREFIX$1}: rls.customRoles.from needs database mode; in jwt mode custom roles ride the token, so build the grants claim with customRoleClaim`);
-	const roles = custom.table;
-	if (roles === void 0) throw configError(`${PREFIX$1}: rls.customRoles.from needs rls.customRoleWrites.roles, the roles table each row belongs to`);
-	const leveled = custom.levels === true;
-	if (from.permissions.level !== void 0 && !leveled) throw configError(`${PREFIX$1}: rls.customRoles.from.permissions.level is set, but no resource declares levels`);
-	const tenantType = tenantTypeOf(ctx);
-	const rolesTable = quoteQualified(roles.table);
-	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 ? "null::text" : `${col(roles.id)}::text`;
-	const skipped = roles.skip === void 0 ? "false" : `coalesce(${col(roles.skip)}, false)`;
-	const renamed = custom.renamed ?? {};
-	const renames = Object.entries(renamed).toSorted(byKey);
-	const current = (expr) => currentKeyExpr(renames, expr);
-	const known = sqlTextArray([...custom.permissions ?? [], ...renames.map(([former]) => former)]);
-	const declared = sqlTextArray(custom.declared);
-	const scopes = sqlTextArray(ctx.scopes.map((item) => item.name));
-	const ceiling = qualified(ctx, CUSTOM_ROLES.ceiling);
-	const rp = qualified(ctx, "role_permissions");
-	const perms = qualified(ctx, CUSTOM_ROLES.permissions);
-	const includes = qualified(ctx, CUSTOM_ROLES.includes);
-	const replace = qualified(ctx, CUSTOM_ROLES.trustedReplace);
-	const p = from.permissions;
-	const pTable = qualifySqlTable(p.table);
-	const pRef = roleRef(p.role, p.table, roles, "rls.customRoles.from.permissions.role");
-	const legacy = sourceSql(p.permission, pTable, "rls.customRoles.from.permissions.permission");
-	const effect = p.effect === void 0 ? "'allow'" : `coalesce(lower(x.${quoteIdent$1(p.effect)}::text), 'allow')`;
-	const level = p.level === void 0 ? "null::text" : `nullif(x.${quoteIdent$1(p.level)}::text, '')`;
-	const inCeiling = (key) => `exists (select 1 from ${ceiling} c where c.scope = v.scope and c.effect = 'allow' and ${current("c.permission")} = ${key})`;
-	const levelCheck = leveled ? `
-          when m.effect = 'allow' and m.level is not null and not exists (
-            select 1 from ${ceiling} c
-            where c.scope = v.scope and c.effect = 'allow' and ${current("c.permission")} = m.key
-              and split_part(c.grant_key, '@', 2) = m.level
-          ) then 'level ' || m.level || ' is not declared'` : "";
-	const allowEntry = leveled ? "j.key || coalesce('@' || j.level, '')" : "j.key";
-	const i = from.includes;
-	const iTable = i === void 0 ? void 0 : qualifySqlTable(i.table);
-	const iRef = i === void 0 || iTable === void 0 ? void 0 : roleRef(i.role, i.table, roles, "rls.customRoles.from.includes.role");
-	const included = i === void 0 || iTable === void 0 ? void 0 : sourceSql(i.include, iTable, "rls.customRoles.from.includes.include");
-	const refs = [`${col(pRef.id)} as permissions_ref`, ...iRef === void 0 ? [] : [`${col(iRef.id)} as includes_ref`]].join(", ");
-	const includeBlock = i === void 0 || iTable === void 0 || iRef === void 0 || included === void 0 ? "    v_include := null;" : `    with raw as (
-      select ${included} as role
-      from ${quoteTable(iTable)} x
-      where x.${quoteIdent$1(iRef.ref)} = v.includes_ref
-    ),
-    judged as (
-      select n.role, case
-          when n.role is null or not (n.role = any(${declared})) then 'not a declared role'
-          when exists (
-            select 1 from ${rp} rp
-            where rp.role = n.role and rp.effect = 'allow'
-              and not ${inCeiling(current("rp.permission"))}
-          ) then 'allows permissions outside the ceiling of ' || v.scope
-        end as dropped
-      from raw n
-    )
-    select array_agg(distinct j.role) filter (where j.dropped is null),
-      array_agg(v.role || ': includes ' || coalesce(j.role, 'null') || ', ' || j.dropped) filter (where j.dropped is not null)
-    into v_include, v_lost
-    from judged j;
-    v_dropped := v_dropped || coalesce(v_lost, '{}'::text[]);`;
+	const plan = rebuildPlan(ctx, from, migrate);
+	const { rolesTable, perms, includes, replace, scopes } = plan;
 	return `${BACKFILL_MARKER} schema=${ctx.schema ?? "permdock"}
--- custom roles copied from ${qualifySqlTable(roles.table)} (rls.customRoles.from) through ${replace}
+-- custom roles copied from ${qualifySqlTable(plan.roles.table)} (rls.customRoles.from) through ${replace}
 -- a role that already has rows is left as it is; entries PermDock cannot hold are dropped and listed in one warning
 do $permdock$
 declare
@@ -578,9 +506,9 @@ declare
   v_present integer := 0;
 begin
   for v in
-    select ${tenant} as tenant_id, ${scope} as scope, ${scopeId} as scope_id, ${col(roles.key)}::text as role, ${refs}
+    ${plan.identity}
     from ${rolesTable} r
-    where not ${skipped} and not (${col(roles.key)}::text = any(${declared}))
+    where ${plan.eligible}
     order by 4, 2, 1, 3
   loop
     if v.role is null or not (v.scope = 'global' or v.scope = any(${scopes})) then
@@ -597,30 +525,7 @@ begin
       v_present := v_present + 1;
       continue;
     end if;
-    with raw as (
-      select ${legacy} as legacy, ${effect} as effect, ${level} as level
-      from ${quoteTable(pTable)} x
-      where x.${quoteIdent$1(pRef.ref)} = v.permissions_ref
-    ),
-    mapped as (
-      select n.legacy, ${legacyKeySql("n.legacy", migrate, renamed)} as key, n.effect, n.level
-      from raw n
-    ),
-    judged as (
-      select m.*, case
-          when m.effect not in ('allow', 'deny') then 'effect ' || m.effect || ' is not allow or deny'
-          when m.key is null or not (m.key = any(${known})) then 'not a declared permission'
-          when m.effect = 'allow' and not ${inCeiling("m.key")} then 'outside the ceiling of ' || v.scope${levelCheck}
-        end as dropped
-      from mapped m
-    )
-    select array_agg(distinct ${allowEntry}) filter (where j.dropped is null and j.effect = 'allow'),
-      array_agg(distinct j.key) filter (where j.dropped is null and j.effect = 'deny'),
-      array_agg(v.role || ': ' || coalesce(j.legacy, 'null') || ', ' || j.dropped) filter (where j.dropped is not null)
-    into v_allow, v_deny, v_lost
-    from judged j;
-    v_dropped := v_dropped || coalesce(v_lost, '{}'::text[]);
-${includeBlock}
+${plan.collect}
     if v_allow is null and v_deny is null and v_include is null then
       continue;
     end if;
@@ -629,7 +534,7 @@ ${includeBlock}
   end loop;
   raise notice 'permdock backfill: copied % custom role(s), % already present', v_copied, v_present;
   if cardinality(v_dropped) > 0 then
-    raise warning 'permdock backfill: dropped % entr(ies) PermDock cannot hold: %', cardinality(v_dropped), array_to_string(v_dropped[1:50], '; ');
+    raise warning 'permdock backfill: dropped % entr(ies) PermDock cannot hold: %', cardinality(v_dropped), ${DROPPED_LIST};
   end if;
 end
 $permdock$;
@@ -639,7 +544,7 @@ $permdock$;
 //#region src/cli/rls/break-glass.ts
 /** The audit table every generated break-glass read writes to. Part of the SQL contract. */
 const BREAK_GLASS_AUDIT = "permdock_break_glass_audit";
-const IDENT$1 = /^[a-z][a-z0-9_]*$/u;
+const IDENT$2 = /^[a-z][a-z0-9_]*$/u;
 /**
 * The resources a `breakGlass` grant targets, with the table each reads. A
 * break-glass grant is non-portable, so `compileGrants` never turns it into a
@@ -688,7 +593,7 @@ function rowsFilter(ctx, entry) {
 		const asked = `p_permission = ${quoteLiteral(grant.permission)}`;
 		if (grant.scope === "anyone") {
 			if (grant.root === void 0) return [`(${asked})`];
-			return grant.column === void 0 ? [] : [`(${asked} and ${quoteIdent$1(grant.column)} in (select ${qualified(ctx, memberIdsHelper(grant.root))}()))`];
+			return grant.column === void 0 ? [] : [`(${asked} and ${quoteIdent$1(grant.column)} in (select ${qualified$1(ctx, memberIdsHelper(grant.root))}()))`];
 		}
 		if (grant.scope !== "global" && grant.column === void 0) return [];
 		return [`(${asked} and ${accessSql(ctx, grant.scope, breakGlassKey(grant.permission), grant.column)})`];
@@ -696,11 +601,11 @@ function rowsFilter(ctx, entry) {
 	return arms.length === 0 ? "false" : [...new Set(arms)].join("\n    or ");
 }
 function functionName$1(resource) {
-	if (!IDENT$1.test(resource)) throw configError(`PermDock CLI: unsafe break-glass resource '${resource}'`);
+	if (!IDENT$2.test(resource)) throw configError(`PermDock CLI: unsafe break-glass resource '${resource}'`);
 	return `permdock_break_glass_${resource}`;
 }
 function auditSql$1(ctx) {
-	const audit = qualified(ctx, quoteIdent$1(BREAK_GLASS_AUDIT));
+	const audit = qualified$1(ctx, quoteIdent$1(BREAK_GLASS_AUDIT));
 	return `-- break-glass audit: one row per session that read restricted data
 -- RLS never compiles a break-glass override, so restricted rows stay denied to a direct read
 create table if not exists ${audit} (
@@ -715,8 +620,8 @@ alter table ${audit} enable row level security;
 revoke all on table ${audit} from anon, authenticated, public;`;
 }
 function readFunctionSql(ctx, entry) {
-	const fn = qualified(ctx, functionName$1(entry.resource));
-	const audit = qualified(ctx, quoteIdent$1(BREAK_GLASS_AUDIT));
+	const fn = qualified$1(ctx, functionName$1(entry.resource));
+	const audit = qualified$1(ctx, quoteIdent$1(BREAK_GLASS_AUDIT));
 	const table = quoteQualified(entry.table);
 	const session = subjectClaimJsonSql(ctx, "break_glass");
 	const subject = subjectIdSql(ctx);
@@ -770,7 +675,7 @@ function breakGlassSql(ctx, entries) {
 //#endregion
 //#region src/cli/rls/emit.ts
 const HEADER = "-- generated by permdock rls generate\n-- fail-closed: never target a bypass role\n";
-const TRUSTED_READER_GRANT = /^grant execute on function [^\n]+\.permdock_trusted_role_permissions\([^)\n]*\) to [^\n;]+;$/gmu;
+const TRUSTED_READER_GRANT = /^grant usage on schema "[^"\n]+" to [^\n;]+;\ngrant execute on function [^\n]+\.permdock_trusted_role_permissions(?:_by_id)?\([^)\n]*\) to [^\n;]+;$/gmu;
 function assertNoServiceRole(text) {
 	if (/\bservice_role\b/iu.test(text.replace(TRUSTED_READER_GRANT, ""))) throw new Error("PermDock CLI: generated RLS must never emit service_role");
 }
@@ -982,7 +887,7 @@ function declaredScope(facts, scope, where) {
 * relationship or a `where` on the same permission never widens it.
 */
 function permitted(ctx, value, scope, key) {
-	return `${value} in (select x::text from ${qualified(ctx, permittedByPermissionHelper(scope))}(${quoteLiteral(key)}) x)`;
+	return `${value} in (select x::text from ${qualified$1(ctx, permittedByPermissionHelper(scope))}(${quoteLiteral(key)}) x)`;
 }
 function escapeRegex(text) {
 	return text.replaceAll(/[.*+?^${}()|[\]\\]/gu, String.raw`\$&`);
@@ -1099,165 +1004,6 @@ function realtimeStoragePolicies(ctx, facts, config, warnings = []) {
 	return policies;
 }
 //#endregion
-//#region src/cli/rls/rows.ts
-/** `permitted_<resource>_rows(p_permission)`: the resource's row ids the subject may act on with one permission. */
-function rowsHelper(resource) {
-	const name = graphSqlName(resource);
-	const helper = `permitted_${name ?? resource}_rows`;
-	if (name === void 0 || new TextEncoder().encode(`${helper}_for`).length > 63) throw configError(`PermDock CLI: rls.rowHelpers cannot name a helper for resource '${resource}'; use a SQL name of at most 45 bytes`);
-	return helper;
-}
-/** The branches a row check of a permission reads: its allows and denies on rows that exist, for signed-in callers. */
-function rowBranchesOf(branches, resource) {
-	const out = /* @__PURE__ */ new Map();
-	for (const branch of branches) {
-		if (branch.resource !== resource || branch.command === "insert" || branch.coverage === true || !branch.roles.includes("authenticated")) continue;
-		out.set(branch.permissionKey, [...out.get(branch.permissionKey) ?? [], branch]);
-	}
-	return out;
-}
-function usingOf(branches) {
-	const parts = branches.map((branch) => branchClauses(branch).using ?? "true");
-	return parts.length === 0 ? void 0 : orSql(parts);
-}
-function permissionCase(key, branches) {
-	const allow = usingOf(branches.filter((branch) => branch.effect === "allow"));
-	if (allow === void 0) return;
-	const deny = usingOf(branches.filter((branch) => branch.effect === "deny"));
-	const granted = `coalesce((${allow}), false)`;
-	return `    when ${quoteLiteral(key)} then ${deny === void 0 ? granted : `${granted} and (${deny}) is not true`}`;
-}
-function forUserSql(ctx, fn, helper) {
-	const user = ctx.dialect === "supabase" ? "uuid" : "text";
-	const signature = `${user}, text, jsonb`;
-	const head = `create or replace function ${fn}(p_user ${user}, p_permission text, p_claims jsonb default '{}')
-returns setof text
-language plpgsql
-volatile
-security definer
-set search_path = ''
-as $$`;
-	const tail = `revoke execute on function ${fn}(${signature}) from public, anon, authenticated;`;
-	if (ctx.dialect === "supabase") return `${head}
-declare
-  v_claims text := pg_catalog.current_setting('request.jwt.claims', true);
-begin
-  perform pg_catalog.set_config(
-    'request.jwt.claims',
-    (coalesce(p_claims, '{}'::jsonb) || pg_catalog.jsonb_build_object('sub', p_user::text, 'role', 'authenticated'))::text,
-    true
-  );
-  return query select r.id from ${helper}(p_permission) r(id);
-  perform pg_catalog.set_config('request.jwt.claims', coalesce(v_claims, ''), true);
-end
-$$;
-${tail}`;
-	const prefix = ctx.gucPrefix;
-	return `${head}
-declare
-  v_saved jsonb := '{}'::jsonb;
-  v_key text;
-  v_value text;
-begin
-  for v_key, v_value in
-    select 'user_id', p_user
-    union all
-    select c.key, c.value from pg_catalog.jsonb_each_text(coalesce(p_claims, '{}'::jsonb)) c where c.key <> 'user_id'
-  loop
-    v_saved := v_saved || pg_catalog.jsonb_build_object(v_key, coalesce(pg_catalog.current_setting(${quoteLiteral(`${prefix}.`)} || v_key, true), ''));
-    perform pg_catalog.set_config(${quoteLiteral(`${prefix}.`)} || v_key, v_value, true);
-  end loop;
-  return query select r.id from ${helper}(p_permission) r(id);
-  for v_key, v_value in select s.key, s.value from pg_catalog.jsonb_each_text(v_saved) s loop
-    perform pg_catalog.set_config(${quoteLiteral(`${prefix}.`)} || v_key, v_value, true);
-  end loop;
-end
-$$;
-${tail}`;
-}
-function inheritTargets(policy) {
-	const out = /* @__PURE__ */ new Set();
-	for (const grant of policy.grants) for (const item of flattenGrantee(grant.to)) if (item.kind === "inherit") out.add(item.resource);
-	return [...out].toSorted();
-}
-function stubSql(ctx, resource) {
-	return `create or replace function ${qualified(ctx, rowsHelper(resource))}(p_permission text)
-returns setof text
-language sql
-stable
-security definer
-set search_path = ''
-as $$
-  select null::text where false
-$$;`;
-}
-function rowSql(ctx, rows, table, where) {
-	const fn = qualified(ctx, rows.replace(/_rows$/u, "_row"));
-	return `create or replace function ${fn}(p_row ${table}, p_permission text)
-returns boolean
-language sql
-stable
-security definer
-set search_path = ''
-as $$
-  select exists (select 1 from (select (p_row).*) r where ${where})
-$$;
-revoke execute on function ${fn}(${table}, text) from public, anon;
-grant execute on function ${fn}(${table}, text) to authenticated;`;
-}
-function resourceSql(ctx, node, branches, tables) {
-	const name = rowsHelper(node.name);
-	const fn = qualified(ctx, name);
-	const table = quoteQualified(tableFor(node.name, tables));
-	const cases = [...branches.keys()].toSorted().flatMap((key) => {
-		const sql = permissionCase(key, branches.get(key) ?? []);
-		return sql === void 0 ? [] : [sql];
-	});
-	const where = cases.length === 0 ? "false" : `case p_permission\n${cases.join("\n")}\n    else false\n  end`;
-	const rows = `-- ${node.name}: ids of the rows the caller may act on with p_permission, as the table's policies decide it
-create or replace function ${fn}(p_permission text)
-returns setof text
-language sql
-stable
-security definer
-set search_path = ''
-as $$
-  select ${quoteIdent$1(node.id)}::text from ${table}
-  where ${where}
-$$;
-revoke execute on function ${fn}(text) from public, anon;
-grant execute on function ${fn}(text) to authenticated;
-${rowSql(ctx, name, table, where)}`;
-	if (ctx.dialect === "neon") return rows;
-	return `${rows}
--- the same rows for a user the caller names, with claims it supplies; no client role may execute it
-${forUserSql(ctx, qualified(ctx, `${name}_for`), fn)}`;
-}
-/**
-* `permitted_<resource>_rows(p_permission)` for each resource `select`
-* names (or every resource a grant reaches with `true`): the ids of its rows
-* the caller may read, update or delete with that permission, from the same
-* compiled allows and denies the table policies use, so closure walks, link
-* hops, the restricted stop, `includes`, groups and `requires` all apply. A
-* `security definer` helper, so hand-written policies and functions call it
-* without restating the graph. Outside the `neon` dialect a
-* `permitted_<resource>_rows_for(p_user, p_permission, p_claims)` form runs it
-* as the named user, with the claims the caller supplies, for trusted SQL.
-*/
-function rowHelpersSql(ctx, policy, branches, select, tables, warnings) {
-	const names = select === true ? [...new Set(branches.flatMap((branch) => branch.resource === void 0 ? [] : [branch.resource]))].toSorted() : [...new Set(select)];
-	const called = inheritTargets(policy);
-	for (const name of called) if (!names.includes(name)) names.push(name);
-	const chunks = called.map((name) => stubSql(ctx, name));
-	for (const name of names) {
-		const node = policy.resources.get(name);
-		if (node === void 0) throw configError(`PermDock CLI: rls.rowHelpers names '${name}', which the policy does not declare`);
-		chunks.push(resourceSql(ctx, node, rowBranchesOf(branches, name), tables));
-	}
-	if (chunks.length > 0 && ctx.dialect === "neon") warnings.push("rls.rowHelpers: the neon dialect reads the subject from auth.session(), which SQL cannot set, so no permitted_<resource>_rows_for is written");
-	return chunks.length === 0 ? "" : `${chunks.join("\n\n")}\n`;
-}
-//#endregion
 //#region src/cli/rls/generate-policies.ts
 const SERVICE_TABLES_HEADER = "-- Supabase Realtime and Storage: rls.realtime and rls.storage. RLS on both tables is Supabase's.";
 /**
@@ -1293,12 +1039,13 @@ function generatePolicies(input, policy, options, built, warnings) {
 	const { ctx } = built;
 	const { fieldsMode, revokeColumns } = options;
 	databaseModeWarnings(policy, built, warnings);
-	const compiled = compileGrants(policy, ctx, rls?.tables, warnings, input.skipClosures, rls?.rowHelpers !== void 0 || inheritTargets(policy).length > 0);
+	const compiled = compileGrants(policy, ctx, tableNames(rls?.tables), warnings, input.skipClosures, rls?.rowHelpers !== void 0 || inheritTargets(policy).length > 0);
 	const helpersOnly = input.helpersOnly === true || rls?.helpersOnly === true;
 	if (helpersOnly && (input.target !== "sql" || revokeColumns)) return { refusal: "rls generate --helpers-only needs --target sql and no --revoke-columns: the table grants are hand-written, so revoke the restricted columns there" };
 	const views = fieldsMode === void 0 ? [] : fieldViews(policy, ctx, compiled.branches, {
 		revokeColumns,
-		helpersOnly
+		helpersOnly,
+		mask: fieldsMode === "mask"
 	}, warnings);
 	const force = input.force === true || rls?.force === true;
 	if (force && views.some((view) => view.companion !== void 0)) warnings.push("--force with --revoke-columns: each <table>_visible_fields companion reads as its owner, so its owner needs BYPASSRLS or the restricted columns read as null");
@@ -1308,7 +1055,7 @@ function generatePolicies(input, policy, options, built, warnings) {
 		...policyName === void 0 ? {} : { name: policyName }
 	});
 	const actorKinds = readOnlyActorKinds(rls?.readOnlyActors);
-	if (actorKinds !== void 0 && helpersOnly) warnings.push(`rls.readOnlyActors with --helpers-only writes no policies: add \`and (select ${qualified(ctx, ACTOR_MAY_WRITE)}())\` to each hand-written insert, update and delete policy, or a restrictive policy that calls it`);
+	if (actorKinds !== void 0 && helpersOnly) warnings.push(`rls.readOnlyActors with --helpers-only writes no policies: add \`and (select ${qualified$1(ctx, ACTOR_MAY_WRITE)}())\` to each hand-written insert, update and delete policy, or a restrictive policy that calls it`);
 	const withActors = (items) => actorKinds === void 0 ? items : [...items, ...readOnlyActorPolicies(items, subjectClaimJsonSql(ctx, "act"), actorKinds)];
 	let tablePolicies;
 	try {
@@ -1341,7 +1088,7 @@ function generatePolicies(input, policy, options, built, warnings) {
 }
 //#endregion
 //#region src/cli/rls/shims.ts
-const NAME = /^[a-z_][a-z0-9_]*$/u;
+const NAME$1 = /^[a-z_][a-z0-9_]*$/u;
 /**
 * The key a legacy caller passes, mapped the way `rls migrate` maps it:
 * `keys` and `renamed` exactly, then the longest `prefixes` entry.
@@ -1424,7 +1171,7 @@ function grantKeys(keys, scope, effect) {
 }
 /** The instances of `scope` the caller holds an unconditional allow of the key in, minus those it holds a deny in. */
 function idsSql(ctx, keys, scope) {
-	const helper = qualified(ctx, permittedIdsHelper(scope));
+	const helper = qualified$1(ctx, permittedIdsHelper(scope));
 	return `  select a.id
   from ${grantKeys(keys, scope, "allow")}
   cross join lateral ${helper}(g.grant_key) a(id)
@@ -1434,7 +1181,7 @@ function idsSql(ctx, keys, scope) {
   cross join lateral ${helper}(g.grant_key) d(id)`;
 }
 function hasSql(ctx, keys) {
-	const has = qualified(ctx, HELPERS.has);
+	const has = qualified$1(ctx, HELPERS.has);
 	return `exists (select 1 from ${grantKeys(keys, "global", "allow")} where ${has}(g.grant_key))
     and not exists (select 1 from ${grantKeys(keys, "global", "deny")} where ${has}(g.grant_key))`;
 }
@@ -1452,14 +1199,14 @@ function shim(ctx, config, keys, fn, helper) {
 		case "membership": {
 			const scope = scopeOf(ctx, helper.scope);
 			const type = scopeTypeOf(ctx, scope);
-			return shimFunction(fn, `p_id ${type}`, type, "boolean", `  select coalesce(p_id in (select ${qualified(ctx, memberIdsHelper(scope))}()), false)`);
+			return shimFunction(fn, `p_id ${type}`, type, "boolean", `  select coalesce(p_id in (select ${qualified$1(ctx, memberIdsHelper(scope))}()), false)`);
 		}
 		case "role": {
 			const scope = scopeOf(ctx, helper.scope);
 			const type = scopeTypeOf(ctx, scope);
 			const values = Object.entries(ctx.roleValues ?? {});
 			const role = values.length === 0 ? "p_role" : `case p_role ${values.map(([from, to]) => `when ${quoteLiteral(from)} then ${quoteLiteral(to)}`).join(" ")} else p_role end`;
-			return shimFunction(fn, `p_id ${type}, p_role text`, `${type}, text`, "boolean", `  select coalesce(p_id in (select ${qualified(ctx, memberIdsHelper(scope))}(array[${role}])), false)`);
+			return shimFunction(fn, `p_id ${type}, p_role text`, `${type}, text`, "boolean", `  select coalesce(p_id in (select ${qualified$1(ctx, memberIdsHelper(scope))}(array[${role}])), false)`);
 		}
 		case "global": return shimFunction(fn, "p_key text", "text", "boolean", `  select ${hasSql(ctx, keys)}`);
 		case "scoped": {
@@ -1489,7 +1236,7 @@ function shimsSql(ctx, config, shims, renamed, grants) {
 	};
 	const chunks = [`-- permdock shims: legacy helper names over the permdock helpers; drop each once doctor reports no caller (PD056)`];
 	for (const [name, helper] of Object.entries(config.helpers).toSorted(byKey)) {
-		if (!NAME.test(name)) throw configError(`PermDock CLI: unsafe rls.migrate helper name '${name}'`);
+		if (!NAME$1.test(name)) throw configError(`PermDock CLI: unsafe rls.migrate helper name '${name}'`);
 		chunks.push(shim(ctx, config, keys, `${quoteIdent$1(schema)}.${name}`, helper));
 	}
 	return `${chunks.join("\n\n")}\n`;
@@ -1508,7 +1255,7 @@ const AUDITED = [
 	CUSTOM_ROLES.includes,
 	"user_roles"
 ];
-const IDENT = /^[a-z_][a-z0-9_$]*$/u;
+const IDENT$1 = /^[a-z_][a-z0-9_$]*$/u;
 /** The tables `sql` creates in `schema`, by name without the schema. */
 function generatedTables(sql, schema) {
 	const prefix = `create table if not exists ${quoteIdent$1(schema)}.`;
@@ -1570,7 +1317,7 @@ function auditSql(audit, schema, tables) {
 	if (listed !== void 0) for (const table of listed) knownTable(table, tables, "rls.audit.tables");
 	const targets = listed ?? AUDITED.filter((table) => tables.includes(table));
 	const args = Object.entries(audit.args ?? {}).map(([name, value]) => {
-		if (!IDENT.test(name)) throw configError(`${PREFIX}: rls.audit.args names ${JSON.stringify(name)}, which is not a lower-case parameter name`);
+		if (!IDENT$1.test(name)) throw configError(`${PREFIX}: rls.audit.args names ${JSON.stringify(name)}, which is not a lower-case parameter name`);
 		return `, ${quoteIdent$1(name)} => ${quoteLiteral(value)}`;
 	});
 	if (targets.length === 0) return "";
@@ -1633,14 +1380,15 @@ function sectionsSql(input, policy, options, built, generated, jsonSchema, warni
 	} catch (cause) {
 		return { refusal: describeError(cause) };
 	}
-	const graphed = graphSql(ctx, graph, rls?.tables);
+	if (typeof rls?.approvals === "object" && rls.approvals.delegations === true && ctx.authorize !== "database") warnings.push("rls.approvals.delegations with --authorize jwt: permdock_is_approver cannot read a delegator's permissions from the caller's token, so in SQL a cover never satisfies a holder() approver; approvalsHandler still does");
+	const graphed = graphSql(ctx, graph, tableNames(rls?.tables));
 	let rowHelpers = "";
 	if (rls?.rowHelpers !== void 0 || inheritTargets(policy).length > 0) try {
-		rowHelpers = rowHelpersSql(ctx, policy, [...options.fieldsMode === void 0 ? compiled.branches : rowBranches(compiled.branches), ...compiled.actionBranches], rls?.rowHelpers ?? [], rls?.tables, warnings);
+		rowHelpers = rowHelpersSql(ctx, policy, [...options.fieldsMode === void 0 ? compiled.branches : rowBranches(compiled.branches), ...compiled.actionBranches], rls?.rowHelpers ?? [], tableNames(rls?.tables), warnings);
 	} catch (cause) {
 		return { refusal: describeError(cause) };
 	}
-	const breakGlass = breakGlassSql(ctx, breakGlassEntries(policy, rls?.tables));
+	const breakGlass = breakGlassSql(ctx, breakGlassEntries(policy, tableNames(rls?.tables)));
 	return [
 		approvals,
 		owned === "" ? void 0 : owned,
@@ -1715,6 +1463,14 @@ function preambleSql(input, policy, options, built, generated, jsonSchema, warni
 		audit
 	};
 }
+function seedsBody(ctx, schema, rows) {
+	switch (ctx.seeds) {
+		case "function": return `select ${quoteQualified(`${schema}.seed`)}();`;
+		case "view": return "-- rls.seeds: 'view': the role_permissions rows are in the helpers part";
+		case void 0: return seedSql(ctx, rows);
+		default: return ctx.seeds;
+	}
+}
 function forceWarnings({ graph }, warnings) {
 	for (const entry of graph.values()) {
 		const own = [...entry.relations].filter((name) => !("edge" in (entry.node.relations[name] ?? {})));
@@ -1795,18 +1551,144 @@ function generateSql(input, policy, options, built, warnings) {
 		...generated,
 		...emitted,
 		backfill: checked.backfill,
-		indexes: indexTargets(ctx, tableColumns(generated.compiled.rowColumns, rls?.tables, helpersOnly, warnings)),
+		indexes: indexTargets(ctx, tableColumns(generated.compiled.rowColumns, tableNames(rls?.tables), helpersOnly, warnings)),
 		parts: (indexes) => ({
 			policies: dialectRoles(withHelperTables(emitSql(policies, "", force, views), helperTables), ctx.dialect),
 			declarativePolicies: dialectRoles(emitSql(policies, "", force, views), ctx.dialect),
 			...guardedTables === void 0 ? {} : { servicePolicies: dialectRoles(guardedTables, ctx.dialect) },
 			helpers: dialectRoles(emitSql([], preamble, false, helpersOnly ? views : []), ctx.dialect),
-			seeds: `${SEEDS_MARKER} schema=${built.schema}\n${seedSql(ctx, generated.compiled.rolePermissions)}\n${seedsSplit ? audit : ""}`,
+			seeds: `${SEEDS_MARKER} schema=${built.schema}\n${seedsBody(ctx, built.schema, generated.compiled.rolePermissions)}\n${seedsSplit ? audit : ""}`,
 			indexes: `${INDEXES_MARKER}\n${indexesSql(indexes)}\n`
 		})
 	};
 }
 //#endregion
+//#region src/cli/rls/index-scan.ts
+/** An index PermDock generated (`permdock_<table>_<columns>_idx`), in the indexes part or in a migration derived from it: it never counts as serving its own target. */
+const GENERATED_INDEX = /\bcreate\s+index\s+(?:if\s+not\s+exists\s+)?"?permdock_\w*_idx"?[^;]*;/giu;
+const IDENT = String.raw`(?:"(?:[^"]|"")+"|[A-Za-z_][\w$]*)`;
+const NAME = String.raw`${IDENT}(?:\s*\.\s*${IDENT})?`;
+const CREATE_INDEX = new RegExp(String.raw`\bcreate\s+(?:unique\s+)?index\s+(?:concurrently\s+)?(?:if\s+not\s+exists\s+)?(?:${IDENT}\s+)?on\s+(?:only\s+)?(${NAME})\s*(?:using\s+\w+\s*)?\(`, "giu");
+const ADD_KEY = new RegExp(String.raw`\balter\s+table\s+(?:if\s+exists\s+)?(?:only\s+)?(${NAME})\s+add\s+(?:constraint\s+${IDENT}\s+)?(?:unique|primary\s+key)\s*(?:nulls\s+not\s+distinct\s*)?\(`, "giu");
+const CREATE_TABLE = new RegExp(String.raw`\bcreate\s+(?:unlogged\s+|temp(?:orary)?\s+)?table\s+(?:if\s+not\s+exists\s+)?(${NAME})\s*\(`, "giu");
+const TABLE_NAME = new RegExp(String.raw`\bcreate\s+(?:unlogged\s+)?table\s+(?:if\s+not\s+exists\s+)?(${NAME})`, "giu");
+const TABLE_KEY = new RegExp(String.raw`^(?:constraint\s+${IDENT}\s+)?(?:unique|primary\s+key)\s*(?:nulls\s+not\s+distinct\s*)?\(`, "iu");
+const COLUMN_KEY = new RegExp(String.raw`^(${IDENT})\s+[^,]*?\b(?:primary\s+key|unique)\b`, "iu");
+const NOT_A_COLUMN = /^(?:constraint|check|foreign|exclude|like)\b/iu;
+function bare(part) {
+	const trimmed = part.trim();
+	return trimmed.startsWith("\"") ? trimmed.slice(1, -1).replaceAll("\"\"", "\"") : trimmed.toLowerCase();
+}
+/** `schema.table`, with `public` for an unqualified name. */
+function qualified(raw) {
+	const parts = raw.split(".").map(bare);
+	return parts.length === 1 ? `public.${parts.join("")}` : parts.join(".");
+}
+function stripComments(sql) {
+	return sql.replaceAll(/\/\*[\s\S]*?\*\//gu, " ").replaceAll(/--[^\n]*/gu, " ");
+}
+/** The text between the `(` that ends `match` and its closing `)`, and the index after it. */
+function group(text, open) {
+	let depth = 1;
+	for (let index = open; index < text.length; index += 1) {
+		const char = text[index];
+		if (char === "'" || char === "\"") {
+			const close = text.indexOf(char, index + 1);
+			if (close === -1) return;
+			index = close;
+		} else if (char === "(") depth += 1;
+		else if (char === ")") {
+			depth -= 1;
+			if (depth === 0) return {
+				body: text.slice(open, index),
+				end: index + 1
+			};
+		}
+	}
+}
+function splitTop(body) {
+	const items = [];
+	let depth = 0;
+	let from = 0;
+	for (let index = 0; index < body.length; index += 1) {
+		const char = body[index];
+		if (char === "'" || char === "\"") index = Math.max(body.indexOf(char, index + 1), index);
+		else if (char === "(") depth += 1;
+		else if (char === ")") depth -= 1;
+		else if (char === "," && depth === 0) {
+			items.push(body.slice(from, index));
+			from = index + 1;
+		}
+	}
+	items.push(body.slice(from));
+	return items.map((item) => item.trim());
+}
+/** The first capture group of a match; every pattern here captures it. */
+function captured(match) {
+	return match.slice(1, 2).join("");
+}
+/** The index just past a match. */
+function endOf(match) {
+	return match.index + match[0].length;
+}
+/** The plain key columns of an index column list, cut at the first expression. */
+function keyColumns(body) {
+	const columns = [];
+	for (const item of splitTop(body)) {
+		const match = new RegExp(`^(${IDENT})(?:\\s|$)`, "u").exec(item);
+		if (match === null || item.startsWith("(")) break;
+		columns.push(bare(captured(match)));
+	}
+	return columns;
+}
+/** Key columns of each index, unique constraint and primary key the SQL creates, per `schema.table`. */
+function indexKeysFromSql(sql) {
+	const text = stripComments(sql);
+	const keys = {};
+	const add = (table, columns) => {
+		if (columns.length > 0) (keys[qualified(table)] ??= []).push(columns);
+	};
+	for (const pattern of [CREATE_INDEX, ADD_KEY]) for (const match of text.matchAll(pattern)) {
+		const found = group(text, endOf(match));
+		if (found !== void 0) add(captured(match), keyColumns(found.body));
+	}
+	for (const match of text.matchAll(CREATE_TABLE)) {
+		const found = group(text, endOf(match));
+		if (found === void 0) continue;
+		for (const item of splitTop(found.body)) if (TABLE_KEY.test(item)) {
+			const inner = group(item, item.indexOf("(") + 1);
+			if (inner !== void 0) add(captured(match), keyColumns(inner.body));
+		} else if (!NOT_A_COLUMN.test(item)) {
+			const column = COLUMN_KEY.exec(item)?.[1];
+			if (column !== void 0) add(captured(match), [bare(column)]);
+		}
+	}
+	return keys;
+}
+/** The index keys of the SQL files under the migration and schema folders of `cwd`. */
+function indexKeysFromProject(cwd) {
+	const all = {};
+	for (const file of sqlFiles(cwd, [...MIGRATION_DIRS])) {
+		const keys = indexKeysFromSql(readFileSync(file, "utf8").replaceAll(GENERATED_INDEX, ""));
+		for (const [table, list] of Object.entries(keys)) (all[table] ??= []).push(...list);
+	}
+	return all;
+}
+/** Every `schema.table` the SQL creates, temporary tables left out. */
+function tablesFromSql(sql) {
+	return new Set([...stripComments(sql).matchAll(TABLE_NAME)].map((match) => qualified(captured(match))));
+}
+/** Every `schema.table` the SQL files under the migration and schema folders of `cwd` create. */
+function tablesFromProject(cwd) {
+	const all = /* @__PURE__ */ new Set();
+	for (const file of sqlFiles(cwd, [...MIGRATION_DIRS])) for (const table of tablesFromSql(readFileSync(file, "utf8"))) all.add(table);
+	return all;
+}
+/** The targets no index in `keys` leads with: its key columns start with the target's, as `pruneIndexTargets` reads a database. */
+function withoutServedTargets(targets, keys) {
+	return targets.filter((target) => !(keys[target.table] ?? []).some((key) => target.columns.every((column, at) => key[at] === column)));
+}
+//#endregion
 //#region src/cli/rls/generate.ts
 function loadPolicy(cwd, config, from) {
 	const policyPath = from === "drizzle" ? config.policy : from ?? config.policy;
@@ -1884,8 +1766,19 @@ async function runRlsGenerate(input) {
 	const { ctx } = built;
 	const { text, migration, migrationRel, helpersOnly } = generated;
 	let indexes = generated.indexes;
+	const bindings = tableBindings(generated.compiled.rowColumns.map((item) => item.resource), tableNames(input.config.rls?.tables), helpersOnly);
+	if (input.config.rls?.tables === void 0) warnings.push(...bindingNotes(bindings, input.db !== void 0));
+	warnings.push(...triggerNotes(text));
+	if (ctx.seeds === "function") warnings.push(`run select ${built.schema}.seed(); after each deploy`);
+	if (input.db === void 0) {
+		indexes = withoutServedTargets(indexes, indexKeysFromProject(input.cwd));
+		warnings.push(...unknownTableNotes(bindings, tablesFromProject(input.cwd)));
+	}
 	if (input.db !== void 0) try {
-		const pruned = pruneIndexTargets(indexes, await readTableIndexFacts(input.db, [...new Set(indexes.map((target) => target.table))], input.connect));
+		const facts = await readTableIndexFacts(input.db, [.../* @__PURE__ */ new Set([...indexes.map((target) => target.table), ...bindings.map((binding) => binding.table)])], input.connect);
+		const missing = missingBindings(bindings, facts.columns);
+		if (missing.length > 0) return refused(`rls generate: ${missing.map((binding) => `resource ${binding.resource} is bound to ${binding.table}, which the database does not have`).join("; ")}; name the table in rls.tables, or set rls.tables.<resource>: false for a resource with no table`);
+		const pruned = pruneIndexTargets(indexes, facts);
 		indexes = pruned.targets;
 		warnings.push(...pruned.warnings);
 	} catch (cause) {
@@ -1907,10 +1800,19 @@ async function runRlsGenerate(input) {
 		keys: {
 			permissions: listPermissions(policy.vocabulary.permissions).map((leaf) => leaf.key),
 			rowConditions: [...policyRowConditionKeys(policy)],
+			levels: levelKeys(policy),
 			renamed: Object.fromEntries(renamedKeys(policy.vocabulary.permissions))
 		},
 		schema: built.schema,
 		helpersOnly,
+		explain: explainRls({
+			config: input.config,
+			ctx,
+			schema: built.schema,
+			authorize: built.authorize,
+			generated,
+			text
+		}),
 		...extras
 	};
 	const planned = outputFiles({
@@ -2034,7 +1936,7 @@ function missingIndexes(expected, actual) {
 	return expected.indexes.flatMap((target) => {
 		const column = target.columns[0];
 		const columns = actual.columns?.[target.table];
-		return column === void 0 || columns !== void 0 && !columns.includes(column) || actual.leadingColumns[target.table]?.includes(column) === true ? [] : [`warning: ${target.table}: no index starts with ${column}, which the policies or helpers filter on; add it, or write it with rls generate --split ...,indexes`];
+		return column === void 0 || columns !== void 0 && !columns.includes(column) || actual.leadingColumns[target.table]?.includes(column) === true ? [] : [rlsFinding("index-missing", target.table, column, `${target.table}: no index starts with ${column}, which the policies or helpers filter on; add it, or write it with rls generate --split ...,indexes`, "warning")];
 	});
 }
 function sameList(left, right) {
@@ -2042,42 +1944,42 @@ function sameList(left, right) {
 	const b = right.toSorted();
 	return a.length === b.length && a.every((item, index) => item === b[index]);
 }
-/** One line per difference; policy expressions are not compared, since Postgres rewrites their text. */
+/** One finding per difference; policy expressions are not compared, since Postgres rewrites their text. */
 function diffRls(expected, actual, options = {}) {
 	const out = [];
 	const found = new Map(actual.policies.map((item) => [`${item.table}\u0000${item.name}`, item]));
 	for (const want of expected.policies) {
 		const have = found.get(`${want.table}\u0000${want.name}`);
 		if (have === void 0) {
-			out.push(`${want.table}: policy ${want.name} is missing`);
+			out.push(rlsFinding("policy-missing", want.table, want.name, `${want.table}: policy ${want.name} is missing`));
 			continue;
 		}
-		if (have.command !== want.command) out.push(`${want.table}: policy ${want.name} is for ${have.command}, expected ${want.command}`);
-		if (have.permissive !== want.permissive) out.push(`${want.table}: policy ${want.name} is ${have.permissive ? "permissive" : "restrictive"}, expected ${want.permissive ? "permissive" : "restrictive"}`);
-		if (!sameList(have.roles, want.roles)) out.push(`${want.table}: policy ${want.name} applies to ${have.roles.join(", ")}, expected ${want.roles.join(", ")}`);
+		if (have.command !== want.command) out.push(rlsFinding("policy-command", want.table, want.name, `${want.table}: policy ${want.name} is for ${have.command}, expected ${want.command}`));
+		if (have.permissive !== want.permissive) out.push(rlsFinding("policy-mode", want.table, want.name, `${want.table}: policy ${want.name} is ${have.permissive ? "permissive" : "restrictive"}, expected ${want.permissive ? "permissive" : "restrictive"}`));
+		if (!sameList(have.roles, want.roles)) out.push(rlsFinding("policy-roles", want.table, want.name, `${want.table}: policy ${want.name} applies to ${have.roles.join(", ")}, expected ${want.roles.join(", ")}`));
 	}
 	const wanted = new Set(expected.policies.map((item) => `${item.table}\u0000${item.name}`));
-	for (const have of actual.policies) if (expected.tables.includes(have.table) && !wanted.has(`${have.table}\u0000${have.name}`)) out.push(`${have.table}: policy ${have.name} is not generated (${have.permissive ? "permissive" : "restrictive"} ${have.command}); a permissive one widens access`);
+	for (const have of actual.policies) if (expected.tables.includes(have.table) && !wanted.has(`${have.table}\u0000${have.name}`)) out.push(rlsFinding("policy-extra", have.table, have.name, `${have.table}: policy ${have.name} is not generated (${have.permissive ? "permissive" : "restrictive"} ${have.command}); a permissive one widens access`));
 	for (const table of expected.tables) {
 		if (actual.rlsEnabled[table] !== true) {
-			out.push(actual.rlsEnabled[table] === void 0 ? `${table}: table is missing` : `${table}: row level security is disabled`);
+			out.push(actual.rlsEnabled[table] === void 0 ? rlsFinding("table-missing", table, "table", `${table}: table is missing`) : rlsFinding("rls-disabled", table, "table", `${table}: row level security is disabled`));
 			continue;
 		}
 		for (const role of ROLES) {
 			const want = expected.grants[table]?.[role] ?? [];
 			const have = actual.grants[table]?.[role] ?? [];
-			for (const privilege of want) if (!have.includes(privilege) && !(privilege === "select" && options.columnGrants === true)) out.push(`${table}: ${role} lacks ${privilege}, so the policy answers 42501 instead of filtering`);
-			for (const privilege of have) if (!want.includes(privilege)) out.push(`${table}: ${role} holds ${privilege}, which no generated policy allows`);
+			for (const privilege of want) if (!have.includes(privilege) && !(privilege === "select" && options.columnGrants === true)) out.push(rlsFinding("grant-missing", table, `${role}.${privilege}`, `${table}: ${role} lacks ${privilege}, so the policy answers 42501 instead of filtering`));
+			for (const privilege of have) if (!want.includes(privilege)) out.push(rlsFinding("grant-extra", table, `${role}.${privilege}`, `${table}: ${role} holds ${privilege}, which no generated policy allows`));
 		}
 	}
 	for (const helper of expected.helpers) {
 		const have = actual.helpers[helper];
 		if (have === void 0) {
-			out.push(`${helper}: helper is missing`);
+			out.push(rlsFinding("helper-missing", helper, "helper", `${helper}: helper is missing`));
 			continue;
 		}
-		if (!have.securityDefiner) out.push(`${helper}: helper is not security definer`);
-		if (!have.emptySearchPath) out.push(`${helper}: helper does not set search_path = ''`);
+		if (!have.securityDefiner) out.push(rlsFinding("helper-definer", helper, "helper", `${helper}: helper is not security definer`));
+		if (!have.emptySearchPath) out.push(rlsFinding("helper-search-path", helper, "helper", `${helper}: helper does not set search_path = ''`));
 	}
 	return out;
 }
@@ -2098,12 +2000,6 @@ const HELPERS_SQL = `select n.nspname || '.' || p.proname as target, p.prosecdef
 from pg_proc p
 join pg_namespace n on n.oid = p.pronamespace
 where n.nspname || '.' || p.proname = any($1::text[])`;
-const INDEXES_SQL = `select n.nspname || '.' || c.relname as target, a.attname as leading
-from pg_index i
-join pg_class c on c.oid = i.indrelid
-join pg_namespace n on n.oid = c.relnamespace
-join pg_attribute a on a.attrelid = i.indrelid and a.attnum = i.indkey[0]
-where i.indpred is null and n.nspname || '.' || c.relname = any($1::text[])`;
 function commandOf(cmd) {
 	const text = String(cmd ?? "").toLowerCase();
 	return text === "*" ? "all" : text;
@@ -2122,13 +2018,16 @@ async function introspectRls(db, expected, connect = connectIntrospect) {
 			client.query(TABLES_SQL, [tables]),
 			client.query(GRANTS_SQL, [tables]),
 			client.query(HELPERS_SQL, [[...expected.helpers]]),
-			client.query(INDEXES_SQL, [indexed]),
+			client.query(INDEX_COLUMNS_SQL, [indexed]),
 			client.query(COLUMNS_SQL, [indexed])
 		]);
 		const columnsOf = {};
 		for (const row of columns.rows) (columnsOf[String(row["target"])] ??= []).push(String(row["name"]));
 		const leadingColumns = {};
-		for (const row of indexes.rows) (leadingColumns[String(row["target"])] ??= []).push(String(row["leading"]));
+		for (const row of indexes.rows) {
+			const lead = (Array.isArray(row["columns"]) ? row["columns"] : []).at(0);
+			if (typeof lead === "string") (leadingColumns[String(row["target"])] ??= []).push(lead);
+		}
 		const byTable = {};
 		for (const row of grants.rows) {
 			const table = String(row["target"]);
@@ -2176,7 +2075,7 @@ function unguardedWrites(policies, fn) {
 		const permissive = applying.filter((policy) => policy.restrictive !== true && (policy.roles ?? []).some((role) => role === "authenticated" || role === "public"));
 		if (permissive.length === 0) continue;
 		const calls = (expression) => expression.includes(fn);
-		if (!(applying.some((policy) => policy.restrictive === true && calls(policy.expression)) || permissive.every((policy) => calls(policy.expression)))) out.push(`${table}: ${command} policies for authenticated do not call ${fn}(), so a read-only support or impersonation session can write (rls.readOnlyActors)`);
+		if (!(applying.some((policy) => policy.restrictive === true && calls(policy.expression)) || permissive.every((policy) => calls(policy.expression)))) out.push(rlsFinding("write-unguarded", table, command, `${table}: ${command} policies for authenticated do not call ${fn}(), so a read-only support or impersonation session can write (rls.readOnlyActors)`));
 	}
 	return out;
 }
@@ -2205,26 +2104,37 @@ function inScope(table) {
 function seedLine(row) {
 	return `${row.role} ${row.effect} ${row.grantKey} on ${row.scope}`;
 }
+function seedKey(line) {
+	return line.replace(" on ", " ").replaceAll(" ", "/");
+}
 /** Drift is an error; `info` names RLS tables whose policies call no PermDock helper. */
 function diffMixed(expected, actual) {
 	const drift = [];
+	const seeds = `${expected.schema}.role_permissions`;
 	const want = new Set(expected.seeds.map(seedLine));
 	const have = new Set(actual.seeds.map(seedLine));
-	for (const line of want) if (!have.has(line)) drift.push(`${expected.schema}.role_permissions: missing ${line}`);
-	for (const line of have) if (!want.has(line)) drift.push(`${expected.schema}.role_permissions: unexpected ${line}`);
+	for (const line of want) if (!have.has(line)) drift.push(rlsFinding("seed-missing", seeds, seedKey(line), `${seeds}: missing ${line}`));
+	for (const line of have) if (!want.has(line)) drift.push(rlsFinding("seed-extra", seeds, seedKey(line), `${seeds}: unexpected ${line}`));
 	const permissions = new Set(expected.permissions);
 	const conditioned = new Set(expected.rowConditions);
+	const levels = new Map((expected.levels ?? []).map((level) => [level.key, level]));
+	const notes = [];
 	const covered = /* @__PURE__ */ new Set();
 	for (const policy of actual.policies) {
 		if (callsHelper(policy.expression)) covered.add(policy.table);
 		const blind = new Set(helperCallKeys(policy.expression, true));
-		for (const key of helperCallKeys(policy.expression)) if (!permissions.has(key)) drift.push(`${policy.table}: policy ${policy.name} passes ${key}, which the policy does not declare, so it always denies`);
-		else if (conditioned.has(key) && blind.has(key)) drift.push(`${policy.table}: policy ${policy.name} passes ${key}, whose grants carry row conditions the helpers do not check: the policy grants more than the application does`);
+		for (const key of helperCallKeys(policy.expression)) {
+			const level = levels.get(key);
+			if (level !== void 0) {
+				if (level.conditioned) notes.push(rlsFinding("level-unconditioned", policy.table, `${policy.name}/${key}`, `${policy.table}: policy ${policy.name} passes ${key}, which skips the level's row condition, so holders of it are denied there; use ${level.rowHelper}(${policy.table.slice(policy.table.lastIndexOf(".") + 1)}, '${level.permission}')`, "info"));
+			} else if (!permissions.has(key)) drift.push(rlsFinding("undeclared-key", policy.table, `${policy.name}/${key}`, `${policy.table}: policy ${policy.name} passes ${key}, which the policy does not declare, so it always denies`));
+			else if (conditioned.has(key) && blind.has(key)) drift.push(rlsFinding("condition-blind", policy.table, `${policy.name}/${key}`, `${policy.table}: policy ${policy.name} passes ${key}, whose grants carry row conditions the helpers do not check: the policy grants more than the application does`));
+		}
 	}
 	if (expected.readOnlyActors === true) drift.push(...unguardedWrites(actual.policies, ACTOR_MAY_WRITE));
 	return {
 		drift,
-		info: actual.rlsTables.filter((table) => !covered.has(table)).map((table) => `${table}: no policy calls a PermDock helper`)
+		info: [...notes, ...actual.rlsTables.filter((table) => !covered.has(table)).map((table) => rlsFinding("helper-uncalled", table, "table", `${table}: no policy calls a PermDock helper`, "info"))]
 	};
 }
 const ALL_POLICIES_SQL = `select schemaname || '.' || tablename as target, policyname,
@@ -2270,12 +2180,15 @@ async function introspectMixed(db, schema, connect = connectIntrospect) {
 }
 //#endregion
 //#region src/cli/rls/rls.ts
-const RLS_HELP = `permdock rls generate | import | verify | migrate
+/** `rls migrate` and `rls import` read the pgsql-parser 18 AST. */
+const PGSQL_PARSER_MAJOR = 18;
+const RLS_HELP = `permdock rls generate | import | verify | migrate | explain
 
   generate  Compile the policy into RLS policies and helpers
   import    Turn existing policies (--sql or --db-url-stdin) into a permissions module
   verify    Run the fixtures, or compare a live database with --introspect
   migrate   Rewrite the rls.migrate helpers' calls onto the generated helpers
+  explain   Show the tables, membership sources, custom roles and triggers the SQL binds to
 
 Run permdock rls <command> --help for its flags.
 Never emits service_role, except in the execute grant rls.trustedReaders asks for. memberOf compiles through the dialect memberships mapping.
@@ -2318,11 +2231,48 @@ function generateInput(input, target, dialect) {
 		...isSupabaseSchemas(input.schemas) ? { schemas: input.schemas } : {},
 		...input.grantsOut === void 0 ? {} : { grantsOut: input.grantsOut },
 		...input.seedsOut === void 0 ? {} : { seedsOut: input.seedsOut },
+		...input.noSeeds === true ? { noSeeds: true } : {},
 		...input.backfillOut === void 0 ? {} : { backfillOut: input.backfillOut },
 		helpersOnly: input.helpersOnly,
 		shims: input.shims === true
 	};
 }
+async function explain(input) {
+	const dialect = asDialect(input.dialect ?? input.config.rls?.dialect);
+	if (dialect === void 0) return {
+		code: 2,
+		output: "rls explain --dialect (or rls.dialect) must be supabase, neon or guc"
+	};
+	const generated = await runRlsGenerate({
+		...generateInput(input, "sql", dialect),
+		check: false,
+		write: false
+	});
+	if (generated.explain === void 0) return {
+		code: generated.code,
+		output: generated.output
+	};
+	let report = generated.explain;
+	if (input.db !== void 0) try {
+		const facts = await readTableIndexFacts(input.db, report.bindings.map((binding) => binding.table), input.connect);
+		report = {
+			...report,
+			bindings: report.bindings.map((binding) => ({
+				...binding,
+				exists: facts.columns[binding.table] !== void 0
+			}))
+		};
+	} catch (cause) {
+		return {
+			code: exitCodeOfError(cause),
+			output: describeError(cause)
+		};
+	}
+	return {
+		code: 0,
+		output: input.json ? JSON.stringify(report, null, 2) : describeExplain(report)
+	};
+}
 async function migrate(input) {
 	const config = input.config.rls?.migrate;
 	if (config === void 0) return {
@@ -2347,8 +2297,8 @@ async function migrate(input) {
 		code: 2,
 		output: generated.output
 	};
-	await requirePeer(() => import("pgsql-parser"), "pgsql-parser", "permdock rls migrate", input.cwd);
-	const { migrateTarget, runRlsMigrate } = await import("./migrate-CIq4-E9F.js");
+	await requirePeer(() => import("pgsql-parser"), "pgsql-parser", "permdock rls migrate", input.cwd, PGSQL_PARSER_MAJOR);
+	const { migrateTarget, runRlsMigrate } = await import("./migrate-Dodel0IJ.js");
 	return runRlsMigrate({
 		cwd: input.cwd,
 		sql: input.sql,
@@ -2365,7 +2315,7 @@ async function migrate(input) {
 	});
 }
 /** `verify --introspect` with `--helpers-only`: helpers and seeds exactly, hand-written policies by their keys. */
-async function introspectHelpersOnly(db, expected, generated, connect, readOnlyActors) {
+async function introspectHelpersOnly(db, expected, generated, connect, readOnlyActors, ignore) {
 	const schema = generated.schema ?? "permdock";
 	try {
 		const actual = await introspectRls(db, expected, connect);
@@ -2376,31 +2326,25 @@ async function introspectHelpersOnly(db, expected, generated, connect, readOnlyA
 			seeds: generated.seeds ?? [],
 			permissions: generated.keys?.permissions ?? [],
 			rowConditions: generated.keys?.rowConditions ?? [],
+			levels: generated.keys?.levels ?? [],
 			readOnlyActors
 		}, await introspectMixed(db, schema, connect));
-		const drift = [...helpers, ...mixed.drift];
-		const info = mixed.info.map((line) => `info: ${line}`);
-		return drift.length > 0 ? {
-			code: 1,
-			output: [
-				...drift,
+		return verifyResult({
+			findings: [
+				...helpers,
+				...mixed.drift,
 				...warnings,
-				...info
-			].join("\n")
-		} : {
-			code: 0,
-			output: [
-				...warnings,
-				...info,
-				`introspected ${String(expected.helpers.length)} helper(s) and ${String(generated.seeds?.length ?? 0)} seeded row(s), helpers only: no drift`
-			].join("\n")
-		};
+				...mixed.info
+			],
+			ignore,
+			summary: `introspected ${String(expected.helpers.length)} helper(s) and ${String(generated.seeds?.length ?? 0)} seeded row(s), helpers only: no drift`
+		});
 	} catch (cause) {
 		return usageResult(cause);
 	}
 }
 /** `verify --introspect`: the catalogs against what `generate` would write with the same flags. */
-async function introspect(input) {
+async function introspect(input, ignore) {
 	if (input.db === void 0) return {
 		code: 2,
 		output: "PermDock CLI: rls verify --introspect needs a database: --db-url-stdin, DATABASE_URL or SUPABASE_DB_URL"
@@ -2420,19 +2364,15 @@ async function introspect(input) {
 		output: generated.output
 	};
 	const expected = expectedRls(generated.policies, generated.text, generated.indexes);
-	if (generated.helpersOnly === true) return introspectHelpersOnly(input.db, expected, generated, input.connect, readOnlyActorKinds(input.config.rls?.readOnlyActors) !== void 0);
+	if (generated.helpersOnly === true) return introspectHelpersOnly(input.db, expected, generated, input.connect, readOnlyActorKinds(input.config.rls?.readOnlyActors) !== void 0, ignore);
 	try {
 		const actual = await introspectRls(input.db, expected, input.connect);
-		const drift = diffRls(expected, actual, { columnGrants: (input.fields ?? input.config.rls?.fields) === "views" });
-		const warnings = missingIndexes(expected, actual);
-		if (drift.length > 0) return {
-			code: 1,
-			output: [...drift, ...warnings].join("\n")
-		};
-		return {
-			code: 0,
-			output: `${warnings.map((line) => `${line}\n`).join("")}introspected ${String(expected.policies.length)} policies on ${String(expected.tables.length)} table(s) and ${String(expected.helpers.length)} helper(s): no drift`
-		};
+		const drift = diffRls(expected, actual, { columnGrants: (input.fields ?? input.config.rls?.fields) !== void 0 });
+		return verifyResult({
+			findings: [...drift, ...missingIndexes(expected, actual)],
+			ignore,
+			summary: `introspected ${String(expected.policies.length)} policies on ${String(expected.tables.length)} table(s) and ${String(expected.helpers.length)} helper(s): no drift`
+		});
 	} catch (cause) {
 		return usageResult(cause);
 	}
@@ -2467,8 +2407,8 @@ async function runRls(input) {
 			});
 		}
 		case "import": {
-			await requirePeer(() => import("pgsql-parser"), "pgsql-parser", "permdock rls import", input.cwd);
-			const { runRlsImport } = await import("./import-wyqXUyjm.js");
+			await requirePeer(() => import("pgsql-parser"), "pgsql-parser", "permdock rls import", input.cwd, PGSQL_PARSER_MAJOR);
+			const { runRlsImport } = await import("./import-Bz0GefWg.js");
 			return runRlsImport({
 				cwd: input.cwd,
 				config: input.config,
@@ -2490,7 +2430,8 @@ async function runRls(input) {
 				...input.db === void 0 ? {} : { db: input.db },
 				...input.exec === void 0 ? {} : { exec: input.exec }
 			});
-			if (input.introspect) return introspect(input);
+			const ignore = verifyIgnores(input.config, input.ignore);
+			if (input.introspect) return introspect(input, ignore);
 			const format = input.format ?? "node";
 			if (format !== "node" && format !== "pgtap") return {
 				code: 2,
@@ -2502,13 +2443,16 @@ async function runRls(input) {
 				format,
 				tree: input.tree,
 				io: input.io,
+				...input.out === void 0 ? {} : { out: input.out },
 				...input.fixtures === void 0 ? {} : { fixtures: input.fixtures },
 				...input.db === void 0 ? {} : { db: input.db },
 				...input.from === void 0 ? {} : { from: input.from },
-				...input.connect === void 0 ? {} : { connect: input.connect }
+				...input.connect === void 0 ? {} : { connect: input.connect },
+				ignore
 			});
 		}
 		case "migrate": return migrate(input);
+		case "explain": return explain(input);
 		default: return {
 			code: 2,
 			output: RLS_HELP