permdock 0.3.0 → 0.4.0

package/dist/{policy-xyWg7QdR.js → role-builder-B4GbKM-i.js}

@@ -1,15 +1,14 @@
-import { n as isReadonlyArray, r as sole, t as compact } from "./compact-y6vfu2_f.js";
+import { a as sole, n as isReadonlyArray, t as compact } from "./compact-CAf557ZB.js";
 import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
-import { D as ownKeys, T as isForbiddenKey, _ as listPermissions, f as isFieldRelation, g as isSelfParented, h as isRegistryTree, i as findPermission, p as isPermission, s as getRegistry, t as annotationsFor, w as assertSafeKey } from "./permissions-DVoF6dMt.js";
-import { c as isConditionRef, l as isSqlFunctionField, n as isSubjectRef, o as isCondition, s as isConditionDate } from "./refs-KYb4ntaz.js";
-import { c as isUserApprover, i as flattenApprovers, l as user, o as isAnyOfInput, r as approverLeaves, s as isPermissionApprover } from "./approvers-DT4AVyIg.js";
-import { n as defineScopes, o as resolveScope } from "./scopes-CVdPrWN-.js";
+import { a as assertSafeKey, c as ownKeys, o as isForbiddenKey } from "./thenable-QSmvt-vZ.js";
+import { c as isConditionRef, l as isSqlFunctionField, n as isSubjectRef, o as isCondition, s as isConditionDate } from "./refs-f3imMjNW.js";
+import { c as isUserApprover, i as flattenApprovers, l as user, o as isAnyOfInput, r as approverLeaves, s as isPermissionApprover } from "./approvers-CqPOLD-o.js";
+import { n as assertMetaValue, r as parseAppData, t as assertAppData } from "./app-data-CV8pqqMi.js";
 import { t as parseDuration } from "./duration-xK2jGFVc.js";
