@aooth/arbac 0.1.70 → 0.1.72

package/dist/index.mjs

@@ -92,44 +92,197 @@ function definePrivilege() {
 	};
 }
 //#endregion
-//#region src/db-privileges.ts
-const TABLE_READ_ACTIONS = [
-	"query",
-	"pages",
-	"getOne",
-	"getOneComposite",
-	"meta",
-	"metaForm"
-];
-const TABLE_WRITE_ACTIONS = [
-	"insert",
-	"update",
-	"replace",
-	"remove",
-	"removeComposite"
-];
-function rulesFor(resource, actions, scope) {
-	return actions.map((action) => scope ? {
-		resource,
-		action,
-		scope
-	} : {
-		resource,
-		action
-	});
+//#region src/scope/controls.ts
+/**
+* Controls whose values can be sensibly whitelisted via `readonly string[]`.
+*
+* - `$with` — relation names; uniquery parses to `{ name, … }[]`.
+* - `$groupBy` — column names; the value already IS the array of names.
+*
+* Other controls only support boolean gates in v1; supplying a whitelist
+* for them throws from {@link unionControlsPolicy}.
+*/
+const WHITELISTABLE_CONTROLS = /* @__PURE__ */ new Set(["$with", "$groupBy"]);
+/**
+* Union per-role `controls` policies. Additive RBAC semantics: more roles =
+* broader access, mirroring how `mergeScopeFilters` and `unionProjections`
+* combine other parts of an `ArbacDbScope`.
+*
+* Resolution per control key:
+*   1. Collect each scope's value for the key (including `undefined` for
+*      silent scopes — i.e., scopes that have a `controls` map but no entry
+*      for this key).
+*   2. If any value is `undefined` or `true` → return `true` (full allow).
+*      Silence and explicit allow both mean "this role has no objection".
+*   3. Else (every scope is `false` or `string[]`):
+*      - If all are `false` → return `false` (full deny).
+*      - Else collect every `string[]` into a single sorted, de-duplicated
+*        array; return that array. (Roles that say `false` don't contribute
+*        positively; roles with whitelists do.)
+*
+* Scopes that omit the `controls` map entirely are treated as silent on
+* EVERY key — i.e., they grant unrestricted control usage. As a result, if
+* even a single scope in the input lacks a `controls` map, the result is
+* always `{}` (no restrictions).
+*
+* Whitelist support is restricted to {@link WHITELISTABLE_CONTROLS}. Passing
+* a whitelist for any other control throws — the gate cannot be enforced
+* meaningfully in v1, so the misuse is rejected loudly at scope-merge time.
+*
+* @returns merged policy keyed by control name. Keys absent from the result
+*          mean "no opinion → fully allowed". The caller should treat a
+*          missing key the same as `true`.
+*
+* @throws when a non-whitelistable control is given a `readonly string[]` gate.
+*/
+function unionControlsPolicy(scopes) {
+	if (scopes.length === 0) return {};
+	if (scopes.some((s) => !s.controls)) return {};
+	const allKeys = /* @__PURE__ */ new Set();
+	for (const s of scopes) for (const k of Object.keys(s.controls)) allKeys.add(k);
+	const result = {};
+	for (const key of allKeys) {
+		let anyAllow = false;
+		const whitelistAcc = /* @__PURE__ */ new Set();
+		let hadWhitelist = false;
+		for (const s of scopes) {
+			const v = s.controls[key];
+			if (v === void 0 || v === true) {
+				anyAllow = true;
+				break;
+			}
+			if (v === false) continue;
+			if (Array.isArray(v)) {
+				if (!WHITELISTABLE_CONTROLS.has(key)) throw new Error(`unionControlsPolicy: control "${key}" only supports boolean gates; whitelist arrays not yet implemented`);
+				hadWhitelist = true;
+				for (const item of v) whitelistAcc.add(item);
+				continue;
+			}
+			throw new Error(`unionControlsPolicy: invalid gate value ${String(v)} for control "${key}" (must be boolean or string[])`);
+		}
+		if (anyAllow) continue;
+		if (hadWhitelist) {
+			result[key] = [...whitelistAcc].toSorted();
+			continue;
+		}
+		result[key] = false;
+	}
+	return result;
 }
-/** Read-side actions on an `AsDbController` table: `query`, `pages`, `getOne`, `getOneComposite`, `meta`, `metaForm`. */
-function allowTableRead(resource, opts) {
-	return () => rulesFor(resource, TABLE_READ_ACTIONS, opts?.scope);
+/**
+* Conjoin two ALREADY-UNIONED controls policies (each the output of
+* {@link unionControlsPolicy} for one authority pass) under DENY-WINS
+* intersection — a control is permitted only if BOTH passes permit it. This is
+* the credential-attenuation combiner; polarity is the **opposite** of
+* {@link unionControlsPolicy} (which is additive / silence-wins).
+*
+* Per control key (absent ≡ allowed, matching {@link unionControlsPolicy}):
+*   - denied (`false`) on EITHER side → `false`.
+*   - allowed on one side → the OTHER side's gate (`allow ∧ X = X`).
+*   - whitelist ∧ whitelist → the INTERSECTION of the two arrays (only values
+*     allowed by both; may be empty = nothing permitted).
+*
+* @returns merged policy; keys absent from the result mean "allowed" (callers
+*          treat a missing key as `true`), matching {@link unionControlsPolicy}.
+*/
+function intersectControlsPolicy(a, b) {
+	const result = {};
+	const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+	for (const key of keys) {
+		const av = key in a ? a[key] : true;
+		const bv = key in b ? b[key] : true;
+		if (av === false || bv === false) {
+			result[key] = false;
+			continue;
+		}
+		if (av === true) {
+			if (Array.isArray(bv)) result[key] = [...bv];
+			continue;
+		}
+		if (bv === true) {
+			if (Array.isArray(av)) result[key] = [...av];
+			continue;
+		}
+		const bset = new Set(bv);
+		result[key] = [...new Set(av)].filter((v) => bset.has(v)).toSorted();
+	}
+	return result;
 }
-/** All actions on an `AsDbController` table: read + `insert`, `update`, `replace`, `remove`, `removeComposite`. */
-function allowTableWrite(resource, opts) {
-	return () => rulesFor(resource, [...TABLE_READ_ACTIONS, ...TABLE_WRITE_ACTIONS], opts?.scope);
+//#endregion
+//#region src/scope/filter.ts
+/**
+* A filter that matches no rows (`{ $or: [] }`) — what a denied read, or a
+* conjunction whose field intersection is empty, filters by. Shared; never
+* mutate it.
+*/
+const DENY_FILTER = { $or: [] };
+/**
+* Merge multiple scope filters into a single filter using `$or` semantics.
+*
+* In RBAC, if multiple roles grant access with different filters,
+* the user can see records matching ANY of them — hence `$or`.
+*
+* Behaviour:
+* - Empty input → `undefined` (no filter)
+* - Any empty filter → `undefined` (one role grants unrestricted access)
+* - Single filter → returned as-is
+* - All filters single-keyed on the same primitive field → `{ field: { $in: [...] } }`
+* - Otherwise → `{ $or: [...] }`
+*
+* @returns the merged filter, or `undefined` for unrestricted access
+*/
+function mergeScopeFilters(scopes) {
+	if (scopes.length === 0) return void 0;
+	if (scopes.some((s) => Object.keys(s).length === 0)) return void 0;
+	if (scopes.length === 1) return scopes[0];
+	if (canOptimizeToIn(scopes)) {
+		const key = Object.keys(scopes[0])[0];
+		const values = scopes.map((s) => s[key]);
+		return { [key]: { $in: values } };
+	}
+	return { $or: scopes };
 }
-/** One or more declarative actions on the same table, sharing a scope. */
-function allowTableAction(resource, name, opts) {
-	const actions = typeof name === "string" ? [name] : name;
-	return () => rulesFor(resource, actions, opts?.scope);
+/**
+* Conjoin two filters under `$and` semantics — a row survives only if BOTH
+* sides admit it. The restrict-only combiner, used wherever two independent
+* constraints must both hold:
+*
+* - **credential attenuation** — assigned authority ∧ presented authority, so
+*   a scoped token can only clip what the role grants (see
+*   `conjoinArbacDbScopes`);
+* - **scope ∧ request** — the caller's scope union ∧ the user-supplied query
+*   filter, on both the top-level read and the per-relation `$with` overlay.
+*
+* Either side may be a {@link mergeScopeFilters} output or a raw filter.
+*
+* Polarity is the **opposite** of {@link mergeScopeFilters}: an empty `{}` /
+* `undefined` filter is the universe and acts as the **identity** here
+* (dropped from the `$and`, contributing NO constraint) — never the absorbing
+* "unrestricted wins". Never object-spreads the two filters: a key present on
+* both sides would be overwritten rather than intersected, silently widening
+* access (a caller scoped to `tenantId: 'a'` asking for `'b'` would get `'b'`).
+*
+* @returns the conjoined filter, or `undefined` when BOTH sides are unrestricted.
+*/
+function conjoinScopeFilters(a, b) {
+	const aEmpty = !a || Object.keys(a).length === 0;
+	const bEmpty = !b || Object.keys(b).length === 0;
+	if (aEmpty && bEmpty) return void 0;
+	if (aEmpty) return b;
+	if (bEmpty) return a;
+	return { $and: [a, b] };
+}
+function canOptimizeToIn(scopes) {
+	const firstKeys = Object.keys(scopes[0]);
+	if (firstKeys.length !== 1) return false;
+	const key = firstKeys[0];
+	for (const scope of scopes) {
+		const keys = Object.keys(scope);
+		if (keys.length !== 1 || keys[0] !== key) return false;
+		const value = scope[key];
+		if (value !== null && typeof value === "object") return false;
+	}
+	return true;
 }
 //#endregion
 //#region src/scope/projection.ts
@@ -329,197 +482,549 @@ function restrictProjection(desired, accessControl, childrenOf) {
 	return intersectProjections(desired, accessControl, childrenOf) ?? { ...accessControl };
 }
 //#endregion
-//#region src/scope/filter.ts
+//#region src/scope/db-scope.ts
 /**
-* A filter that matches no rows (`{ $or: [] }`) — what a denied read, or a
-* conjunction whose field intersection is empty, filters by. Shared; never
-* mutate it.
+* The built-in {@link TDbScope} keys — the facets the scope algebra itself
+* combines. Any other key is a custom (declaration-merged) scope field, which
+* {@link conjoinScopes} combines only through a registered
+* {@link TScopeFieldRule}.
+*
+* @since 0.1.72
 */
-const DENY_FILTER = { $or: [] };
+const DB_SCOPE_KEYS = Object.freeze([
+	"filter",
+	"check",
+	"projection",
+	"controls",
+	"allowedFields",
+	"set",
+	"nestedWrites",
+	"checkRefs",
+	"with"
+]);
+const BUILT_IN_KEYS = new Set(DB_SCOPE_KEYS);
 /**
-* Merge multiple scope filters into a single filter using `$or` semantics.
-*
-* In RBAC, if multiple roles grant access with different filters,
-* the user can see records matching ANY of them — hence `$or`.
+* Thrown by {@link conjoinScopes} for a custom scope field without a
+* conjunction rule — a server CONFIGURATION error (never a client error):
+* the conjunction fails closed instead of dropping the field.
 *
-* Behaviour:
-* - Empty input → `undefined` (no filter)
-* - Any empty filter → `undefined` (one role grants unrestricted access)
-* - Single filter → returned as-is
-* - All filters single-keyed on the same primitive field → `{ field: { $in: [...] } }`
-* - Otherwise → `{ $or: [...] }`
-*
-* @returns the merged filter, or `undefined` for unrestricted access
+* @since 0.1.72
 */
-function mergeScopeFilters(scopes) {
-	if (scopes.length === 0) return void 0;
-	if (scopes.some((s) => Object.keys(s).length === 0)) return void 0;
-	if (scopes.length === 1) return scopes[0];
-	if (canOptimizeToIn(scopes)) {
-		const key = Object.keys(scopes[0])[0];
-		const values = scopes.map((s) => s[key]);
-		return { [key]: { $in: values } };
+var ScopeFieldConfigError = class extends Error {
+	field;
+	name = "ScopeFieldConfigError";
+	constructor(field, message) {
+		super(message);
+		this.field = field;
 	}
-	return { $or: scopes };
-}
-/**
-* Conjoin two filters under `$and` semantics — a row survives only if BOTH
-* sides admit it. The restrict-only combiner, used wherever two independent
-* constraints must both hold:
-*
-* - **credential attenuation** — assigned authority ∧ presented authority, so
-*   a scoped token can only clip what the role grants (see
-*   `conjoinArbacDbScopes`);
-* - **scope ∧ request** — the caller's scope union ∧ the user-supplied query
-*   filter, on both the top-level read and the per-relation `$with` overlay.
-*
-* Either side may be a {@link mergeScopeFilters} output or a raw filter.
-*
-* Polarity is the **opposite** of {@link mergeScopeFilters}: an empty `{}` /
-* `undefined` filter is the universe and acts as the **identity** here
-* (dropped from the `$and`, contributing NO constraint) — never the absorbing
-* "unrestricted wins". Never object-spreads the two filters: a key present on
-* both sides would be overwritten rather than intersected, silently widening
-* access (a caller scoped to `tenantId: 'a'` asking for `'b'` would get `'b'`).
+};
+const NONE = /* @__PURE__ */ new Set();
+/** Lazily computed facets of one scopes array. */
+var EffectiveDbScope = class {
+	scopes;
+	memo = /* @__PURE__ */ new Map();
+	withMemo;
+	constructor(scopes) {
+		this.scopes = scopes;
+	}
+	lazy(name, compute) {
+		if (this.memo.has(name)) return this.memo.get(name);
+		const value = compute();
+		this.memo.set(name, value);
+		return value;
+	}
+	get filter() {
+		return this.lazy("filter", () => mergeScopeFilters(this.scopes.map((s) => s.filter ?? {})));
+	}
+	get check() {
+		return this.lazy("check", () => this.hasExplicitCheck ? mergeScopeFilters(this.scopes.map((s) => s.check ?? s.filter ?? {})) : this.filter);
+	}
+	get hasExplicitCheck() {
+		return this.lazy("hasCheck", () => this.scopes.some((s) => s.check !== void 0));
+	}
+	get projection() {
+		return this.lazy("projection", () => unionProjections(...this.scopes.map((s) => s.projection ?? {})));
+	}
+	get controls() {
+		return this.lazy("controls", () => unionControlsPolicy(this.scopes));
+	}
+	get allowedFields() {
+		return this.lazy("allowedFields", () => {
+			let out;
+			for (const s of this.scopes) {
+				if (!Array.isArray(s.allowedFields)) continue;
+				out ??= /* @__PURE__ */ new Set();
+				for (const f of s.allowedFields) out.add(f);
+			}
+			return out;
+		});
+	}
+	get set() {
+		return this.lazy("set", () => {
+			let out;
+			for (const s of this.scopes) if (s.set) Object.assign(out ??= {}, s.set);
+			return out;
+		});
+	}
+	get nestedWrites() {
+		return this.lazy("nestedWrites", () => {
+			const out = new Set(this.scopes.flatMap((s) => s.nestedWrites ?? []));
+			return out.size > 0 ? out : NONE;
+		});
+	}
+	get checkRefs() {
+		return this.lazy("checkRefs", () => intersectEnabled(this.scopes.map((s) => s.checkRefs === true ? true : new Set(s.checkRefs ?? []))));
+	}
+	get withNames() {
+		return this.lazy("withNames", () => {
+			const out = /* @__PURE__ */ new Set();
+			for (const s of this.scopes) if (s.with) for (const name of Object.keys(s.with)) out.add(name);
+			return out.size > 0 ? out : NONE;
+		});
+	}
+	withScopes(name) {
+		this.withMemo ??= /* @__PURE__ */ new Map();
+		let list = this.withMemo.get(name);
+		if (!list) {
+			list = [];
+			for (const s of this.scopes) {
+				const sub = s.with?.[name];
+				if (sub) list.push(sub);
+			}
+			this.withMemo.set(name, list);
+		}
+		return list;
+	}
+};
+const effectiveCache = /* @__PURE__ */ new WeakMap();
+/**
+* The {@link TEffectiveDbScope} of `scopes`, memoized per scopes ARRAY (an
+* identity-stable per-request list reuses every computed facet).
 *
-* @returns the conjoined filter, or `undefined` when BOTH sides are unrestricted.
+* @since 0.1.72
 */
-function conjoinScopeFilters(a, b) {
-	const aEmpty = !a || Object.keys(a).length === 0;
-	const bEmpty = !b || Object.keys(b).length === 0;
-	if (aEmpty && bEmpty) return void 0;
-	if (aEmpty) return b;
-	if (bEmpty) return a;
-	return { $and: [a, b] };
-}
-function canOptimizeToIn(scopes) {
-	const firstKeys = Object.keys(scopes[0]);
-	if (firstKeys.length !== 1) return false;
-	const key = firstKeys[0];
-	for (const scope of scopes) {
-		const keys = Object.keys(scope);
-		if (keys.length !== 1 || keys[0] !== key) return false;
-		const value = scope[key];
-		if (value !== null && typeof value === "object") return false;
+function effectiveScope(scopes) {
+	let eff = effectiveCache.get(scopes);
+	if (!eff) {
+		eff = new EffectiveDbScope(scopes);
+		effectiveCache.set(scopes, eff);
 	}
-	return true;
+	return eff;
 }
-//#endregion
-//#region src/scope/controls.ts
 /**
-* Controls whose values can be sensibly whitelisted via `readonly string[]`.
+* Intersection of enforcement: an entry is enforced only when EVERY input
+* enables it (`true` enables all). No input → nothing enforced.
 *
-* - `$with` — relation names; uniquery parses to `{ name, … }[]`.
-* - `$groupBy` — column names; the value already IS the array of names.
+* @since 0.1.72
+*/
+function intersectEnabled(inputs) {
+	let out;
+	for (const input of inputs) {
+		if (input === true) {
+			out ??= true;
+			continue;
+		}
+		out = out === void 0 || out === true ? new Set(input) : intersect(out, input);
+		if (out.size === 0) return out;
+	}
+	return out ?? /* @__PURE__ */ new Set();
+}
+function intersect(a, b) {
+	const out = /* @__PURE__ */ new Set();
+	for (const k of a) if (b.has(k)) out.add(k);
+	return out;
+}
+/**
+* The unified empty-scope rule for an evaluation outcome: denied → `undefined`;
+* allowed with `scopes` absent (a scope-agnostic evaluator) → `[{}]`
+* (unrestricted); a scope predicate that returned nothing contributes nothing
+* (fail closed for that rule); allowed with no scope left → `undefined` (deny).
 *
-* Other controls only support boolean gates in v1; supplying a whitelist
-* for them throws from {@link unionControlsPolicy}.
+* @since 0.1.72
 */
-const WHITELISTABLE_CONTROLS = /* @__PURE__ */ new Set(["$with", "$groupBy"]);
+function normalizeScopes(outcome) {
+	if (!outcome.allowed) return void 0;
+	const { scopes } = outcome;
+	if (scopes === void 0) return [{}];
+	const list = scopes.every((s) => s != null) ? scopes : scopes.filter((s) => s != null);
+	return list.length > 0 ? list : void 0;
+}
 /**
-* Union per-role `controls` policies. Additive RBAC semantics: more roles =
-* broader access, mirroring how `mergeScopeFilters` and `unionProjections`
-* combine other parts of an `ArbacDbScope`.
+* Several evaluations served as ONE surface (e.g. the handlers of one crud
+* op): each normalized with {@link normalizeScopes}, the allowed ones'
+* scopes concatenated — `undefined` when none allows.
 *
-* Resolution per control key:
-*   1. Collect each scope's value for the key (including `undefined` for
-*      silent scopes — i.e., scopes that have a `controls` map but no entry
-*      for this key).
-*   2. If any value is `undefined` or `true` → return `true` (full allow).
-*      Silence and explicit allow both mean "this role has no objection".
-*   3. Else (every scope is `false` or `string[]`):
-*      - If all are `false` → return `false` (full deny).
-*      - Else collect every `string[]` into a single sorted, de-duplicated
-*        array; return that array. (Roles that say `false` don't contribute
-*        positively; roles with whitelists do.)
+* @since 0.1.72
+*/
+function unionOutcomes(outcomes) {
+	let out;
+	for (const o of outcomes) {
+		const scopes = normalizeScopes(o);
+		if (scopes) (out ??= []).push(...scopes);
+	}
+	return out;
+}
+/**
+* Conjoin two row policies (`$and`, restrict-only): `filter = a.filter ∧
+* b.filter`; the effective check `(a.check ?? a.filter) ∧ (b.check ??
+* b.filter)`. `check` is set only when it differs from the conjoined
+* `filter` (which an absent `check` defaults to) — `{}` when it is
+* unrestricted while the filter is not.
 *
-* Scopes that omit the `controls` map entirely are treated as silent on
-* EVERY key — i.e., they grant unrestricted control usage. As a result, if
-* even a single scope in the input lacks a `controls` map, the result is
-* always `{}` (no restrictions).
+* @since 0.1.72
+*/
+function conjoinRowPolicies(a, b) {
+	const out = {};
+	const filter = conjoinScopeFilters(a.filter, b.filter);
+	if (filter && Object.keys(filter).length > 0) out.filter = filter;
+	if (a.check === void 0 && b.check === void 0) return out;
+	const check = conjoinScopeFilters(a.check ?? a.filter, b.check ?? b.filter);
+	if (stableKey(check ?? {}) !== stableKey(out.filter ?? {})) out.check = check ?? {};
+	return out;
+}
+/**
+* Conjoin two scope lists (credential attenuation: the user's ceiling ∧ the
+* credential's narrowed view) into ONE composite scope. Each side is first
+* unioned ({@link effectiveScope}), then the two results are CONJOINED facet
+* by facet — never with the additive union helpers, which would widen:
 *
-* Whitelist support is restricted to {@link WHITELISTABLE_CONTROLS}. Passing
-* a whitelist for any other control throws — the gate cannot be enforced
-* meaningfully in v1, so the misuse is rejected loudly at scope-merge time.
+* - `filter` / `check` — {@link conjoinRowPolicies};
+* - `projection` — {@link intersectProjections} (no common field → the
+*   first side's projection plus a match-nothing filter, never `{}`);
+* - `controls` — {@link intersectControlsPolicy} (deny wins);
+* - `allowedFields` — intersection (a side without a whitelist is unrestricted);
+* - `nestedWrites` — intersection (a side without the key allows none);
+* - `set` — combined, the FIRST side winning a key conflict;
+* - `checkRefs` — enforced when EITHER side enforces it;
+* - `with` — per relation, recursively; a relation declared by ONE side only
+*   is marked {@link INHERITED_CONJUNCTION} (the silent side's inherited
+*   grant on the related table must be conjoined at resolution time);
+* - a custom field — its `opts.fields` rule; none registered → throws
+*   (fail closed: never silently dropped).
 *
-* @returns merged policy keyed by control name. Keys absent from the result
-*          mean "no opinion → fully allowed". The caller should treat a
-*          missing key the same as `true`.
+* @since 0.1.72
+*/
+function conjoinScopes(a, b, opts = {}) {
+	const custom = customFieldRules(a, b, opts.fields);
+	const ea = effectiveScope(a);
+	const eb = effectiveScope(b);
+	const intersected = intersectProjections(ea.projection, eb.projection, opts.childrenOf);
+	const projection = intersected ?? ea.projection;
+	const deny = (f) => intersected ? f : conjoinScopeFilters(f, DENY_FILTER);
+	const rows = conjoinRowPolicies({
+		filter: ea.filter,
+		check: ea.hasExplicitCheck ? ea.check ?? {} : void 0
+	}, {
+		filter: deny(eb.filter),
+		check: eb.hasExplicitCheck ? deny(eb.check) ?? {} : void 0
+	});
+	const controls = intersectControlsPolicy(ea.controls, eb.controls);
+	const allowedFields = intersectAllowedFields(ea.allowedFields, eb.allowedFields);
+	const nestedWrites = [...ea.nestedWrites].filter((rel) => eb.nestedWrites.has(rel)).toSorted();
+	const set = ea.set || eb.set ? {
+		...eb.set,
+		...ea.set
+	} : void 0;
+	const checkRefs = (opts.checkRefs ?? unionRefNames)(a, b);
+	const withMap = conjoinWith(ea, eb, opts.fields);
+	const s = { ...rows };
+	if (Object.keys(projection).length > 0) s.projection = projection;
+	if (Object.keys(controls).length > 0) s.controls = controls;
+	if (allowedFields) s.allowedFields = allowedFields;
+	if (nestedWrites.length > 0) s.nestedWrites = nestedWrites;
+	if (checkRefs) s.checkRefs = checkRefs;
+	if (set) s.set = set;
+	if (withMap) s.with = withMap;
+	for (const [key, rule] of custom) {
+		const value = rule.conjoin(a, b);
+		if (value !== void 0) s[key] = value;
+	}
+	return s;
+}
+/**
+* The rules of the custom fields some scope of `a` / `b` carries (a key
+* holding `undefined` does not count). Throws on a custom field without a
+* rule — dropping it would silently widen (fail closed).
+*/
+function customFieldRules(a, b, fields) {
+	const out = /* @__PURE__ */ new Map();
+	for (const scope of [...a, ...b]) for (const key of Object.keys(scope)) {
+		if (BUILT_IN_KEYS.has(key) || out.has(key)) continue;
+		if (scope[key] === void 0) continue;
+		const rule = fields && Object.hasOwn(fields, key) ? fields[key] : void 0;
+		if (!rule) throw new ScopeFieldConfigError(key, `Scope field "${key}" has no conjunction rule: a credential attenuation cannot combine it, and dropping it would widen access. Register one with MoostArbac.registerScopeFields({ ${key}: { conjoin: (a, b) => ... } }) (or the \`fields\` option of conjoinScopes).`);
+		out.set(key, rule);
+	}
+	return out;
+}
+function intersectAllowedFields(a, b) {
+	if (a === void 0) return b && [...b];
+	if (b === void 0) return [...a];
+	return [...a].filter((f) => b.has(f)).toSorted();
+}
+/** Schema-less `checkRefs` conjunction: what either side enforces. */
+function unionRefNames(a, b) {
+	const ra = effectiveScope(a).checkRefs;
+	const rb = effectiveScope(b).checkRefs;
+	if (ra === true || rb === true) return true;
+	const names = /* @__PURE__ */ new Set([...ra, ...rb]);
+	return names.size > 0 ? [...names].toSorted() : void 0;
+}
+/** Per rule registry: its row rules and the fold memo (scope → folded scope). */
+const foldStates = /* @__PURE__ */ new WeakMap();
+const NO_FIELDS = Object.freeze({});
+/**
+* Fold every custom field's {@link TScopeFieldRule.rowFilter} into its
+* scope's `filter` (`filter ∧ rowFilter(value, scope)`), recursively into
+* `with` sub-scopes. Apply it per evaluated scope list — before any union or
+* conjunction — so every row path sees the restriction. The custom value
+* stays on the scope. Scopes are never mutated: a changed scope is a copy.
+* Memoized per rule registry and scope object (process-wide), and
+* idempotent (a folded scope folds to itself); without row rules (and no
+* `onUnknownField`) the input list is returned as is.
 *
-* @throws when a non-whitelistable control is given a `readonly string[]` gate.
+* @since 0.1.72
 */
-function unionControlsPolicy(scopes) {
-	if (scopes.length === 0) return {};
-	if (scopes.some((s) => !s.controls)) return {};
-	const allKeys = /* @__PURE__ */ new Set();
-	for (const s of scopes) for (const k of Object.keys(s.controls)) allKeys.add(k);
-	const result = {};
-	for (const key of allKeys) {
-		let anyAllow = false;
-		const whitelistAcc = /* @__PURE__ */ new Set();
-		let hadWhitelist = false;
-		for (const s of scopes) {
-			const v = s.controls[key];
-			if (v === void 0 || v === true) {
-				anyAllow = true;
-				break;
-			}
-			if (v === false) continue;
-			if (Array.isArray(v)) {
-				if (!WHITELISTABLE_CONTROLS.has(key)) throw new Error(`unionControlsPolicy: control "${key}" only supports boolean gates; whitelist arrays not yet implemented`);
-				hadWhitelist = true;
-				for (const item of v) whitelistAcc.add(item);
-				continue;
-			}
-			throw new Error(`unionControlsPolicy: invalid gate value ${String(v)} for control "${key}" (must be boolean or string[])`);
+function applyScopeFieldFilters(scopes, fields, opts = {}) {
+	const registry = fields ?? NO_FIELDS;
+	let state = foldStates.get(registry);
+	if (!state) {
+		const rules = [];
+		for (const [key, rule] of Object.entries(registry)) if (rule.rowFilter) rules.push([key, rule.rowFilter.bind(rule)]);
+		state = {
+			rules,
+			memo: /* @__PURE__ */ new WeakMap()
+		};
+		foldStates.set(registry, state);
+	}
+	const { rules, memo } = state;
+	const { onUnknownField } = opts;
+	if (rules.length === 0 && !onUnknownField) return scopes;
+	const fold = (scope) => {
+		if (scope === null || typeof scope !== "object") return scope;
+		const hit = memo.get(scope);
+		if (hit) return hit;
+		const record = scope;
+		if (onUnknownField) for (const key of Object.keys(scope)) {
+			if (BUILT_IN_KEYS.has(key) || Object.hasOwn(registry, key)) continue;
+			if (record[key] !== void 0) onUnknownField(key);
 		}
-		if (anyAllow) continue;
-		if (hadWhitelist) {
-			result[key] = [...whitelistAcc].toSorted();
-			continue;
+		let filter = scope.filter;
+		for (const [key, rowFilter] of rules) {
+			const value = record[key];
+			if (value !== void 0) filter = conjoinScopeFilters(filter, rowFilter(value, scope));
 		}
-		result[key] = false;
+		let out = filter === scope.filter ? scope : {
+			...scope,
+			filter
+		};
+		if (scope.with) {
+			const subs = scope.with;
+			let next;
+			for (const [rel, sub] of Object.entries(subs)) {
+				const folded = fold(sub);
+				if (folded !== sub) (next ??= { ...subs })[rel] = folded;
+			}
+			if (next) out = {
+				...out,
+				with: next
+			};
+		}
+		memo.set(scope, out);
+		memo.set(out, out);
+		return out;
+	};
+	const out = scopes.map(fold);
+	return out.every((s, i) => s === scopes[i]) ? scopes : out;
+}
+/**
+* Marks a `with.<rel>` sub-scope {@link conjoinScopes} built from ONE side's
+* declaration. The other side is silent on the relation, so ITS policy for
+* the joined rows is its inherited grant on the related table — unknown
+* here. A resolver must conjoin the marked sub-scope with the caller's own
+* grant on the related table (never apply it alone as parent authority);
+* unresolved, the relation is hidden. See {@link needsInheritedConjunction}.
+*
+* @since 0.1.72
+*/
+const INHERITED_CONJUNCTION = Symbol.for("aooth.arbac.inheritedConjunction");
+/** A `with` sub-scope marked {@link INHERITED_CONJUNCTION}. @since 0.1.72 */
+function needsInheritedConjunction(scope) {
+	return scope[INHERITED_CONJUNCTION] === true;
+}
+function conjoinWith(ea, eb, fields) {
+	const names = /* @__PURE__ */ new Set([...ea.withNames, ...eb.withNames]);
+	if (names.size === 0) return void 0;
+	const out = {};
+	for (const rel of names) {
+		const a = ea.withScopes(rel);
+		const b = eb.withScopes(rel);
+		const sub = conjoinScopes(a, b, { fields });
+		if (a.length === 0 || b.length === 0 || [...a, ...b].some(needsInheritedConjunction)) sub[INHERITED_CONJUNCTION] = true;
+		out[rel] = sub;
 	}
-	return result;
+	return out;
 }
 /**
-* Conjoin two ALREADY-UNIONED controls policies (each the output of
-* {@link unionControlsPolicy} for one authority pass) under DENY-WINS
-* intersection — a control is permitted only if BOTH passes permit it. This is
-* the credential-attenuation combiner; polarity is the **opposite** of
-* {@link unionControlsPolicy} (which is additive / silence-wins).
+* A stable string key for a JSON-like value (bigint-safe) — for
+* de-duplicating filters / tuples and comparing them structurally.
 *
-* Per control key (absent ≡ allowed, matching {@link unionControlsPolicy}):
-*   - denied (`false`) on EITHER side → `false`.
-*   - allowed on one side → the OTHER side's gate (`allow ∧ X = X`).
-*   - whitelist ∧ whitelist → the INTERSECTION of the two arrays (only values
-*     allowed by both; may be empty = nothing permitted).
+* @since 0.1.72
+*/
+function stableKey(value) {
+	return JSON.stringify(value, (_k, v) => typeof v === "bigint" ? `${v}n` : v);
+}
+//#endregion
+//#region src/db-privileges.ts
+/**
+* Read-side handler actions of an `AsDbController` table: `query`, `pages`,
+* `getOne`, `getOneComposite`, `geo`, `meta`, `metaForm`.
+*/
+const TABLE_READ_ACTIONS = [
+	"query",
+	"pages",
+	"getOne",
+	"getOneComposite",
+	"geo",
+	"meta",
+	"metaForm"
+];
+/** Write-side handler actions of an `AsDbController` table. */
+const TABLE_WRITE_ACTIONS = [
+	"insert",
+	"update",
+	"replace",
+	"remove",
+	"removeComposite"
+];
+/** The `/meta` + `/meta/form/:name` handler actions (a subset of {@link TABLE_READ_ACTIONS}). */
+const TABLE_META_ACTIONS = ["meta", "metaForm"];
+/**
+* Operation → handler actions. `meta` is the form-metadata subset of `read`,
+* for write-only principals that still render forms from `/meta`.
+*/
+const TABLE_OP_ACTIONS = {
+	read: TABLE_READ_ACTIONS,
+	meta: TABLE_META_ACTIONS,
+	insert: ["insert"],
+	update: ["update"],
+	replace: ["replace"],
+	remove: ["remove", "removeComposite"]
+};
+const ALL_WRITE_OPS = [
+	"insert",
+	"update",
+	"replace",
+	"remove"
+];
+function rulesFor(resource, actions, scope) {
+	return actions.map((action) => scope ? {
+		resource,
+		action,
+		scope
+	} : {
+		resource,
+		action
+	});
+}
+/** Handler actions of `ops`, in op order, without duplicates. Throws on an unknown op. */
+function actionsForOps(ops) {
+	const out = /* @__PURE__ */ new Set();
+	for (const op of ops) {
+		const actions = TABLE_OP_ACTIONS[op];
+		if (!actions) throw new Error(`Unknown table operation "${op}"`);
+		for (const a of actions) out.add(a);
+	}
+	return [...out];
+}
+/** Read-side actions on an `AsDbController` table — see {@link TABLE_READ_ACTIONS}. */
+function allowTableRead(resource, opts) {
+	return () => rulesFor(resource, TABLE_READ_ACTIONS, opts?.scope);
+}
+/** All actions on an `AsDbController` table: read + `insert`, `update`, `replace`, `remove`, `removeComposite`. */
+function allowTableWrite(resource, opts) {
+	return () => rulesFor(resource, [...TABLE_READ_ACTIONS, ...TABLE_WRITE_ACTIONS], opts?.scope);
+}
+/**
+* Selected operations on an `AsDbController` table, sharing a scope — e.g. an
+* insert-only form principal: `allowTableOps("leads", ["insert", "meta"])`.
 *
-* @returns merged policy; keys absent from the result mean "allowed" (callers
-*          treat a missing key as `true`), matching {@link unionControlsPolicy}.
+* - `read` → `query`, `pages`, `getOne`, `getOneComposite`, `geo`, `meta`, `metaForm`
+* - `meta` → `meta`, `metaForm` (forms for principals without `read`)
+* - `remove` → `remove`, `removeComposite`
+* - `insert` / `update` / `replace` → the same-named action
+*
+* Throws on an unknown op name.
 */
-function intersectControlsPolicy(a, b) {
-	const result = {};
-	const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
-	for (const key of keys) {
-		const av = key in a ? a[key] : true;
-		const bv = key in b ? b[key] : true;
-		if (av === false || bv === false) {
-			result[key] = false;
-			continue;
-		}
-		if (av === true) {
-			if (Array.isArray(bv)) result[key] = [...bv];
-			continue;
-		}
-		if (bv === true) {
-			if (Array.isArray(av)) result[key] = [...av];
-			continue;
-		}
-		const bset = new Set(bv);
-		result[key] = [...new Set(av)].filter((v) => bset.has(v)).toSorted();
+function allowTableOps(resource, ops, opts) {
+	const actions = actionsForOps(ops);
+	return () => rulesFor(resource, actions, opts?.scope);
+}
+/** One or more declarative actions on the same table, sharing a scope. */
+function allowTableAction(resource, name, opts) {
+	const actions = typeof name === "string" ? [name] : name;
+	return () => rulesFor(resource, actions, opts?.scope);
+}
+/**
+* Merge a part scope over the shared one: the row policy is CONJOINED
+* ({@link conjoinRowPolicies} — a part can only narrow the shared rows, and
+* the effective check is `(shared.check ?? shared.filter) ∧ (part.check ??
+* part.filter)`); every other key (projection, `allowedFields`, `set`,
+* `with`, …) comes from the part when it sets it, else from the shared scope.
+*/
+function mergePartScope(shared, part) {
+	const merged = {
+		...shared,
+		...part
+	};
+	delete merged.filter;
+	delete merged.check;
+	return Object.assign(merged, conjoinRowPolicies(shared, part));
+}
+function composeScope(shared, part) {
+	if (!part) return shared;
+	if (!shared) return part;
+	return (attrs, userId) => mergePartScope(shared(attrs, userId), part(attrs, userId));
+}
+/**
+* One table policy → consistent rules for every endpoint of an
+* `AsDbController` table. The shared `scope` (row filter + projection +
+* controls + `with` + `check` …) applies to every part; a part's own `scope`
+* merges over it — `filter` / `check` conjoined (`$and`), other keys from the
+* part. An action granted by an earlier part (`read` → `write` → `actions`)
+* is not repeated by a later one. Throws on an unknown write op.
+*
+* @example
+* ```ts
+* defineTableAccess<Attrs, ArbacDbScope<typeof Task>>("tasks", {
+*   scope: (a) => ({ filter: { tenantId: a.tenantId }, projection: { secret: 0 } }),
+*   read: true,
+*   write: { ops: ["insert", "update"], scope: () => ({ allowedFields: ["title", "status"] }) },
+*   actions: ["markDone"],
+* });
+* ```
+*/
+function defineTableAccess(resource, def) {
+	const { read, write, actions } = def;
+	const writePart = typeof write === "object" && !isList(write) ? write : void 0;
+	const actionsPart = actions && !isList(actions) ? actions : void 0;
+	const parts = [];
+	if (read) parts.push([TABLE_READ_ACTIONS, typeof read === "object" ? read.scope : void 0]);
+	if (write) {
+		const ops = isList(write) ? write : writePart?.ops ?? ALL_WRITE_OPS;
+		parts.push([actionsForOps(ops), writePart?.scope]);
 	}
-	return result;
+	if (actions) parts.push([actionsPart?.names ?? actions, actionsPart?.scope]);
+	const seen = /* @__PURE__ */ new Set();
+	const resolved = parts.map(([names, partScope]) => {
+		const fresh = names.filter((n) => !seen.has(n));
+		for (const n of fresh) seen.add(n);
+		return [fresh, composeScope(def.scope, partScope)];
+	});
+	return () => resolved.flatMap(([names, scope]) => rulesFor(resource, names, scope));
+}
+function isList(v) {
+	return Array.isArray(v);
 }
 //#endregion
 //#region src/codegen/extract.ts
@@ -593,4 +1098,4 @@ function generateResourceTypes(map, options) {
 	return lines.join("\n");
 }
 //#endregion
-export { DENY_FILTER, allowTableAction, allowTableRead, allowTableWrite, conjoinScopeFilters, definePrivilege, defineRole, expandExcludeToLeaves, extractResourceActions, generateResourceTypes, getProjectionMode, intersectControlsPolicy, intersectProjections, isFieldAllowed, mergeScopeFilters, restrictProjection, unionControlsPolicy, unionProjections };
+export { DB_SCOPE_KEYS, DENY_FILTER, INHERITED_CONJUNCTION, ScopeFieldConfigError, TABLE_META_ACTIONS, TABLE_OP_ACTIONS, TABLE_READ_ACTIONS, TABLE_WRITE_ACTIONS, allowTableAction, allowTableOps, allowTableRead, allowTableWrite, applyScopeFieldFilters, conjoinRowPolicies, conjoinScopeFilters, conjoinScopes, definePrivilege, defineRole, defineTableAccess, effectiveScope, expandExcludeToLeaves, extractResourceActions, generateResourceTypes, getProjectionMode, intersectControlsPolicy, intersectEnabled, intersectProjections, isFieldAllowed, mergeScopeFilters, needsInheritedConjunction, normalizeScopes, restrictProjection, stableKey, unionControlsPolicy, unionOutcomes, unionProjections };