permdock 0.3.0 → 0.4.0

package/dist/relation-walk-BXnlLtg2.js

@@ -0,0 +1,186 @@
+import { r as isRecord } from "./compact-CAf557ZB.js";
+import { s as ownGet } from "./thenable-QSmvt-vZ.js";
+import { n as relationId } from "./relations-CvmSpG67.js";
+//#region src/core/relation-walk.ts
+/** Whether the holder's period covers `now`. */
+function activeNow(holder, now) {
+	return (holder.startsAt === void 0 || holder.startsAt <= now) && (holder.expiresAt === void 0 || holder.expiresAt > now);
+}
+function holdsNow(holder, principalId, now) {
+	return "principal" in holder && holder.principal.id === principalId && activeNow(holder, now);
+}
+/** Where the walk starts after following `hops`, or why it cannot. */
+function followHops(condition, first, reader) {
+	const hops = condition.hops ?? [];
+	let id = first;
+	for (let index = 1; index < hops.length; index += 1) {
+		const from = hops[index - 1];
+		const hop = hops[index];
+		if (from === void 0 || hop === void 0)
+ /* v8 ignore next */
+		return;
+		const chain = reader.chain({
+			resource: from.resource,
+			id,
+			depth: 1,
+			through: hop.link
+		});
+		if (chain === "pending" || chain === "failed") return "relation-unavailable";
+		const next = chain.ancestors[0]?.id;
+		if (next === void 0) return;
+		id = next;
+	}
+	return { id };
+}
+function restrictedAbove(condition, row, reader) {
+	const above = condition.restrictedAncestors;
+	if (above === void 0) return false;
+	const parent = relationId(ownGet(row, above.parent));
+	if (parent === void 0) return false;
+	const chain = reader.chain({
+		resource: above.resource,
+		id: parent,
+		depth: above.depth - 1
+	});
+	if (chain === "pending" || chain === "failed") return "relation-unavailable";
+	if (chain.restricted === true || chain.ancestors.some((ancestor) => ancestor.restricted === true)) return;
+	const own = relationId(ownGet(row, above.id));
+	const ids = [
+		...own === void 0 ? [] : [own],
+		parent,
+		...chain.ancestors.map((ancestor) => ancestor.id)
+	];
+	if (new Set(ids).size !== ids.length || chain.truncated === true || chain.ancestors.length > above.depth - 1) return "relation-depth";
+	return false;
+}
+/** The instances a graph relation reads: the start, then ancestors until a restricted one or `depth`. */
+function relationWalk(condition, row, reader) {
+	if (!isRecord(row)) return;
+	const first = relationId(ownGet(row, condition.field));
+	if (first === void 0) return;
+	const rowRestricted = condition.restricted !== void 0 && ownGet(row, condition.restricted) === true;
+	const hopped = condition.hops !== void 0 && condition.hops.length > 0;
+	if ((condition.parent === true || hopped) && rowRestricted) return;
+	const above = restrictedAbove(condition, row, reader);
+	if (above !== false) return above;
+	const start = hopped ? followHops(condition, first, reader) : { id: first };
+	if (start === void 0 || start === "relation-unavailable") return start;
+	const id = start.id;
+	if (condition.depth === 0 || rowRestricted) return {
+		ids: [id],
+		truncated: false
+	};
+	const chain = reader.chain({
+		resource: condition.resource,
+		id,
+		depth: condition.depth
+	});
+	if (chain === "pending" || chain === "failed") return "relation-unavailable";
+	const ids = [id];
+	const stops = condition.passRestricted !== true;
+	let stopped = stops && chain.restricted === true;
+	if (!stopped) for (const ancestor of chain.ancestors.slice(0, condition.depth)) {
+		ids.push(ancestor.id);
+		if (stops && ancestor.restricted === true) {
+			stopped = true;
+			break;
+		}
+	}
+	if (new Set(ids).size !== ids.length) return "relation-depth";
+	return {
+		ids,
+		truncated: !stopped && (chain.ancestors.length > condition.depth || chain.truncated === true)
+	};
+}
+/**
+* Whether the subject holds the relation on the row's instance or an
+* ancestor within `depth`. A cycle is `relation-depth`; so is a chain that
+* goes on past `depth` with no holder below it. Any read the instance could
+* not answer is `relation-unavailable` unless a holder was found elsewhere.
+*/
+function resolveRelated(condition, row, subject, now, reader, permitted) {
+	if (condition.permission !== void 0) return resolveInherited(condition, condition.permission, row, reader, permitted);
+	const principal = subject.principal;
+	if (principal === null) return false;
+	const walk = relationWalk(condition, row, reader);
+	if (walk === void 0) return false;
+	if (walk === "relation-depth" || walk === "relation-unavailable") return walk;
+	if (condition.ids !== void 0) {
+		const held = new Set(condition.ids);
+		if (walk.ids.some((id) => held.has(id))) return true;
+		return walk.truncated ? "relation-depth" : false;
+	}
+	let unavailable = false;
+	let deep = false;
+	const explored = /* @__PURE__ */ new Map();
+	for (const id of walk.ids) {
+		const verdict = holdsRelation({
+			resource: condition.resource,
+			id,
+			relation: condition.relation
+		}, principal.id, now, reader, 16, /* @__PURE__ */ new Set(), explored);
+		if (verdict === true) return true;
+		if (verdict === "relation-unavailable") unavailable = true;
+		else if (verdict === "relation-depth") deep = true;
+	}
+	if (unavailable) return "relation-unavailable";
+	return walk.truncated || deep ? "relation-depth" : false;
+}
+function resolveInherited(condition, permission, row, reader, permitted) {
+	const walk = relationWalk(condition, row, reader);
+	if (walk === void 0) return false;
+	if (walk === "relation-depth" || walk === "relation-unavailable") return walk;
+	if (permitted === void 0) return "relation-unavailable";
+	let unknown = false;
+	for (const id of walk.ids) {
+		const verdict = permitted(condition.resource, id, permission);
+		if (verdict === true) return true;
+		if (verdict !== false && unknown === false) unknown = verdict;
+	}
+	return unknown;
+}
+function groupKey(group) {
+	return JSON.stringify([
+		group.resource,
+		group.id,
+		group.relation
+	]);
+}
+/**
+* Whether the principal holds `at.relation` on one instance, directly or
+* through a group whose members hold it. Groups of `at`'s own resource nest
+* at most `budget` deep; a group of another resource gets a fresh budget
+* (declarations rule out cycles across resources). A group met twice on one
+* path, or one past the budget, is `relation-depth`. `explored` holds the
+* budget each group was walked with across the whole walk: a group already
+* walked with as much budget adds nothing, since its verdict already reached
+* the caller, so shared sub-groups cost one walk rather than one per path.
+*/
+function holdsRelation(at, principalId, now, reader, budget, seen, explored) {
+	const key = groupKey(at);
+	const walked = explored.get(key);
+	if (walked !== void 0 && walked >= budget) return false;
+	explored.set(key, budget);
+	const holders = reader.holders(at);
+	if (holders === "pending" || holders === "failed") return "relation-unavailable";
+	if (holders.some((holder) => holdsNow(holder, principalId, now))) return true;
+	const path = new Set(seen).add(key);
+	let unavailable = false;
+	let deep = false;
+	for (const holder of holders) {
+		if (!("group" in holder) || !activeNow(holder, now)) continue;
+		const nested = holder.group.resource === at.resource;
+		if (nested && budget <= 0 || path.has(groupKey(holder.group))) {
+			deep = true;
+			continue;
+		}
+		const verdict = holdsRelation(holder.group, principalId, now, reader, nested ? budget - 1 : 16, path, explored);
+		if (verdict === true) return true;
+		if (verdict === "relation-unavailable") unavailable = true;
+		else if (verdict === "relation-depth") deep = true;
+	}
+	if (unavailable) return "relation-unavailable";
+	return deep ? "relation-depth" : false;
+}
+//#endregion
+export { resolveRelated as n, relationWalk as t };