-import { E as listRoles, a as authenticated, g as relationStart, h as relationHops, l as inheritCondition, r as asGrantee, s as flattenGrantee, u as isGraphRelation, v as roleNameOf, w as isRole, y as roleScopeOf } from "./grantee-Cv5Sogfv.js";
-import { t as canonicalJson } from "./canonical-json-DemiK4Vp.js";
-import { i as sanitizeFields } from "./fields-BMl1RxoX.js";
-import { n as sha256, t as bytesToBase64Url } from "./sha256-BO0swRXL.js";
-import { f as relatesTo, h as scopeField, n as normalizeValidity, s as memberOfFields } from "./validity-uOp8UpYn.js";
+import { c as listPermissions, o as isPermission } from "./permission-registry-BsblpB-z.js";
+import { d as isSelfParented } from "./resource-relations-D1Un3pcz.js";
+import { a as authenticated, d as roleScopeOf, g as isRole, o as flattenGrantee, r as asGrantee, u as roleNameOf } from "./grantee-CXY-0C87.js";
+import { n as normalizeValidity, o as sanitizeFields } from "./validity-dVrUEPJt.js";
 //#region src/conditions/opaque.ts
 function opaque(input) {
 	return freezeDeep({
@@ -213,6 +212,153 @@ function normalizeWhere(input) {
 	});
 }
 //#endregion
+//#region src/core/approval-normalize.ts
+/** Every approver a requirement names: `by`, each stage and its escalation, and `escalation.to`, inside `anyOf` groups too. */
+function approversOf(requirement) {
+	return [
+		...approverLeaves(requirement.by),
+		...(requirement.stages ?? []).flatMap((stage) => approverLeaves(stage.by).concat(approverLeaves(stage.escalation?.to))),
+		...approverLeaves(requirement.escalation?.to)
+	];
+}
+function asApprover(input) {
+	if (isPermissionApprover(input)) {
+		if (typeof input.permission !== "string" || input.permission === "") throw new Error("PermDock: a permission approver needs a permission key");
+		return Object.freeze({
+			kind: "permission",
+			permission: input.permission
+		});
+	}
+	if (isAnyOfInput(input)) {
+		if (!Array.isArray(input.of) || input.of.length === 0) throw new Error("PermDock: anyOf() needs at least one approver");
+		const of = input.of.map((item) => {
+			const normalized = asApprover(item);
+			const items = flattenApprovers(normalized);
+			if (items.length === 0) throw new Error("PermDock: an anyOf() item names no approver");
+			const [first] = items;
+			return isReadonlyArray(normalized) || first === void 0 ? items : first;
+		});
+		return Object.freeze({
+			kind: "any-of",
+			of: Object.freeze(of)
+		});
+	}
+	if (isReadonlyArray(input)) {
+		const items = [];
+		for (const item of input) items.push(...flattenApprovers(asApprover(item)));
+		return items;
+	}
+	if (isUserApprover(input)) return user(input.id);
+	return asGrantee(input);
+}
+function normalizeApproval(approval, permission) {
+	if (approval === void 0) return;
+	if (approval === "human") return "human";
+	if (approval.staleOn !== void 0 && approval.staleOn !== "resource-change") throw new Error(`PermDock: approval staleOn must be 'resource-change', got '${String(approval.staleOn)}'`);
+	const label = permission ?? "a grant";
+	assertQuorum(approval.quorum, "approval.quorum", label);
+	if (approval.ttl !== void 0 && parseDuration(approval.ttl) === void 0) throw new Error(`PermDock: approval.ttl on '${label}' must be a duration such as '30m', got '${approval.ttl}'`);
+	const escalation = normalizeEscalation(approval.escalation, label);
+	const mode = approval.mode ?? "any";
+	if (mode !== "any") return compact({
+		mode,
+		stages: normalizeStages(approval, mode, label),
+		distinct: approval.distinct,
+		staleOn: approval.staleOn,
+		ttl: approval.ttl,
+		escalation
+	});
+	if (approval.stages !== void 0) throw new Error(`PermDock: approval.stages on '${label}' needs mode: 'all' or 'sequential'`);
+	const by = approval.by === void 0 ? void 0 : asApprover(approval.by);
+	if (by === void 0 && approval.distinct === void 0 && approval.staleOn === void 0 && approval.quorum === void 0 && approval.ttl === void 0 && escalation === void 0) return "human";
+	return compact({
+		by: by ?? authenticated(),
+		distinct: approval.distinct,
+		staleOn: approval.staleOn,
+		quorum: approval.quorum,
+		ttl: approval.ttl,
+		escalation
+	});
+}
+function assertQuorum(quorum, name, label) {
+	if (quorum !== void 0 && (!Number.isInteger(quorum) || quorum < 1)) throw new Error(`PermDock: ${name} on '${label}' must be an integer of at least 1, got ${String(quorum)}`);
+}
+function normalizeStages(approval, mode, label) {
+	if (mode !== "all" && mode !== "sequential") throw new Error(`PermDock: approval.mode on '${label}' must be 'any', 'all' or 'sequential', got '${mode}'`);
+	if (approval.by !== void 0 || approval.quorum !== void 0) throw new Error(`PermDock: approval on '${label}' sets mode '${mode}': put by and quorum on each stage`);
+	const stages = approval.stages ?? [];
+	if (stages.length === 0) throw new Error(`PermDock: approval mode '${mode}' on '${label}' needs at least one stage`);
+	return stages.map((stage, index) => {
+		assertQuorum(stage.quorum, `approval.stages[${index}].quorum`, label);
+		const by = asApprover(stage.by);
+		if (flattenApprovers(by).length === 0) throw new Error(`PermDock: approval.stages[${index}].by on '${label}' names no approver`);
+		return compact({
+			by,
+			quorum: stage.quorum,
+			escalation: normalizeEscalation(stage.escalation, label)
+		});
+	});
+}
+function normalizeEscalation(escalation, label) {
+	if (escalation === void 0) return;
+	if (parseDuration(escalation.after) === void 0) throw new Error(`PermDock: approval.escalation.after on '${label}' must be a duration such as '4h', got '${escalation.after}'`);
+	return {
+		after: escalation.after,
+		to: asApprover(escalation.to)
+	};
+}
+/**
+* A role with `activation` is eligible-only: it needs a positive `maxDuration`
+* (Doctor PD033 warns without one). `justification` defaults to `'optional'`.
+*/
+function activationApproval(option, roleName) {
+	const label = `activation of '${roleName}'`;
+	const approval = normalizeApproval(option, label);
+	if (approval !== void 0 && approval !== "human" && approversOf(approval).some((item) => item.kind === "relation")) throw new Error(`PermDock: approval on ${label} names a relation; an activation has no row to read it on`);
+	return approval;
+}
+/**
+* A stale-on-change approval needs a row to version: an instance permission
+* whose resource declares `version`.
+*/
+function assertApprovalVersions(grants, resources) {
+	for (const grant of grants) {
+		const approval = grant.approval;
+		if (approval === void 0 || approval === "human" || approval.staleOn === void 0) continue;
+		if (grant.permission.kind !== "instance") throw new Error(`PermDock: approval staleOn on '${grant.permission.key}' needs an instance action; a collection action has no row to version`);
+		if (resources.get(grant.permission.resource)?.version === void 0) throw new Error(`PermDock: approval staleOn on '${grant.permission.key}' needs resource(..., { version: '<field>' }) on '${grant.permission.resource}'`);
+	}
+}
+/**
+* A relation approver is checked by id, from the requested row: the
+* relation lives on the permission's own resource (optionally up its parent
+* chain), or at the end of a list of links from it.
+*/
+function assertApprovalRelations(grants, resources) {
+	for (const grant of grants) {
+		const approval = grant.approval;
+		if (approval === void 0 || approval === "human") continue;
+		for (const item of approversOf(approval)) {
+			if (item.kind !== "relation") continue;
+			const label = `${grant.permission.key}: approver relation '${item.relation}'`;
+			if (grant.permission.kind !== "instance") throw new Error(`PermDock: ${label} needs an instance action; a collection action has no row to read it on`);
+			if (approverRelationResource(grant.permission.resource, item.through, resources) !== item.resource) throw new Error(`PermDock: ${label} must live on '${grant.permission.resource}' or at the end of its through links`);
+			if (resources.get(item.resource)?.relations[item.relation] === void 0) throw new Error(`PermDock: ${label} is not declared on '${item.resource}'`);
+		}
+	}
+}
+/** The resource a relation approver's `through` reaches from `start`, or `undefined`. */
+function approverRelationResource(start, through, resources) {
+	if (through === void 0) return start;
+	if (through === "parent") return isSelfParented(resources.get(start)) ? start : void 0;
+	let current = start;
+	for (const name of through) {
+		const node = current === void 0 ? void 0 : resources.get(current);
+		current = node !== void 0 && Object.hasOwn(node.links, name) ? node.links[name]?.resource : void 0;
+	}
+	return current;
+}
+//#endregion
 //#region src/core/limits.ts
 const UNIT_SECONDS = {
 	s: 1,
@@ -427,119 +573,7 @@ function applyQuota(input) {
 	}
 }
 //#endregion
-//#region src/core/policy.ts
-/** Every approver a requirement names: `by`, each stage and its escalation, and `escalation.to`, inside `anyOf` groups too. */
-function approversOf(requirement) {
-	return [
-		...approverLeaves(requirement.by),
-		...(requirement.stages ?? []).flatMap((stage) => approverLeaves(stage.by).concat(approverLeaves(stage.escalation?.to))),
-		...approverLeaves(requirement.escalation?.to)
-	];
-}
-function asApprover(input) {
-	if (isPermissionApprover(input)) {
-		if (typeof input.permission !== "string" || input.permission === "") throw new Error("PermDock: a permission approver needs a permission key");
-		return Object.freeze({
-			kind: "permission",
-			permission: input.permission
-		});
-	}
-	if (isAnyOfInput(input)) {
-		if (!Array.isArray(input.of) || input.of.length === 0) throw new Error("PermDock: anyOf() needs at least one approver");
-		const of = input.of.map((item) => {
-			const normalized = asApprover(item);
-			const items = flattenApprovers(normalized);
-			if (items.length === 0) throw new Error("PermDock: an anyOf() item names no approver");
-			const [first] = items;
-			return isReadonlyArray(normalized) || first === void 0 ? items : first;
-		});
-		return Object.freeze({
-			kind: "any-of",
-			of: Object.freeze(of)
-		});
-	}
-	if (isReadonlyArray(input)) {
-		const items = [];
-		for (const item of input) items.push(...flattenApprovers(asApprover(item)));
-		return items;
-	}
-	if (isUserApprover(input)) return user(input.id);
-	return asGrantee(input);
-}
-function indexPolicy(roles, grants, vocabulary) {
-	const declaredRoles = new Set(roles.map((item) => item.name));
-	for (const leaf of listRoles(vocabulary.roles)) declaredRoles.add(leaf.key);
-	const supports = roles.flatMap((binding) => binding.support === void 0 ? [] : [binding.support]);
-	const listed = grants.length > 0 ? grants : roles.flatMap((binding) => binding.grants);
-	const byKey = /* @__PURE__ */ new Map();
-	for (const grant of listed) {
-		const bucket = byKey.get(grant.permission.key);
-		if (bucket === void 0) byKey.set(grant.permission.key, [grant]);
-		else bucket.push(grant);
-	}
-	for (const bucket of byKey.values()) Object.freeze(bucket);
-	return freezeDeep({
-		declaredRoles,
-		supports,
-		grantsByKey: byKey
-	});
-}
-function normalizeApproval(approval, permission) {
-	if (approval === void 0) return;
-	if (approval === "human") return "human";
-	if (approval.staleOn !== void 0 && approval.staleOn !== "resource-change") throw new Error(`PermDock: approval staleOn must be 'resource-change', got '${String(approval.staleOn)}'`);
-	const label = permission ?? "a grant";
-	assertQuorum(approval.quorum, "approval.quorum", label);
-	if (approval.ttl !== void 0 && parseDuration(approval.ttl) === void 0) throw new Error(`PermDock: approval.ttl on '${label}' must be a duration such as '30m', got '${approval.ttl}'`);
-	const escalation = normalizeEscalation(approval.escalation, label);
-	const mode = approval.mode ?? "any";
-	if (mode !== "any") return compact({
-		mode,
-		stages: normalizeStages(approval, mode, label),
-		distinct: approval.distinct,
-		staleOn: approval.staleOn,
-		ttl: approval.ttl,
-		escalation
-	});
-	if (approval.stages !== void 0) throw new Error(`PermDock: approval.stages on '${label}' needs mode: 'all' or 'sequential'`);
-	const by = approval.by === void 0 ? void 0 : asApprover(approval.by);
-	if (by === void 0 && approval.distinct === void 0 && approval.staleOn === void 0 && approval.quorum === void 0 && approval.ttl === void 0 && escalation === void 0) return "human";
-	return compact({
-		by: by ?? authenticated(),
-		distinct: approval.distinct,
-		staleOn: approval.staleOn,
-		quorum: approval.quorum,
-		ttl: approval.ttl,
-		escalation
-	});
-}
-function assertQuorum(quorum, name, label) {
-	if (quorum !== void 0 && (!Number.isInteger(quorum) || quorum < 1)) throw new Error(`PermDock: ${name} on '${label}' must be an integer of at least 1, got ${String(quorum)}`);
-}
-function normalizeStages(approval, mode, label) {
-	if (mode !== "all" && mode !== "sequential") throw new Error(`PermDock: approval.mode on '${label}' must be 'any', 'all' or 'sequential', got '${mode}'`);
-	if (approval.by !== void 0 || approval.quorum !== void 0) throw new Error(`PermDock: approval on '${label}' sets mode '${mode}': put by and quorum on each stage`);
-	const stages = approval.stages ?? [];
-	if (stages.length === 0) throw new Error(`PermDock: approval mode '${mode}' on '${label}' needs at least one stage`);
-	return stages.map((stage, index) => {
-		assertQuorum(stage.quorum, `approval.stages[${index}].quorum`, label);
-		const by = asApprover(stage.by);
-		if (flattenApprovers(by).length === 0) throw new Error(`PermDock: approval.stages[${index}].by on '${label}' names no approver`);
-		return compact({
-			by,
-			quorum: stage.quorum,
-			escalation: normalizeEscalation(stage.escalation, label)
-		});
-	});
-}
-function normalizeEscalation(escalation, label) {
-	if (escalation === void 0) return;
-	if (parseDuration(escalation.after) === void 0) throw new Error(`PermDock: approval.escalation.after on '${label}' must be a duration such as '4h', got '${escalation.after}'`);
-	return {
-		after: escalation.after,
-		to: asApprover(escalation.to)
-	};
-}
+//#region src/core/grant-builders.ts
 function isClosure(value) {
 	return typeof value === "function";
 }
@@ -548,78 +582,6 @@ function flattenPermissions(input) {
 	if (isReadonlyArray(input)) return input.flatMap((item) => flattenPermissions(item));
 	return [...listPermissions(input)];
 }
-function delegationTarget(to, index) {
-	if (typeof to === "string") return { kind: to };
-	if ("actor" in to) return { kind: to.actor };
-	const target = compact({
-		kind: to.kind,
-		id: to.id,
-		client: to.client
-	});
-	if (typeof target.kind !== "string" || target.kind === "") throw new Error(`PermDock: delegations[${index}].to needs an actor kind, such as actor('eve')`);
-	if (target.id !== void 0 && (typeof target.id !== "string" || target.id === "")) throw new Error(`PermDock: delegations[${index}].to.id must be a non-empty string`);
-	if (target.client !== void 0 && (typeof target.client !== "string" || target.client === "")) throw new Error(`PermDock: delegations[${index}].to.client must be a non-empty string`);
-	if (target.id !== void 0 && target.client !== void 0) throw new Error(`PermDock: delegations[${index}].to names both an id and a client; name one`);
-	return target;
-}
-function normalizeDelegation(input, index, tree) {
-	const label = `delegations[${index}]`;
-	const from = asGrantee(input.from);
-	const items = flattenGrantee(from);
-	if (items.length === 0) throw new Error(`PermDock: ${label}.from names nobody`);
-	if (items.some((item) => item.kind === "relation" || item.kind === "inherit")) throw new Error(`PermDock: ${label}.from names a relation or inherit(); a delegation is matched without a row, so name a role or another subject-only grantee`);
-	if (items.some((item) => item.kind === "actor")) throw new Error(`PermDock: ${label}.from names an actor; the principal hands over, the actor is \`to\``);
-	const leaves = /* @__PURE__ */ new Map();
-	for (const leaf of input.permissions.flatMap((item) => flattenPermissions(item))) {
-		if (findPermission(tree, leaf.key) === void 0) throw new Error(`PermDock: ${label} names unknown permission '${leaf.key}'`);
-		leaves.set(leaf.key, leaf);
-	}
-	const keys = [...leaves.keys()].toSorted();
-	if (keys.length === 0) throw new Error(`PermDock: ${label}.permissions is empty`);
-	return compact({
-		from,
-		to: delegationTarget(input.to, index),
-		permissions: keys,
-		readOnly: [...leaves.values()].filter((leaf) => annotationsFor(leaf).readOnlyHint).map((leaf) => leaf.key).toSorted(),
-		validity: normalizeValidity(input, label)
-	});
-}
-/** RFC 6749 section 3.3 `scope-token`: printable ASCII without space, `"` or `\`. */
-function isScopeToken(value) {
-	return /^[!#-[\]-~]+$/u.test(value);
-}
-function normalizeOAuthScopes(input, tree) {
-	if (input === void 0) return [];
-	const own = new Set(listPermissions(tree).map((leaf) => leaf.scope));
-	return Object.entries(input).map(([scope, items]) => {
-		if (!isScopeToken(scope)) throw new Error(`PermDock: oauthScopes key '${scope}' is not an OAuth scope token`);
-		if (own.has(scope)) throw new Error(`PermDock: oauthScopes key '${scope}' is a permission's own scope`);
-		const leaves = /* @__PURE__ */ new Map();
-		for (const leaf of (Array.isArray(items) ? items : []).flatMap((item) => flattenPermissions(item))) {
-			if (findPermission(tree, leaf.key) === void 0) throw new Error(`PermDock: oauthScopes '${scope}' names unknown permission '${leaf.key}'`);
-			leaves.set(leaf.key, leaf);
-		}
-		if (leaves.size === 0) throw new Error(`PermDock: oauthScopes '${scope}' covers no permission`);
-		const sorted = [...leaves.values()].toSorted((a, b) => a.key.localeCompare(b.key));
-		return {
-			scope,
-			permissions: sorted.map((leaf) => leaf.key),
-			scopes: sorted.map((leaf) => leaf.scope)
-		};
-	});
-}
-function resolveRoleScope(on) {
-	if (on === void 0) return "global";
-	if (typeof on === "string") {
-		if (on === "global" || on === "resource") throw new Error(`PermDock: role on: '${on}' is not a scope name`);
-		return on;
-	}
-	const permissions = flattenPermissions(on);
-	const names = new Set(permissions.map((permission) => permission.resource));
-	const [resource] = names;
-	if (names.size !== 1 || resource === void 0) throw new Error("PermDock: role on: resource must name exactly one resource");
-	return { resource };
-}
 const GROUP = /^[a-z][a-z0-9_-]*$/u;
 function grantGroup(group, key) {
 	if (group === void 0) return;
@@ -661,11 +623,64 @@ function makeGrant(permission, effect, condition) {
 		fields: sanitizeFields(condition?.fields),
 		name: condition?.name,
 		group: grantGroup(condition?.group, permission.key),
+		meta: grantMeta(condition?.meta, permission.key, void 0),
+		obligations: appObligations(condition?.obligations, permission.key, effect),
 		purpose,
 		validity: normalizeValidity(condition ?? {}, permission.key),
 		requires
 	});
 }
+/** Checks a grant's `meta`: plain JSON, string `description`, `x` through the schema when given. */
+function grantMeta(meta, key, schema) {
+	if (meta === void 0) return;
+	assertAppData(meta, `meta of a grant on ${key}`);
+	const { description, x } = meta;
+	if (description !== void 0 && typeof description !== "string") throw new TypeError(`PermDock: meta.description of a grant on ${key} must be a string`);
+	return freezeDeep(compact({
+		description,
+		x: x === void 0 ? void 0 : parseAppData(schema, x, `meta.x of a grant on ${key}`)
+	}));
+}
+function appObligations(input, key, effect) {
+	if (input === void 0) return;
+	if (effect !== "allow") throw new Error(`PermDock: obligations are allowed on an allow only; '${key}' is a deny`);
+	const list = input;
+	if (!Array.isArray(list)) throw new TypeError(`PermDock: obligations on '${key}' must be a list`);
+	const items = list;
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const item of items) {
+		const entry = typeof item === "object" && item !== null ? item : void 0;
+		const name = typeof item === "string" ? item : entry === void 0 ? void 0 : Reflect.get(entry, "name");
+		if (typeof name !== "string" || !GROUP.test(name)) throw new Error(`PermDock: obligation '${String(name)}' on '${key}' must be lower case letters, digits, _ or -, starting with a letter`);
+		if (seen.has(name)) throw new Error(`PermDock: obligation '${name}' is listed twice on '${key}'`);
+		seen.add(name);
+		const detail = entry === void 0 ? void 0 : Reflect.get(entry, "detail");
+		if (detail === void 0) {
+			out.push({
+				kind: "app",
+				name
+			});
+			continue;
+		}
+		assertMetaValue(detail, `detail of obligation '${name}' on '${key}'`);
+		out.push({
+			kind: "app",
+			name,
+			detail
+		});
+	}
+	return out.length === 0 ? void 0 : freezeDeep(out);
+}
+/** Re-checks every grant's `meta.x` with the policy's grant schema, keeping the schema output. */
+function withGrantSchema(grant, schema) {
+	const meta = grant.meta;
+	if (schema === void 0 || meta?.x === void 0) return grant;
+	return freezeDeep({
+		...grant,
+		meta: grantMeta(meta, grant.permission.key, schema) ?? meta
+	});
+}
 function requiredKey(input, permission, effect) {
 	if (input === void 0) return;
 	if (effect !== "allow") throw new Error(`PermDock: requires is allowed on an allow only; '${permission.key}' is a deny`);
@@ -688,6 +703,30 @@ function flattenGrants(grants) {
 	else out.push(grant);
 	return out;
 }
+function completeGrant(grant) {
+	const to = flattenGrantee(grant.to);
+	const first = to[0];
+	if (to.length === 1 && first?.kind === "role" && first.role === "") throw new Error("PermDock: grant is missing to");
+	return freezeDeep({
+		...grant,
+		role: roleNameOf(grant.to),
+		scope: roleScopeOf(grant.to)
+	});
+}
+//#endregion
+//#region src/core/role-builder.ts
+function resolveRoleScope(on) {
+	if (on === void 0) return "global";
+	if (typeof on === "string") {
+		if (on === "global" || on === "resource") throw new Error(`PermDock: role on: '${on}' is not a scope name`);
+		return on;
+	}
+	const permissions = flattenPermissions(on);
+	const names = new Set(permissions.map((permission) => permission.resource));
+	const [resource] = names;
+	if (names.size !== 1 || resource === void 0) throw new Error("PermDock: role on: resource must name exactly one resource");
+	return { resource };
+}
 function role(name, grants, options) {
 	if (options !== void 0 && Object.hasOwn(options, "restricted")) throw new Error(`PermDock: role option 'restricted' is reserved`);
 	const leaf = isRole(name) ? name : void 0;
@@ -723,16 +762,6 @@ function role(name, grants, options) {
 		activation
 	}));
 }