package/dist/relations-CvmSpG67.js

@@ -0,0 +1,163 @@
+import { r as isRecord } from "./compact-CAf557ZB.js";
+import { n as isThenable } from "./thenable-QSmvt-vZ.js";
+import { t as idText } from "./ids-DC4V4CFu.js";
+import { a as expandRelation } from "./resource-relations-D1Un3pcz.js";
+//#region src/core/relations.ts
+function isInstant(value) {
+	return value === void 0 || typeof value === "number" && Number.isFinite(value);
+}
+function asChain(value) {
+	if (!isRecord(value) || !Array.isArray(value["ancestors"])) return;
+	const ancestors = [];
+	for (const item of value["ancestors"]) {
+		if (!isRecord(item) || typeof item["id"] !== "string" || item["id"] === "") return;
+		ancestors.push(item["restricted"] === true ? {
+			id: item["id"],
+			restricted: true
+		} : { id: item["id"] });
+	}
+	return {
+		ancestors,
+		...value["restricted"] === true ? { restricted: true } : {},
+		...value["truncated"] === true ? { truncated: true } : {}
+	};
+}
+function asRow(value) {
+	if (value === null || value === void 0) return { row: null };
+	return isRecord(value) ? { row: value } : void 0;
+}
+function asGroup(value) {
+	if (!isRecord(value) || typeof value["resource"] !== "string" || typeof value["id"] !== "string" || typeof value["relation"] !== "string" || value["id"] === "") return;
+	return {
+		resource: value["resource"],
+		id: value["id"],
+		relation: value["relation"]
+	};
+}
+function asHolders(value) {
+	if (!Array.isArray(value)) return;
+	const holders = [];
+	for (const item of value) {
+		if (!isRecord(item) || !isInstant(item["startsAt"]) || !isInstant(item["expiresAt"])) return;
+		const period = {
+			...item["startsAt"] === void 0 ? {} : { startsAt: item["startsAt"] },
+			...item["expiresAt"] === void 0 ? {} : { expiresAt: item["expiresAt"] }
+		};
+		if (isRecord(item["principal"]) && typeof item["principal"]["id"] === "string") {
+			holders.push({
+				principal: { id: item["principal"]["id"] },
+				...period
+			});
+			continue;
+		}
+		const group = asGroup(item["group"]);
+		if (group === void 0) return;
+		holders.push({
+			group,
+			...period
+		});
+	}
+	return holders;
+}
+function read(cache, key, call, validate) {
+	const entry = cache.get(key);
+	if (entry !== void 0) return entry.state === "ready" ? entry.value : entry.state;
+	if (call === void 0) return "failed";
+	const settle = (value) => {
+		const valid = validate(value);
+		cache.set(key, valid === void 0 ? { state: "failed" } : {
+			state: "ready",
+			value: valid
+		});
+	};
+	let result;
+	try {
+		result = call();
+	} catch {
+		cache.set(key, { state: "failed" });
+		return "failed";
+	}
+	if (isThenable(result)) {
+		const promise = Promise.resolve(result).then(settle, () => {
+			cache.set(key, { state: "failed" });
+		});
+		cache.set(key, {
+			state: "pending",
+			promise
+		});
+		return "pending";
+	}
+	settle(result);
+	const settled = cache.get(key);
+	return settled?.state === "ready" ? settled.value : "failed";
+}
+function relationReader(source, cache, resources) {
+	const concrete = (resource, id, relation) => read(cache, JSON.stringify([
+		"holders",
+		resource,
+		id,
+		relation
+	]), source === void 0 ? void 0 : () => source.related({
+		resource,
+		id,
+		relation
+	}), asHolders);
+	return {
+		available: source !== void 0,
+		row(query) {
+			const load = source?.row?.bind(source);
+			return read(cache, JSON.stringify([
+				"row",
+				query.resource,
+				query.id
+			]), load === void 0 ? void 0 : () => load({
+				resource: query.resource,
+				id: query.id
+			}), asRow);
+		},
+		chain(query) {
+			const through = query.through ?? "parent";
+			return read(cache, JSON.stringify([
+				"chain",
+				query.resource,
+				query.id,
+				query.depth,
+				through
+			]), source === void 0 ? void 0 : () => source.ancestors({
+				resource: query.resource,
+				id: query.id,
+				depth: query.depth,
+				through
+			}), asChain);
+		},
+		holders(query) {
+			const node = resources?.get(query.resource);
+			const names = node === void 0 ? [query.relation] : expandRelation(node, query.relation);
+			const out = [];
+			let unread;
+			for (const name of names) {
+				const answer = concrete(query.resource, query.id, name);
+				if (answer === "pending" || answer === "failed") {
+					unread = answer === "failed" || unread === "failed" ? "failed" : "pending";
+					continue;
+				}
+				for (const holder of answer) out.push({
+					...holder,
+					relation: name
+				});
+			}
+			return unread ?? out;
+		}
+	};
+}
+/** The loads still in flight, for an instance that awaits them before deciding. */
+function pendingRelations(cache) {
+	const out = [];
+	for (const entry of cache.values()) if (entry.state === "pending") out.push(entry.promise);
+	return out;
+}
+function relationId(value) {
+	return idText(value);
+}
+//#endregion
+export { relationId as n, relationReader as r, pendingRelations as t };

package/dist/{replay-CYyiLiwO.d.ts → replay-COpmZUfx.d.ts}

@@ -1,4 +1,4 @@
-import { g as ReplayStore } from "./types-Cq_H8N_X.js";
+import { g as ReplayStore } from "./types-C0dee0Qf.js";
 //#region src/ssf/replay.d.ts
 declare function memoryReplayStore(): ReplayStore;
 //#endregion

package/dist/request-context-BVM7aWNs.js

@@ -0,0 +1,71 @@
+import { t as assertAppData } from "./app-data-CV8pqqMi.js";
+import { n as wrapPermDock } from "./wrap-DWsU_5Bd.js";
+import { t as buildInstance } from "./build-instance-DIIV9DbC.js";
+//#region src/core/request-context.ts
+/**
+* Errors an adapter raises around one instance (a `context` hook that threw,
+* an `onDenied` that failed), fed to the instance's `on('error')` handlers and
+* replayed to later ones, as core replays its own.
+*/
+function deliver(handler, error) {
+	try {
+		handler(error);
+	} catch {}
+}
+function errorChannel(queued) {
+	const errors = [...queued];
+	const handlers = /* @__PURE__ */ new Set();
+	return {
+		report: (error) => {
+			errors.push(error);
+			for (const handler of handlers) deliver(handler, error);
+		},
+		attach: (permdock) => wrapPermDock(permdock, (inner) => ({ on: (event, handler) => {
+			const off = inner.on(event, handler);
+			if (event !== "error") return off;
+			handlers.add(handler);
+			for (const error of errors) deliver(handler, error);
+			return () => {
+				off();
+				handlers.delete(handler);
+			};
+		} }))
+	};
+}
+/**
+* `buildInstance` with an error channel: the instance's `on('error')`
+* replays `errors` raised while resolving the request, and `report` adds
+* more. Kept beside `errorChannel`, so adapters without one do not bundle it.
+*/
+async function buildReportingInstance(input) {
+	const channel = errorChannel(input.errors);
+	const { wrap } = input;
+	return {
+		...await buildInstance({
+			...input,
+			wrap: (created) => {
+				const attached = channel.attach(created);
+				return wrap === void 0 ? attached : wrap(attached);
+			}
+		}),
+		report: channel.report
+	};
+}
+/**
+* Runs an adapter's `context` hook. A throw, or a value that is not a JSON
+* object, adds no context and lands in `errors`.
+*/
+async function requestContext(hook, input, errors) {
+	if (hook === void 0) return;
+	try {
+		const value = await hook(input);
+		if (value === void 0) return;
+		assertAppData(value, "context");
+		return value;
+	} catch (error) {
+		errors.push(error);
+		return;
+	}
+}
+//#endregion
+export { requestContext as n, buildReportingInstance as t };