-/**
-* A role with `activation` is eligible-only: it needs a positive `maxDuration`
-* (Doctor PD033 warns without one). `justification` defaults to `'optional'`.
-*/
-function activationApproval(option, roleName) {
-	const label = `activation of '${roleName}'`;
-	const approval = normalizeApproval(option, label);
-	if (approval !== void 0 && approval !== "human" && approversOf(approval).some((item) => item.kind === "relation")) throw new Error(`PermDock: approval on ${label} names a relation; an activation has no row to read it on`);
-	return approval;
-}
 function normalizeActivation(roleName, option) {
 	if (option === void 0) return;
 	const justification = option.justification ?? "optional";
@@ -783,340 +812,5 @@ function roleRules(roleName, scope, options) {
 		for: nameList(roleName, "for", options?.for)
 	});
 }
-function canonicalPolicy(grants, delegations, levels) {
-	const payload = canonicalGrants(grants);
-	const withDelegations = delegations.length === 0 ? payload : `${payload}\n${JSON.stringify(delegations)}`;
-	return levels === void 0 ? withDelegations : `${withDelegations}\nlevels:${canonicalJson(levels)}`;
-}
-function normalizeLevels(resources) {
-	const out = {};
-	for (const node of resources.values()) {
-		const entries = Object.entries({ ...node.levels });
-		if (entries.length === 0) continue;
-		const levels = {};
-		for (const [name, input] of entries) try {
-			levels[name] = Object.keys(input).length === 0 ? {
-				op: "and",
-				conditions: []
-			} : normalizeWhere(input);
-		} catch (error) {
-			throw new Error(`PermDock: level '${name}' on '${node.name}' is not a valid condition`, { cause: error });
-		}
-		out[node.name] = levels;
-	}
-	return Object.keys(out).length === 0 ? void 0 : freezeDeep(out);
-}
-/** Declared levels of `resource` with their conditions, in declaration order. */
-function policyLevels(policy, resource) {
-	const levels = policy.levels;
-	return levels !== void 0 && Object.hasOwn(levels, resource) ? Object.entries({ ...levels[resource] }) : [];
-}
-/** The condition of `level` on `resource`, if the policy declares it. */
-function levelCondition(policy, resource, level) {
-	return policyLevels(policy, resource).find(([name]) => name === level)?.[1];
-}
-/** Declared level names of `resource`, in declaration order. */
-function levelNames(policy, resource) {
-	return policyLevels(policy, resource).map(([name]) => name);
-}
-function canonicalGrants(grants) {
-	const payload = grants.map((grant) => ({
-		permission: grant.permission.key,
-		effect: grant.effect,
-		to: grant.to,
-		role: grant.role,
-		where: grant.where,
-		check: grant.check,
-		approval: grant.approval,
-		portable: grant.portable,
-		fields: grant.fields,
-		scope: grant.scope,
-		name: grant.name,
-		purpose: grant.purpose,
-		breakGlass: grant.breakGlass,
-		viaOnly: grant.viaOnly,
-		validity: grant.validity,
-		requires: grant.requires
-	}));
-	return JSON.stringify(payload);
-}
-function assertParentGraph(resources) {
-	for (const node of resources.values()) {
-		if (node.parent === void 0) continue;
-		if (!resources.has(node.parent.resource)) throw new Error(`PermDock: resource '${node.name}' parents unknown resource '${node.parent.resource}'`);
-	}
-}
-/**
-* Graph relation grantees must reach their resource: `through: 'parent'` from
-* the row to its parent resource or along its own self-parent, and never over
-* a `memberOf` relation, which is tenancy, not the object graph.
-*/
-function assertRelationGrants(grants, resources) {
-	for (const grant of grants) for (const item of flattenGrantee(grant.to)) {
-		if (item.kind !== "relation" || !isGraphRelation(item, resources)) continue;
-		const label = `grant ${grant.permission.key} relation '${item.relation}'`;
-		const target = resources.get(item.resource);
-		const spec = target?.relations[item.relation];
-		if (target === void 0 || spec === void 0) throw new Error(`PermDock: ${label}: ${item.resource} does not declare it`);
-		if (isFieldRelation(spec) && spec.memberOf !== void 0) throw new Error(`PermDock: ${label} is a memberOf relation; through walks the object graph, not scopes`);
-		const row = resources.get(grant.permission.resource);
-		if (Array.isArray(item.through)) {
-			if (relationHops(item, row, resources) === void 0) throw new Error(`PermDock: ${label}: the links [${item.through.join(", ")}] from ${grant.permission.resource} do not end on ${target.name}${(item.depth ?? 0) > 0 ? ` (or ${target.name} does not parent itself for depth)` : ""}`);
-			continue;
-		}
-		if (item.through === "parent" && target.name === row?.name && !isSelfParented(target)) throw new Error(`PermDock: ${label}: through: 'parent' needs ${target.name} to parent itself`);
-		if (relationStart(item, row, target) === void 0) throw new Error(item.through === void 0 ? `PermDock: ${label} is on ${target.name}, not ${grant.permission.resource}; add through: 'parent'` : `PermDock: ${label}: ${grant.permission.resource} has no parent on ${target.name}`);
-	}
-}
-function assertInheritGrants(grants, resources, tree) {
-	const keys = new Set(listPermissions(tree).map((leaf) => leaf.key));
-	const edges = /* @__PURE__ */ new Map();
-	for (const grant of grants) for (const item of flattenGrantee(grant.to)) {
-		if (item.kind !== "inherit") continue;
-		const label = `grant ${grant.permission.key} inherit '${item.permission}'`;
-		if (grant.effect !== "allow") throw new Error(`PermDock: ${label}: inherit() is allowed on an allow only`);
-		if (grant.permission.kind !== "instance") throw new Error(`PermDock: ${label}: inherit() needs an instance action; a collection action has no row to follow`);
-		if (!keys.has(item.permission)) throw new Error(`PermDock: ${label}: the policy does not declare it`);
-		if (inheritCondition(item, resources.get(grant.permission.resource), resources) === void 0) throw new Error(item.through === "parent" ? `PermDock: ${label}: ${grant.permission.resource} has no parent on ${item.resource}` : `PermDock: ${label}: the links [${item.through.join(", ")}] from ${grant.permission.resource} do not end on ${item.resource}`);
-		const next = edges.get(grant.permission.key) ?? /* @__PURE__ */ new Set();
-		next.add(item.permission);
-		edges.set(grant.permission.key, next);
-	}
-	const done = /* @__PURE__ */ new Set();
-	const visit = (key, path) => {
-		if (path.includes(key)) throw new Error(`PermDock: inherit() grants form a cycle: ${[...path.slice(path.indexOf(key)), key].join(" -> ")}`);
-		if (done.has(key)) return;
-		for (const target of edges.get(key) ?? []) visit(target, [...path, key]);
-		done.add(key);
-	};
-	for (const key of edges.keys()) visit(key, []);
-}
-function scopeOfGrant(scope, declared) {
-	if (typeof scope !== "string" || scope === "global") return scope;
-	const resolved = resolveScope(declared, scope);
-	if (resolved === void 0) throw new Error(`PermDock: definePolicy({ scopes }) must declare '${scope}' for on: '${scope}' roles`);
-	return resolved;
-}
-function rescopeGrantee(to, declared) {
-	const items = flattenGrantee(to);
-	if (!items.some((item) => item.kind === "role")) return to;
-	const mapped = items.map((item) => item.kind === "role" ? freezeDeep({
-		...item,
-		scope: scopeOfGrant(item.scope, declared)
-	}) : item);
-	if (Array.isArray(to)) return freezeDeep(mapped);
-	const [single] = mapped;
-	return single ?? to;
-}
-/** Resolves `tenant` / `team` aliases to declared names; an undeclared scope throws. */
-function rescopeGrant(grant, declared) {
-	const scope = scopeOfGrant(grant.scope, declared);
-	const to = rescopeGrantee(grant.to, declared);
-	if (scope === grant.scope && to === grant.to) return grant;
-	return freezeDeep({
-		...grant,
-		scope,
-		to
-	});
-}
-function rescopeBinding(binding, declared) {
-	const grants = binding.grants.map((grant) => rescopeGrant(grant, declared));
-	const on = typeof binding.on === "string" ? scopeOfGrant(binding.on, declared) : binding.on;
-	return freezeDeep(compact({
-		...binding,
-		grants,
-		on
-	}));
-}
-/**
-* No implicit cascade: a grant on scope S reaches a row only through the row's
-* own S key, so every resource an instance grant on S touches declares a
-* `memberOf: S` relation on that key. Without it `where()` and RLS could not
-* narrow the rows.
-*/
-function assertScopeKeys(grants, scopes, resources) {
-	for (const grant of grants) {
-		if (typeof grant.scope !== "string" || grant.scope === "global" || grant.permission.kind !== "instance") continue;
-		const key = scopes.find((scope) => scope.name === grant.scope)?.key;
-		const node = resources.get(grant.permission.resource);
-		if (key === void 0 || node === void 0) continue;
-		const fields = memberOfFields(node, grant.scope, scopes);
-		if (fields.length > 1 && !fields.includes(key)) throw new Error(`PermDock: resource '${node.name}' declares several memberOf relations to '${grant.scope}' (${fields.join(", ")}); name the one holding the instance with the scope's key '${key}'`);
-		const field = scopeField(node, grant.scope, scopes);
-		if (field !== void 0 && relatesTo(node, field, grant.scope, scopes)) continue;
-		throw new Error(`PermDock: resource '${node.name}' needs relations: { <name>: { field: '${key}', memberOf: '${grant.scope}' } } for ${grant.permission.key} on '${grant.scope}' roles`);
-	}
-}
-/** A `requires` names a permission the policy declares. */
-function assertRequires(grants, tree) {
-	const keys = new Set(listPermissions(tree).map((leaf) => leaf.key));
-	for (const grant of grants) for (const key of grant.requires ?? []) if (!keys.has(key)) throw new Error(`PermDock: '${grant.permission.key}' requires '${key}', which the policy does not declare`);
-}
-/**
-* A stale-on-change approval needs a row to version: an instance permission
-* whose resource declares `version`.
-*/
-function assertApprovalVersions(grants, resources) {
-	for (const grant of grants) {
-		const approval = grant.approval;
-		if (approval === void 0 || approval === "human" || approval.staleOn === void 0) continue;
-		if (grant.permission.kind !== "instance") throw new Error(`PermDock: approval staleOn on '${grant.permission.key}' needs an instance action; a collection action has no row to version`);
-		if (resources.get(grant.permission.resource)?.version === void 0) throw new Error(`PermDock: approval staleOn on '${grant.permission.key}' needs resource(..., { version: '<field>' }) on '${grant.permission.resource}'`);
-	}
-}
-/**
-* A relation approver is checked by id, from the requested row: the
-* relation lives on the permission's own resource (optionally up its parent
-* chain), or at the end of a list of links from it.
-*/
-function assertApprovalRelations(grants, resources) {
-	for (const grant of grants) {
-		const approval = grant.approval;
-		if (approval === void 0 || approval === "human") continue;
-		for (const item of approversOf(approval)) {
-			if (item.kind !== "relation") continue;
-			const label = `${grant.permission.key}: approver relation '${item.relation}'`;
-			if (grant.permission.kind !== "instance") throw new Error(`PermDock: ${label} needs an instance action; a collection action has no row to read it on`);
-			if (approverRelationResource(grant.permission.resource, item.through, resources) !== item.resource) throw new Error(`PermDock: ${label} must live on '${grant.permission.resource}' or at the end of its through links`);
-			if (resources.get(item.resource)?.relations[item.relation] === void 0) throw new Error(`PermDock: ${label} is not declared on '${item.resource}'`);
-		}
-	}
-}
-/** The resource a relation approver's `through` reaches from `start`, or `undefined`. */
-function approverRelationResource(start, through, resources) {
-	if (through === void 0) return start;
-	if (through === "parent") return isSelfParented(resources.get(start)) ? start : void 0;
-	let current = start;
-	for (const name of through) {
-		const node = current === void 0 ? void 0 : resources.get(current);
-		current = node !== void 0 && Object.hasOwn(node.links, name) ? node.links[name]?.resource : void 0;
-	}
-	return current;
-}
-function isVocabularyInput(value) {
-	return value !== null && typeof value === "object" && "permissions" in value && isRegistryTree(value.permissions);
-}
-function completeGrant(grant) {
-	const to = flattenGrantee(grant.to);
-	const first = to[0];
-	if (to.length === 1 && first?.kind === "role" && first.role === "") throw new Error("PermDock: grant is missing to");
-	return freezeDeep({
-		...grant,
-		role: roleNameOf(grant.to),
-		scope: roleScopeOf(grant.to)
-	});
-}
-function mergeBindings(items) {
-	const merged = /* @__PURE__ */ new Map();
-	for (const item of items) {
-		const existing = merged.get(item.name);
-		if (existing === void 0) {
-			merged.set(item.name, item);
-			continue;
-		}
-		merged.set(item.name, freezeDeep(compact({
-			name: item.name,
-			grants: [...existing.grants, ...item.grants],
-			on: existing.on,
-			assignable: existing.assignable,
-			exclusiveWith: existing.exclusiveWith ?? item.exclusiveWith,
-			min: existing.min ?? item.min,
-			max: existing.max ?? item.max,
-			transferOnly: existing.transferOnly ?? item.transferOnly,
-			assigns: existing.assigns ?? item.assigns,
-			for: existing.for ?? item.for,
-			meta: existing.meta ?? item.meta,
-			activation: existing.activation ?? item.activation,
-			support: existing.support ?? item.support
-		})));
-	}
-	return {
-		roles: [...merged.values()],
-		rolesByName: merged
-	};
-}
-function definePolicy(permissions, options) {
-	const vocabulary = isVocabularyInput(permissions) ? permissions : { permissions };
-	const tree = vocabulary.permissions;
-	const mapper = options.principal ?? options.subject;
-	if (mapper === void 0) throw new Error("PermDock: definePolicy requires principal or subject");
-	const resources = getRegistry(tree);
-	assertParentGraph(resources);
-	const scopes = defineScopes(options.scopes);
-	const { roles, rolesByName } = mergeBindings((options.roles ?? []).map((binding) => rescopeBinding(binding, scopes)));
-	const declared = new Set(roles.map((item) => item.name));
-	for (const leaf of listRoles(vocabulary.roles)) declared.add(leaf.key);
-	for (const binding of roles) for (const name of binding.assigns ?? []) if (!declared.has(name)) throw new Error(`PermDock: role '${binding.name}' names undeclared role '${name}'`);
-	const fromBindings = roles.flatMap((item) => item.grants);
-	const fromGrants = flattenGrants(options.grants ?? []).map(completeGrant).map((grant) => rescopeGrant(grant, scopes));
-	const grants = [...fromBindings, ...fromGrants];
-	assertScopeKeys(grants, scopes, resources);
-	assertApprovalVersions(grants, resources);
-	assertApprovalRelations(grants, resources);
-	assertRelationGrants(grants, resources);
-	assertRequires(grants, tree);
-	assertInheritGrants(grants, resources, tree);
-	const delegations = (options.delegations ?? []).map((item, index) => normalizeDelegation(item, index, tree));
-	const levels = normalizeLevels(resources);
-	const oauthScopes = normalizeOAuthScopes(options.oauthScopes, tree);
-	const fingerprint = bytesToBase64Url(sha256(oauthScopes.length === 0 ? canonicalPolicy(grants, delegations, levels) : `${canonicalPolicy(grants, delegations, levels)}\noauthScopes:${canonicalJson(oauthScopes)}`));
-	const hostable = [...new Set((options.hostable ?? []).flatMap((item) => flattenPermissions(item).map((leaf) => leaf.key)))].toSorted();
-	const fresh = [...new Set((options.fresh ?? []).flatMap((item) => flattenPermissions(item).map((leaf) => leaf.key)))].toSorted();
-	return freezeDeep({
-		permissions: tree,
-		roles,
-		rolesByName,
-		grants,
-		vocabulary,
-		scopes,
-		principal: mapper,
-		subject: mapper,
-		context: options.context,
-		validate: options.validate ?? "boundary",
-		onDenied: options.onDenied,
-		fingerprint,
-		resources,
-		providers: options.providers,
-		hostable,
-		fresh,
-		delegations: delegations.length === 0 ? void 0 : delegations,
-		levels,
-		oauthScopes: oauthScopes.length === 0 ? void 0 : oauthScopes,
-		index: indexPolicy(roles, grants, vocabulary)
-	});
-}
-function exclusivePairs(policy) {
-	const pairs = /* @__PURE__ */ new Map();
-	for (const binding of policy.roles) if (binding.exclusiveWith !== void 0) pairs.set(binding.name, binding.exclusiveWith);
-	return pairs;
-}
-function grantList(policy) {
-	if (policy.grants !== void 0 && policy.grants.length > 0) return policy.grants;
-	return policy.roles.flatMap((binding) => binding.grants);
-}
-function declaredRoleNames(policy) {
-	return policy.index.declaredRoles;
-}
-function separationConflicts(policy, memberships) {
-	const exclusive = exclusivePairs(policy);
-	const seen = /* @__PURE__ */ new Set();
-	const conflicts = [];
-	for (const membership of memberships) {
-		const held = new Set(membership.roles);
-		for (const name of held) for (const other of exclusive.get(name) ?? []) {
-			if (!held.has(other)) continue;
-			const pair = [name, other].toSorted();
-			const key = `${membership.principal ?? ""}:${membership.tenant ?? ""}:${pair.join("+")}`;
-			if (seen.has(key)) continue;
-			seen.add(key);
-			conflicts.push(compact({
-				principal: membership.principal ?? "",
-				tenant: membership.tenant,
-				roles: pair
-			}));
-		}
-	}
-	return conflicts;
-}
 //#endregion
-export { opaque as S, memoryLimitStore as _, definePolicy as a, assertSqlFunctionArg as b, indexPolicy as c, normalizeApproval as d, normalizeAssurance as f, applyQuota as g, separationConflicts as h, declaredRoleNames as i, levelCondition as l, role as m, assertApprovalRelations as n, deny as o, policyLevels as p, completeGrant as r, grantList as s, allow as t, levelNames as u, normalizeWhere as v, assertSqlFunctionName as x, assertPortableTwin as y };
+export { assertSqlFunctionName as _, deny as a, withGrantSchema as c, assertApprovalRelations as d, assertApprovalVersions as f, assertSqlFunctionArg as g, assertPortableTwin as h, completeGrant as i, applyQuota as l, normalizeWhere as m, role as n, flattenGrants as o, normalizeApproval as p, allow as r, flattenPermissions as s, normalizeAssurance as t, memoryLimitStore as u, opaque as v };