package/dist/request-context-C2_1lchh.d.ts

@@ -0,0 +1,5 @@
+//#region src/core/request-context.d.ts
+/** What a `context` hook returns: plain JSON, merged into `subject.context`. */
+type RequestContext = Readonly<Record<string, unknown>>;
+//#endregion
+export { RequestContext as t };

package/dist/resource-relations-D1Un3pcz.js

@@ -0,0 +1,243 @@
+import { a as assertSafeKey } from "./thenable-QSmvt-vZ.js";
+//#region src/core/resource-relations.ts
+/** The edge's group resources with their relation and id column. */
+function groupEntries(spec) {
+	const groups = spec.groups;
+	if (groups === void 0) return [];
+	return Object.entries(groups.resources).map(([resource, group]) => typeof group === "string" ? {
+		resource,
+		relation: group,
+		subject: spec.subject ?? "user_id",
+		typed: false
+	} : {
+		resource,
+		relation: group.relation,
+		subject: group.subject ?? spec.subject ?? "user_id",
+		typed: group.subject !== void 0
+	});
+}
+function restrictedStops(node, path) {
+	return node?.restricted !== void 0 && (node.restrictedStops === void 0 || node.restrictedStops.includes(path));
+}
+function restrictedFor(node, path) {
+	return restrictedStops(node, path) ? node?.restricted : void 0;
+}
+function isFieldRelation(relation) {
+	return relation !== void 0 && "field" in relation;
+}
+function isEdgeRelation(relation) {
+	return relation !== void 0 && "edge" in relation;
+}
+function isPrincipalRelation(relation) {
+	return relation !== void 0 && "principal" in relation;
+}
+function isComputedRelation(relation) {
+	return relation !== void 0 && !("field" in relation) && !("edge" in relation) && !("principal" in relation);
+}
+/**
+* The relations whose holders hold `name` on `node`: `name` itself when it
+* has a source, then everything it includes, transitively, each once.
+* `definePermissions` rejects cycles and unknown names, so this terminates.
+*/
+function expandRelation(node, name) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (current) => {
+		if (seen.has(current)) return;
+		seen.add(current);
+		const spec = node?.relations[current];
+		if (spec === void 0) return;
+		if (!isComputedRelation(spec)) out.push(current);
+		for (const included of spec.includes ?? []) visit(included);
+	};
+	visit(name);
+	return out;
+}
+/** Whether `node` names itself as its parent (nested folders, sub-teams, reporting lines). */
+function isSelfParented(node) {
+	return node?.parent !== void 0 && node.parent.resource === node.name;
+}
+const RESOURCE_NAME = /^[A-Za-z][A-Za-z0-9_-]*$/u;
+/** Level names ride claims and grant keys (`key@level`), so they stay SQL- and claim-safe. */
+const LEVEL_NAME = /^[a-z][a-z0-9_]*$/u;
+const EDGE_TABLE = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/u;
+function restrictedStopsOf(name, option, parent, links) {
+	if (option.stops === void 0) return;
+	if (!Array.isArray(option.stops) || option.stops.length === 0) throw new Error(`PermDock: resource "${name}" restricted.stops must list 'parent' or link names`);
+	const stops = /* @__PURE__ */ new Set();
+	for (const path of option.stops) {
+		if (typeof path !== "string") throw new TypeError(`PermDock: resource "${name}" restricted.stops must list 'parent' or link names`);
+		if (path === "parent" ? parent === void 0 : !Object.hasOwn(links, path)) throw new Error(`PermDock: resource "${name}" restricted.stops names '${path}', which it does not declare`);
+		stops.add(path);
+	}
+	return Object.freeze([...stops].toSorted());
+}
+function normaliseRelation(resourceName, relationName, spec) {
+	if (typeof spec === "string") {
+		assertSafeKey(spec, "relation field");
+		return { field: spec };
+	}
+	const label = `relation '${relationName}' on '${resourceName}'`;
+	const includes = normaliseIncludes(label, spec.includes);
+	const kinds = [
+		"field",
+		"edge",
+		"principal"
+	].filter((kind) => kind in spec);
+	if (kinds.length === 0 && includes !== void 0) return { includes };
+	if (kinds.length !== 1) throw new Error(`PermDock: ${label} needs exactly one of field, edge, principal or includes`);
+	const withIncludes = includes === void 0 ? {} : { includes };
+	if (isEdgeRelation(spec)) {
+		if (!EDGE_TABLE.test(spec.edge)) throw new Error(`PermDock: ${label} has an unsafe edge table '${spec.edge}'`);
+		for (const column of [
+			spec.object,
+			spec.subject,
+			spec.expiresAt
+		]) if (column !== void 0) assertSafeKey(column, "edge column");
+		return {
+			edge: spec.edge,
+			...spec.object === void 0 ? {} : { object: spec.object },
+			...spec.subject === void 0 ? {} : { subject: spec.subject },
+			...spec.expiresAt === void 0 ? {} : { expiresAt: spec.expiresAt },
+			...spec.match === void 0 ? {} : { match: normaliseMatch(label, spec.match) },
+			...spec.groups === void 0 ? {} : { groups: normaliseGroups(label, spec.groups) },
+			...withIncludes
+		};
+	}
+	if (isPrincipalRelation(spec)) {
+		assertSafeKey(spec.principal, "relation principal");
+		for (const column of [spec.period?.startsAt, spec.period?.expiresAt]) if (column !== void 0) assertSafeKey(column, "relation period");
+		return spec.period === void 0 ? {
+			principal: spec.principal,
+			...withIncludes
+		} : {
+			principal: spec.principal,
+			period: { ...spec.period },
+			...withIncludes
+		};
+	}
+	const field = spec;
+	assertSafeKey(field.field, "relation field");
+	if (field.memberOf !== void 0 && includes !== void 0) throw new Error(`PermDock: ${label} is a memberOf relation and cannot include others`);
+	return field.memberOf === void 0 ? {
+		field: field.field,
+		...withIncludes
+	} : {
+		field: field.field,
+		memberOf: field.memberOf
+	};
+}
+function normaliseIncludes(label, includes) {
+	if (includes === void 0) return;
+	if (!Array.isArray(includes) || includes.length === 0) throw new Error(`PermDock: ${label} includes must be a non-empty list of relation names`);
+	for (const name of includes) {
+		if (typeof name !== "string") throw new TypeError(`PermDock: ${label} includes a non-string name`);
+		assertSafeKey(name, "included relation");
+	}
+	return [...new Set(includes)];
+}
+function normaliseMatch(label, match) {
+	const out = {};
+	const columns = Object.keys(match);
+	if (columns.length === 0) throw new Error(`PermDock: ${label} match needs at least one column`);
+	for (const column of columns) {
+		assertSafeKey(column, "edge match column");
+		const value = match[column];
+		if (typeof value !== "string" && typeof value !== "boolean" && !(typeof value === "number" && Number.isFinite(value))) throw new Error(`PermDock: ${label} match '${column}' must be a string, a finite number or a boolean`);
+		out[column] = value;
+	}
+	return out;
+}
+function normaliseGroups(label, groups) {
+	if (groups.column !== void 0) assertSafeKey(groups.column, "edge groups column");
+	const resources = {};
+	const names = Object.keys(groups.resources);
+	if (names.length === 0) throw new Error(`PermDock: ${label} groups needs at least one resource`);
+	for (const name of names) {
+		assertSafeKey(name, "group resource");
+		const group = groups.resources[name];
+		if (typeof group === "string") {
+			assertSafeKey(group, "group relation");
+			if (groups.column === void 0) throw new Error(`PermDock: ${label} groups '${name}' needs its own subject column, or groups needs a column naming the resource`);
+			resources[name] = group;
+			continue;
+		}
+		if (group === null || typeof group !== "object") throw new TypeError(`PermDock: ${label} groups '${name}' must name a relation`);
+		const relationName = "relation" in group ? group.relation : void 0;
+		if (typeof relationName !== "string") throw new TypeError(`PermDock: ${label} groups '${name}' must name a relation`);
+		assertSafeKey(relationName, "group relation");
+		const subject = "subject" in group ? group.subject : void 0;
+		if (subject !== void 0 && typeof subject !== "string") throw new TypeError(`PermDock: ${label} groups '${name}' subject must be a column name`);
+		if (subject !== void 0) assertSafeKey(subject, "group subject column");
+		else if (groups.column === void 0) throw new Error(`PermDock: ${label} groups '${name}' needs its own subject column, or groups needs a column naming the resource`);
+		resources[name] = subject === void 0 ? { relation: relationName } : {
+			relation: relationName,
+			subject
+		};
+	}
+	if (groups.direct !== void 0 && groups.column === void 0) throw new Error(`PermDock: ${label} groups direct needs a column to compare it with`);
+	if (groups.direct !== void 0 && groups.direct in resources) throw new Error(`PermDock: ${label} groups direct '${groups.direct}' is also a group resource`);
+	return {
+		...groups.column === void 0 ? {} : { column: groups.column },
+		resources,
+		...groups.direct === void 0 ? {} : { direct: groups.direct }
+	};
+}
+/** An included relation must exist on the same resource, be tenancy-free and never include itself back. */
+function assertIncludes(node) {
+	const state = /* @__PURE__ */ new Map();
+	const visit = (name, path) => {
+		if (state.get(name) === "done") return;
+		if (state.get(name) === "visiting") throw new Error(`PermDock: relation includes on '${node.name}' form a cycle: ${[...path, name].join(" -> ")}`);
+		state.set(name, "visiting");
+		for (const included of node.relations[name]?.includes ?? []) {
+			const target = node.relations[included];
+			if (target === void 0) throw new Error(`PermDock: relation '${name}' on '${node.name}' includes '${included}', which '${node.name}' does not declare`);
+			if (isFieldRelation(target) && target.memberOf !== void 0) throw new Error(`PermDock: relation '${name}' on '${node.name}' includes the memberOf relation '${included}'; scopes are tenancy, not the object graph`);
+			visit(included, [...path, name]);
+		}
+		state.set(name, "done");
+	};
+	for (const name of Object.keys(node.relations)) visit(name, []);
+}
+function assertGroupTarget(registry, node, relationName, spec, target, targetRelation) {
+	const label = `relation '${relationName}' on '${node.name}' groups '${target}'`;
+	const targetSpec = registry.get(target)?.relations[targetRelation];
+	if (targetSpec === void 0) throw new Error(`PermDock: ${label} names '${target}#${targetRelation}', which is not declared`);
+	if (isFieldRelation(targetSpec) && targetSpec.memberOf !== void 0) throw new Error(`PermDock: ${label} names a memberOf relation; scopes are tenancy, not the object graph`);
+	if (target === node.name && (targetRelation !== relationName || spec.includes !== void 0)) throw new Error(`PermDock: ${label}: a group on its own resource must name the same relation, which includes nothing`);
+}
+/**
+* Links and group targets name declared resources and relations. Groups may
+* nest within one resource (teams in teams) through the same relation, which
+* then includes nothing, so SQL can walk it with one bounded recursive query;
+* a group cycle across resources is rejected.
+*/
+function assertGraphTargets(registry) {
+	const edges = /* @__PURE__ */ new Map();
+	for (const node of registry.values()) {
+		for (const [linkName, link] of Object.entries(node.links)) if (!registry.has(link.resource)) throw new Error(`PermDock: link '${linkName}' on '${node.name}' names the undeclared resource '${link.resource}'`);
+		for (const [relationName, spec] of Object.entries(node.relations)) {
+			if (!isEdgeRelation(spec) || spec.groups === void 0) continue;
+			for (const { resource: target, relation: targetRelation } of groupEntries(spec)) {
+				assertGroupTarget(registry, node, relationName, spec, target, targetRelation);
+				if (target !== node.name) {
+					const out = edges.get(node.name) ?? /* @__PURE__ */ new Set();
+					out.add(target);
+					edges.set(node.name, out);
+				}
+			}
+		}
+	}
+	const state = /* @__PURE__ */ new Map();
+	const visit = (name) => {
+		if (state.get(name) === "done") return;
+		if (state.get(name) === "visiting") throw new Error(`PermDock: edge groups form a cycle across resources through '${name}'`);
+		state.set(name, "visiting");
+		for (const next of edges.get(name) ?? []) visit(next);
+		state.set(name, "done");
+	};
+	for (const name of edges.keys()) visit(name);
+}
+//#endregion
+export { expandRelation as a, isEdgeRelation as c, isSelfParented as d, normaliseRelation as f, restrictedStopsOf as h, assertIncludes as i, isFieldRelation as l, restrictedStops as m, RESOURCE_NAME as n, groupEntries as o, restrictedFor as p, assertGraphTargets as r, isComputedRelation as s, LEVEL_NAME as t, isPrincipalRelation as u };