@aooth/arbac-moost 0.1.71 → 0.1.73

package/dist/index.mjs

@@ -1,12 +1,592 @@
-import { n as ArbacUserProviderToken, r as __decorate, t as ArbacUserProvider } from "./user.provider-CYiwr7y3.mjs";
+import { i as __decorate, n as ArbacUserProvider, r as ArbacUserProviderToken, t as __decorateMetadata } from "./decorateMetadata-CU_mqYGT.mjs";
 import { Arbac, Arbac as Arbac$1, arbacPatternToRegex } from "@aooth/arbac-core";
 import { Authenticate, HttpError } from "@moostjs/event-http";
-import { current, key } from "@wooksjs/event-core";
+import { cached, cachedBy, current, eventTypeKey, key, tryGetCurrent } from "@wooksjs/event-core";
 import { Inherit, Injectable, TInterceptorPriority, defineBeforeInterceptor, getConstructor, getMoostMate, useControllerContext, useLogger } from "moost";
-import { DENY_FILTER, conjoinScopeFilters, expandExcludeToLeaves, getProjectionMode, intersectControlsPolicy, intersectProjections, isFieldAllowed, mergeScopeFilters, restrictProjection, unionControlsPolicy, unionProjections } from "@aooth/arbac";
-import { findAncestorInSet } from "@atscript/db";
-import { AsDbController, AsDbReadableController } from "@atscript/moost-db";
-import { groupByFields } from "@uniqu/core";
+import { DB_SCOPE_KEYS, DENY_FILTER, ScopeFieldConfigError, applyScopeFieldFilters, conjoinScopeFilters, conjoinScopes, effectiveScope, expandExcludeToLeaves, getProjectionMode, intersectEnabled, isFieldAllowed, needsInheritedConjunction, normalizeScopes, restrictProjection, stableKey, unionOutcomes } from "@aooth/arbac";
+import { computeInsights, findAncestorInSet, getPath, isPlainObject } from "@atscript/db";
+import { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsValueHelpController, DB_CRUD_HANDLERS, VALUE_HELP_CRUD_HANDLERS, discoverRowLevelActions, getDbEndpoint, resolveTerminalRef } from "@atscript/moost-db";
+import { groupByFields, walkFilter } from "@uniqu/core";
+//#region src/db/helpers.ts
+/** `map.get(key)`, created with `create()` and stored on a miss. */
+function getOrCreate(map, key, create) {
+	let value = map.get(key);
+	if (value === void 0) {
+		value = create();
+		map.set(key, value);
+	}
+	return value;
+}
+/** `path` or one of its dotted ancestors is in `set`. */
+function hasSelfOrAncestor(set, path) {
+	return set.has(path) || findAncestorInSet(path, set) !== void 0;
+}
+/** A patch (`update` / `updateMany`) — only the keys it carries are written. */
+function isPatchAction(action) {
+	return action === "update" || action === "updateMany";
+}
+/** An update / replace — a write whose target row has a pre-image to scope (USING). */
+function hasPreImage(action) {
+	return action !== "insert" && action !== "insertMany";
+}
+/**
+* A value written as-is to one column: a primitive, `null`, or a class
+* instance (`Date`, a Mongo `ObjectId`, a `Buffer`, …) — never a plain object
+* or an array (a nested patch / an operator shape).
+*/
+function isScalar(v) {
+	if (v === null) return true;
+	if (typeof v === "function") return false;
+	return typeof v !== "object" || !Array.isArray(v) && !isPlainObject(v);
+}
+const navFieldsCache = /* @__PURE__ */ new WeakMap();
+/** The table's navigation fields (`navFields`, else its relation names), cached per table. */
+function navFieldsOf(table) {
+	return table.navFields ?? getOrCreate(navFieldsCache, table, () => new Set(table.relations?.keys()));
+}
+//#endregion
+//#region src/db/visibility.ts
+/**
+* Union the per-scope `projection` whitelists into the single access-control
+* projection used for FIELD-EXISTENCE decisions (`hasField` parity + `/meta`
+* pruning). Returns `undefined` when the union imposes no restriction — no
+* scopes at all, or any scope without a `projection` (a universal grant makes
+* `unionProjections` collapse to the universe `{}`).
+*/
+function unionScopeProjection(scopes) {
+	const allowed = effectiveScope(scopes).projection;
+	return Object.keys(allowed).length === 0 ? void 0 : allowed;
+}
+/**
+* Relation names any scope explicitly declares via `with.<name>` — those
+* relations are governed by the declared sub-scopes alone (parent authority),
+* and the declaration implies the relation EXISTS for this principal even
+* when the projection union does not name it (see {@link ArbacDbScope.with}).
+*/
+function collectWithGrantNames(scopes) {
+	return effectiveScope(scopes).withNames;
+}
+/**
+* Union of write-scope `allowedFields`; `"all"` for field-unrestricted write
+* access. The whitelist exists only when at least one scope carries an
+* `allowedFields` array — scoped-but-unlisted writes are field-unrestricted.
+*/
+function collectWritableFields(scopes, unrestricted) {
+	if (unrestricted) return "all";
+	if (scopes.length === 0) return void 0;
+	const fields = effectiveScope(scopes).allowedFields;
+	if (!fields) return "all";
+	return fields.size > 0 ? fields : void 0;
+}
+/**
+* Whether a flattened dot-path field exists for this principal.
+*
+* - A relation declared via `with.<name>` is visible; a path under it
+*   (`rel.x.y`) is checked as `x.y` against its sub-scope visibility.
+* - An undeclared relation of the table (see {@link MetaVisibility.relationNames})
+*   is visible only when the projection allows its name and the caller's own
+*   grant on the related table resolved ({@link MetaVisibility.relation});
+*   paths under it are checked against that grant.
+* - Anything else follows the projection union (and the derived-column rule).
+*
+* So a field a joined table hides is as unknown in a `$with` sub-query as a
+* top-level hidden column is in the main query (no filter/sort value oracle).
+*/
+function isMetaFieldVisible(path, vis) {
+	if (vis.alwaysVisible.has(path)) return true;
+	const dot = path.indexOf(".");
+	const head = dot === -1 ? path : path.slice(0, dot);
+	if (vis.withGrants.has(head)) {
+		if (dot === -1) return true;
+		const sub = vis.relation?.(head);
+		return sub ? isMetaFieldVisible(path.slice(dot + 1), sub) : true;
+	}
+	const allowed = (p) => vis.isAllowed ? vis.isAllowed(p) : isFieldAllowed(p, vis.allowed);
+	if (vis.relationNames?.has(head)) {
+		if (!allowed(head)) return false;
+		const sub = vis.relation?.(head);
+		if (!sub) return false;
+		return dot === -1 || isMetaFieldVisible(path.slice(dot + 1), sub);
+	}
+	return allowed(path);
+}
+const NO_NAMES$1 = /* @__PURE__ */ new Set();
+const identifierSetCache = /* @__PURE__ */ new WeakMap();
+/** PK + `preferredId` of a table — the identifiers reads always return. */
+function identifierSet(table) {
+	if (!table) return NO_NAMES$1;
+	return getOrCreate(identifierSetCache, table, () => /* @__PURE__ */ new Set([...table.primaryKeys, ...table.preferredId]));
+}
+/**
+* PK + `preferredId` for a controller's table/readable — the
+* {@link MetaVisibility.alwaysVisible} set. Kept for compatibility: the
+* controllers now pass `this.readable` and it is derived there.
+*/
+function metaAlwaysVisibleFields(_controller, source) {
+	return identifierSet(source);
+}
+const NO_POLICY = {
+	json: NO_NAMES$1,
+	derived: /* @__PURE__ */ new Map(),
+	relations: void 0
+};
+const tablePolicyCache = /* @__PURE__ */ new WeakMap();
+function tablePolicy(table) {
+	if (!table) return NO_POLICY;
+	return getOrCreate(tablePolicyCache, table, () => {
+		const derived = /* @__PURE__ */ new Map();
+		for (const fd of table.fieldDescriptors ?? []) if (fd.derived?.sourcePath) derived.set(fd.path, fd.derived.sourcePath);
+		return {
+			json: table.jsonParents ?? NO_NAMES$1,
+			derived,
+			relations: table.relations ? new Set(table.relations.keys()) : void 0
+		};
+	});
+}
+/**
+* Precompiled {@link isFieldAllowed} for one projection: `hasField` asks it
+* for every referenced path, so the mode and key sets are computed once.
+* Inclusion: the path, an ancestor, or a descendant is listed. Exclusion: no
+* listed key is the path or an ancestor.
+*/
+function compileProjection(projection) {
+	const keys = Object.keys(projection);
+	if (keys.length === 0) return () => true;
+	const listed = new Set(keys);
+	if (getProjectionMode(projection) === "exclude") return (path) => !hasSelfOrAncestor(listed, path);
+	const parents = /* @__PURE__ */ new Set();
+	for (const key of keys) {
+		let pos = key.length;
+		while ((pos = key.lastIndexOf(".", pos - 1)) !== -1) parents.add(key.slice(0, pos));
+	}
+	return (path) => parents.has(path) || hasSelfOrAncestor(listed, path);
+}
+/**
+* The projection union made executable and consistent for the table:
+*
+* - **atomic JSON** — a scope key inside an atomic JSON column (relational
+*   adapters) is folded onto the column: an excluded leaf hides the whole
+*   column (`{ "settings.apiKey": 0 }` → `{ settings: 0 }`), a whitelisted
+*   leaf alone does not reveal it (the key is dropped — fail closed);
+* - **derived columns** — a `@db.column.derived` field whose source the
+*   projection hides is excluded too (or dropped from a whitelist).
+*
+* An include projection the rewrite emptied would read as the universe: it
+* falls back to the table's identifiers (reads return them anyway), else
+* keeps the original (unexecutable → fails closed rather than widening).
+*/
+function normalizeAllowed(allowed, policy, identifiers) {
+	const keys = Object.keys(allowed);
+	if (keys.length === 0) return allowed;
+	const exclude = getProjectionMode(allowed) === "exclude";
+	let out;
+	if (policy.json.size > 0) for (const key of keys) {
+		const column = findAncestorInSet(key, policy.json);
+		if (column === void 0) continue;
+		out ??= { ...allowed };
+		delete out[key];
+		if (exclude) out[column] = 0;
+	}
+	if (policy.derived.size > 0) {
+		const visible = compileProjection(out ?? allowed);
+		for (const [path, source] of policy.derived) {
+			if (identifiers.has(source) || visible(source)) continue;
+			if (exclude) {
+				if (!visible(path)) continue;
+				out ??= { ...allowed };
+				out[path] = 0;
+			} else if ((out ?? allowed)[path] !== void 0) {
+				out ??= { ...allowed };
+				delete out[path];
+			}
+		}
+	}
+	if (!out || exclude || Object.keys(out).length > 0) return out ?? allowed;
+	if (identifiers.size === 0) return allowed;
+	return Object.fromEntries([...identifiers].map((id) => [id, 1]));
+}
+/**
+* The declared relations governed by their `with` sub-scopes alone. A
+* sub-scope a credential conjunction marked `INHERITED_CONJUNCTION` (declared
+* by one side only) is not: such a relation follows the undeclared-relation
+* rule — visible only once resolved (conjoined with the caller's own grant
+* on the related table).
+*/
+function parentAuthorityGrants(eff) {
+	const names = eff.withNames;
+	for (const name of names) if (eff.withScopes(name).some(needsInheritedConjunction)) return new Set([...names].filter((n) => !eff.withScopes(n).some(needsInheritedConjunction)));
+	return names;
+}
+/**
+* Build the {@link MetaVisibility} a set of read scopes implies — the single
+* structure behind `hasField`, `/meta` pruning, `$select` value stripping
+* and the `$with` overlay, so they cannot drift. Own fields: the projection
+* union (`{}` when unrestricted), normalized for atomic JSON columns and
+* derived-column sources, precompiled into `isAllowed`. Relations: an
+* undeclared one → its node in `relations` (none → hidden); a declared
+* `with.<name>` → the union of its sub-scopes (lazily built when `relations`
+* has no node for it). The related table's own PK / `preferredId` stay
+* visible.
+*
+* @param opts - {@link ScopeVisibilityOptions}; a bare identifier set is the
+*   0.1.71 `alwaysVisible` argument
+*/
+function buildScopeVisibility(scopes, table, opts = {}) {
+	const { alwaysVisible = identifierSet(table), relations } = opts instanceof Set ? { alwaysVisible: opts } : opts;
+	const eff = effectiveScope(scopes);
+	const withGrants = parentAuthorityGrants(eff);
+	const policy = tablePolicy(table);
+	const allowed = normalizeAllowed(unionScopeProjection(scopes) ?? {}, policy, alwaysVisible);
+	const base = compileProjection(allowed);
+	const isAllowed = policy.derived.size === 0 ? base : (path) => {
+		if (!base(path)) return false;
+		const source = policy.derived.get(path);
+		return source === void 0 || alwaysVisible.has(source) || base(source);
+	};
+	const declared = /* @__PURE__ */ new Map();
+	return {
+		allowed,
+		alwaysVisible,
+		withGrants,
+		relationNames: policy.relations,
+		scopes,
+		table,
+		isAllowed,
+		relation(name) {
+			const resolved = relations?.get(name);
+			if (resolved || !withGrants.has(name)) return resolved ?? void 0;
+			return getOrCreate(declared, name, () => buildScopeVisibility(eff.withScopes(name), table?.relatedTable?.(name)));
+		}
+	};
+}
+const scopeVisibilityCache = /* @__PURE__ */ new WeakMap();
+const NO_TABLE = {
+	primaryKeys: [],
+	preferredId: []
+};
+/** `source` is an identifier set (the 0.1.67 signatures), not a readable. */
+function isIdentifierSet(source) {
+	return !("primaryKeys" in source);
+}
+/**
+* The memoized {@link MetaVisibility} for `scopes` over `source` (a
+* readable, or an `alwaysVisible` identifier set), without relation
+* resolution (undeclared relations hidden).
+*/
+function scopeVisibility(scopes, source = NO_TABLE) {
+	return getOrCreate(getOrCreate(scopeVisibilityCache, scopes, () => /* @__PURE__ */ new WeakMap()), source, () => isIdentifierSet(source) ? buildScopeVisibility(scopes, void 0, source) : buildScopeVisibility(scopes, source === NO_TABLE ? void 0 : source));
+}
+//#endregion
+//#region src/db/relation-policy.ts
+/** Registry bucket for controllers without an `app`. */
+const NO_APP = {};
+const registry = /* @__PURE__ */ new WeakMap();
+/**
+* Register an ARBAC DB controller as an owner of its readable's ARBAC
+* resource, so a `$with` from another controller can evaluate the caller's
+* own grant on the joined table. Called once per controller instance (a
+* field initializer of the ARBAC DB controllers). Scoped per moost app and
+* keyed by the readable's annotated type; a newer instance of the same class
+* replaces the older one.
+*
+* @returns `true` (so it can initialize a field)
+* @since 0.1.72
+*/
+function registerArbacDbTarget(controller) {
+	const c = controller;
+	const target = c.readable?.type ?? c.readable;
+	if (!target) return true;
+	getOrCreate(getOrCreate(registry, c.app ?? NO_APP, () => /* @__PURE__ */ new WeakMap()), target, () => /* @__PURE__ */ new Map()).set(getConstructor(controller), controller);
+	return true;
+}
+function registeredControllers(target) {
+	let app = NO_APP;
+	try {
+		app = useControllerContext().getController()?.app ?? NO_APP;
+	} catch {}
+	const perTarget = registry.get(app)?.get(target);
+	return perTarget ? [...perTarget.values()] : [];
+}
+/**
+* The ARBAC resource + action a controller's handler is authorized as — the
+* precedence `useArbac()` applies while that handler serves a request.
+* Resource: method `@ArbacResource` → class `@ArbacResource` → controller id
+* → class name. Action: method `@ArbacAction` → `@DbAction` name → class
+* `@ArbacAction` → method `@Id` → method name.
+*
+* @since 0.1.72
+*/
+function resolveHandlerArbacIds(instance, methodName) {
+	const mate = getMoostMate();
+	return arbacIdsFromMeta(mate.read(instance), mate.read(instance, methodName), instance, methodName);
+}
+/**
+* Evaluate several handlers as ONE surface (memoized per event): the scopes
+* of every allowing handler concatenated (`unionOutcomes`); `undefined` when
+* none allows.
+*/
+async function evaluateHandlers(ids) {
+	return unionOutcomes(await evaluateHandlerOutcomes(ids));
+}
+/** The raw per-handler outcomes behind {@link evaluateHandlers} (memoized per event). */
+function evaluateHandlerOutcomes(ids) {
+	return Promise.all(ids.map((id) => evaluateArbacCached(id.resource, id.action, id.table)));
+}
+/**
+* The caller's read scopes on the readable of annotated type `type` (a
+* `$with` / `ref` target) through its registered ARBAC DB controllers (their
+* `query` handler, each evaluated against ITS table's schema), plus a
+* registered controller's readable — `null` when none is registered or none
+* allows.
+*/
+async function evaluateTypeRead(type) {
+	const controllers = registeredControllers(type);
+	if (controllers.length === 0) return null;
+	const scopes = await evaluateHandlers(controllers.map((c) => ({
+		...resolveHandlerArbacIds(c, "query"),
+		table: c.readable
+	})));
+	return scopes ? {
+		scopes,
+		table: controllers[0].readable
+	} : null;
+}
+/**
+* Deepest `$with` nesting resolved: the request controls the depth, and each
+* level may evaluate grants. A deeper relation stays unresolved (hidden).
+*/
+const MAX_WITH_DEPTH = 16;
+/**
+* Relation names a parsed `$with` control reaches, per level. A dotted
+* name (`a.b`) nests like `a($with=b)`.
+*/
+function withNameTree(withArr, into = /* @__PURE__ */ new Map(), depth = 0) {
+	if (!Array.isArray(withArr) || depth >= MAX_WITH_DEPTH) return into;
+	for (const raw of withArr) {
+		const entry = raw;
+		const name = typeof raw === "string" ? raw : entry?.name;
+		if (typeof name !== "string" || !name) continue;
+		const segments = name.split(".");
+		if (depth + segments.length > MAX_WITH_DEPTH) continue;
+		let level = into;
+		for (const segment of segments) level = getOrCreate(level, segment, () => /* @__PURE__ */ new Map());
+		if (entry && typeof entry === "object") withNameTree(entry.controls?.$with ?? entry.$with, level, depth + segments.length);
+	}
+	return into;
+}
+/**
+* Resolve every relation in `names` against `scopes` over `table` into the
+* visibility its joined rows obey: a declared `with.<name>` → its
+* sub-scopes; otherwise the caller's own read grant on the related table
+* (`null` = hidden). Recurses into nested names — the decision is made here
+* once; `MetaVisibility.relation()` only reads it.
+*
+* When a level names a hidden or nonexistent relation, the level's OTHER
+* relations are resolved too (one level deep — `listSiblings: false` skips
+* it), so the `Unknown relation` 400 can list the relations the caller may
+* use — never the hidden ones.
+*/
+async function resolveRelationTree(scopes, table, names, opts = {}) {
+	const out = /* @__PURE__ */ new Map();
+	const resolveOne = async (name, nested) => {
+		const target = table?.relatedTable?.(name);
+		const declared = effectiveScope(scopes).withScopes(name);
+		const inherits = declared.length === 0 || declared.some(needsInheritedConjunction);
+		const read = inherits && target ? await evaluateTypeRead(target.type ?? target) : null;
+		let nodeScopes = inherits ? read?.scopes : declared;
+		if (nodeScopes && declared.length > 0 && inherits) nodeScopes = [conjoinForTable(declared, nodeScopes, target, await currentScopeFields())];
+		if (!nodeScopes) {
+			out.set(name, null);
+			return;
+		}
+		const relations = nested.size > 0 ? await resolveRelationTree(nodeScopes, target, nested, opts) : void 0;
+		out.set(name, buildScopeVisibility(nodeScopes, target, { relations }));
+	};
+	await Promise.all([...names].map(([name, nested]) => resolveOne(name, nested)));
+	if (opts.listSiblings !== false && [...out.values()].includes(null) && table?.relations) {
+		const siblings = [...table.relations.keys()].filter((name) => !out.has(name));
+		await Promise.all(siblings.map((name) => resolveOne(name, /* @__PURE__ */ new Map())));
+	}
+	return out;
+}
+const requestRelationsKey = key("arbac.db.relations");
+/**
+* Per-request `$with` policy for the ARBAC DB controllers' `prepareRequest`:
+* resolves every relation `controls.$with` names (recursively) and stores
+* the resolution the request's visibility (`hasField`, `validateControls`,
+* `transformProjection`) reads.
+*/
+async function resolveRequestRelations(scopes, controls, readable) {
+	const names = withNameTree(controls?.$with);
+	if (names.size === 0) return;
+	current().set(requestRelationsKey, await resolveRelationTree(scopes, readable, names));
+}
+/** The resolution {@link resolveRequestRelations} stored for the current event, if any. */
+function requestRelations() {
+	const ctx = current();
+	return ctx.has(requestRelationsKey) ? ctx.get(requestRelationsKey) : void 0;
+}
+//#endregion
+//#region src/db/write-refs.ts
+/**
+* The FK a `checkRefs` entry designates: one of its local fields, or the TO
+* relation it backs (`readable.foreignKeyOf`). A name that is neither is a
+* configuration error.
+*/
+function refForeignKeyOf(table, name) {
+	const fk = [...table.foreignKeys?.values() ?? []].find((f) => f.fields.includes(name)) ?? table.foreignKeyOf?.(name);
+	if (fk) return fk;
+	throw new Error(`checkRefs: "${name}" is not a foreign key field or TO relation of this table`);
+}
+/**
+* The FKs whose target check applies to a write under `scopes` — the union
+* rule: write scopes grant additively (more roles = more access), so a scope
+* WITHOUT the flag for an FK grants unconstrained writes of it; the check is
+* enforced only for the FKs EVERY scope enables (intersection).
+*
+* @example
+* ```ts
+* // role "member":  { filter: { tenant }, checkRefs: ["projectId"] }
+* // role "auditor": { filter: { tenant }, checkRefs: true }
+* // member + auditor → projectId checked (both enable it); assigneeId not
+* // role "importer": { filter: { tenant } }            // no checkRefs
+* // member + importer → nothing checked (importer grants unconstrained FK writes)
+* ```
+*/
+function enforcedRefs(scopes, table) {
+	const all = table.foreignKeys;
+	if (!all || all.size === 0 || scopes.length === 0) return [];
+	const enforced = intersectEnabled(scopes.map((s) => s.checkRefs === true ? true : new Set((s.checkRefs ?? []).map((name) => refForeignKeyOf(table, name)))));
+	return enforced === true ? [...all.values()] : [...enforced];
+}
+/**
+* Canonical `checkRefs` of a conjunction (credential attenuation): the FKs
+* EITHER side enforces — each side resolved with {@link enforcedRefs} —
+* named by their first local field. `true` when that is every FK of the
+* table; `undefined` when none. Without the table's schema the names are
+* combined as written (per side: the entries every scope lists, `true`
+* matching any).
+*/
+function conjoinCheckRefs(userScopes, credScopes, table) {
+	if (!table?.foreignKeys) {
+		const u = effectiveScope(userScopes).checkRefs;
+		const c = effectiveScope(credScopes).checkRefs;
+		if (u === true || c === true) return true;
+		const names = /* @__PURE__ */ new Set([...u, ...c]);
+		return names.size > 0 ? [...names].toSorted() : void 0;
+	}
+	const all = /* @__PURE__ */ new Set([...enforcedRefs(userScopes, table), ...enforcedRefs(credScopes, table)]);
+	if (all.size === 0) return void 0;
+	if (all.size === table.foreignKeys.size) return true;
+	return [...all].map((fk) => fk.fields[0]).toSorted();
+}
+/** A row value at `path`: a literal dotted key first, else the nested path. */
+function readPath(row, path) {
+	return path in row ? row[path] : getPath(row, path);
+}
+function outOfScope(fk) {
+	return new HttpError(403, `Referenced row "${fk.fields.join(", ")}" is outside your scope`);
+}
+/** A patch row touches `fk` in part only — its tuple is completed from the pre-image. */
+function needsPreImage(row, fk) {
+	const touched = fk.fields.filter((f) => readPath(row, f) !== void 0).length;
+	return touched > 0 && touched < fk.fields.length;
+}
+/**
+* The distinct FK tuples the write SETS: insert / replace rows carry them in
+* full; an update patch only when it touches the FK (a composite FK touched
+* in part is completed from the pre-image). A null / absent part → no
+* reference, skipped. A plain object / array value (an operator shape) →
+* 403 (fail closed); scalars and class instances (a Mongo `ObjectId`, a
+* `Date`) are FK values.
+*/
+function referencedTuples(ctx, fk, pre) {
+	const isPatch = isPatchAction(ctx.action);
+	const tuples = /* @__PURE__ */ new Map();
+	for (let i = 0; i < ctx.rows.length; i++) {
+		const row = ctx.rows[i];
+		if (isPatch && !fk.fields.some((f) => readPath(row, f) !== void 0)) continue;
+		const source = pre[i] ? {
+			...pre[i],
+			...row
+		} : row;
+		const tuple = fk.fields.map((f) => readPath(source, f));
+		if (tuple.some((v) => v === null || v === void 0)) continue;
+		if (!tuple.every(isScalar)) throw outOfScope(fk);
+		tuples.set(stableKey(tuple), tuple);
+	}
+	return [...tuples.values()];
+}
+/** The target-row filter of `tuples` over `fk.targetFields`. */
+function targetFilter(fk, tuples) {
+	if (fk.targetFields.length === 1) return { [fk.targetFields[0]]: { $in: tuples.map((t) => t[0]) } };
+	return { $or: tuples.map((t) => Object.fromEntries(fk.targetFields.map((f, j) => [f, t[j]]))) };
+}
+async function countInScope(table, ids, scope) {
+	return table.count({
+		filter: scope ? { $and: [ids, scope] } : ids,
+		controls: {}
+	});
+}
+/**
+* One target type's check: every referenced row must be readable by the
+* caller there — ONE count over all of its FKs' references; on a shortfall
+* (or two FKs naming one row through different keys) each FK is re-counted
+* exactly so the error names the offending FK.
+*/
+async function assertTargetRefs(type, refs) {
+	const target = await evaluateTypeRead(type);
+	const table = target?.table;
+	if (!target || typeof table?.count !== "function") throw outOfScope(refs[0].fk);
+	const scope = effectiveScope(target.scopes).filter;
+	if (refs.length > 1) {
+		const keys = /* @__PURE__ */ new Set();
+		for (const { fk, tuples } of refs) for (const t of tuples) keys.add(`${fk.targetFields.join(",")}:${stableKey(t)}`);
+		if (await countInScope(table, { $or: refs.map(({ fk, tuples }) => targetFilter(fk, tuples)) }, scope) === keys.size) return;
+	}
+	for (const { fk, tuples } of refs) if (await countInScope(table, targetFilter(fk, tuples), scope) !== tuples.length) throw outOfScope(fk);
+}
+/**
+* `checkRefs` enforcement for a write (runs in `guardWrite`, inside the
+* write's transaction): every FK {@link enforcedRefs} returns that the write
+* sets must reference rows the caller can read on the target table (its own
+* `query` grant there) — one count per target table — else 403
+* `Referenced row "<field>" is outside your scope`. No registered ARBAC
+* controller on the target, or no read grant there → 403 as well.
+*
+* @since 0.1.72
+*/
+async function assertRefsInScope(ctx, scopes, table) {
+	const fks = enforcedRefs(scopes, table);
+	if (fks.length === 0) return;
+	const pre = isPatchAction(ctx.action) && ctx.rows.some((row) => fks.some((fk) => needsPreImage(row, fk))) ? await ctx.currentAll() : [];
+	const byType = /* @__PURE__ */ new Map();
+	for (const fk of fks) {
+		const tuples = referencedTuples(ctx, fk, pre);
+		if (tuples.length === 0) continue;
+		const type = fk.targetTypeRef?.();
+		if (!type) throw outOfScope(fk);
+		getOrCreate(byType, type, () => []).push({
+			fk,
+			tuples
+		});
+	}
+	for (const [type, refs] of byType) await assertTargetRefs(type, refs);
+}
+/**
+* Start the target-table evaluations {@link assertRefsInScope} will need, so
+* the in-transaction guard finds them memoized (fire-and-forget: a failure
+* resurfaces where the guard awaits it).
+*/
+function prefetchRefTargets(scopes, table) {
+	const types = /* @__PURE__ */ new Set();
+	for (const fk of enforcedRefs(scopes, table)) {
+		const type = fk.targetTypeRef?.();
+		if (type) types.add(type);
+	}
+	for (const type of types) evaluateTypeRead(type).catch(() => {});
+}
+//#endregion
 //#region src/attenuation.ts
 /**
 * Conjoin the full-authority scopes (`userScopes`, the ceiling) and the
@@ -14,11 +594,12 @@ import { groupByFields } from "@uniqu/core";
 * `ArbacDbScope`. A row/field/control is admitted only if BOTH passes admit
 * it — the normative restrict-only clip that closes the attr-widen hole.
 *
-* Each side is first UNIONed with the existing additive helpers (today's
-* machinery), then the two RESULTS are CONJOINED with the dedicated combiners
-* ({@link conjoinScopeFilters} `$and`, {@link intersectProjections} field ∩,
-* {@link intersectControlsPolicy} deny-wins, `with` recursion) — never the
-* additive union helpers, which would silently widen.
+* Each side is first UNIONed, then the two results are CONJOINED facet by
+* facet with `conjoinScopes` from `@aooth/arbac` (`$and` filters and WITH
+* CHECK filters, path-wise projection ∩, deny-wins controls, `allowedFields`
+* / `nestedWrites` intersection, `set` combined with the USER winning a key
+* conflict, recursive `with`) — never the additive union helpers, which
+* would silently widen.
 *
 * Returned as a single-element list so every downstream scope-application
 * site (which UNIONs the cached scope list per facet) sees the identity of a
@@ -31,118 +612,252 @@ import { groupByFields } from "@uniqu/core";
 * closed). When NO field survives (`{a:1}` ∩ `{a:0}`, disjoint whitelists),
 * the composite keeps the user's projection and gets a match-nothing filter —
 * an empty field set must never read as the unrestricted `{}`. `with`
-* sub-scopes are conjoined without a schema.
-*/
-function conjoinArbacDbScopes(userScopes, credScopes, childrenOf) {
-	const userProjection = unionProjections(...userScopes.map((s) => s.projection ?? {}));
-	const intersected = intersectProjections(userProjection, unionProjections(...credScopes.map((s) => s.projection ?? {})), childrenOf);
-	const projection = intersected ?? userProjection;
-	const credFilter = mergeScopeFilters(credScopes.map((s) => s.filter ?? {}));
-	const filter = conjoinScopeFilters(mergeScopeFilters(userScopes.map((s) => s.filter ?? {})), intersected ? credFilter : conjoinScopeFilters(credFilter, DENY_FILTER));
-	const controls = intersectControlsPolicy(unionControlsPolicy(userScopes), unionControlsPolicy(credScopes));
-	const allowedFields = intersectAllowedFields(userScopes, credScopes);
-	const set = combineSet(userScopes, credScopes);
-	const withMap = conjoinWith(userScopes, credScopes);
-	const s = {};
-	if (filter && Object.keys(filter).length > 0) s.filter = filter;
-	if (Object.keys(projection).length > 0) s.projection = projection;
-	if (Object.keys(controls).length > 0) s.controls = controls;
-	if (allowedFields) s.allowedFields = allowedFields;
-	if (set) s.set = set;
-	if (withMap) s.with = withMap;
-	return [s];
-}
-/**
-* Intersect the two sides' `allowedFields` write-whitelists (the credential
-* may write FEWER fields). A side with no whitelist is unrestricted (all
-* fields), so the other side wins; both restricting → set intersection.
-*/
-function intersectAllowedFields(userScopes, credScopes) {
-	const u = unionAllowedFields(userScopes);
-	const c = unionAllowedFields(credScopes);
-	if (u === void 0) return c;
-	if (c === void 0) return u;
-	const cset = new Set(c);
-	return [...new Set(u)].filter((f) => cset.has(f)).toSorted();
-}
-function unionAllowedFields(scopes) {
-	let set;
-	for (const s of scopes) if (Array.isArray(s.allowedFields)) {
-		set ??= /* @__PURE__ */ new Set();
-		for (const f of s.allowedFields) set.add(f);
-	}
-	return set ? [...set] : void 0;
-}
-/**
-* Combine the two sides' `set` overlays. `set` forces field values on writes;
-* both sides' forced constraints apply, and on a key conflict the USER's value
-* wins so the credential can only ADD constraints, never override the owner's.
-*/
-function combineSet(userScopes, credScopes) {
-	const u = unionSet(userScopes);
-	const c = unionSet(credScopes);
-	if (!u && !c) return void 0;
-	return {
-		...c,
-		...u
-	};
-}
-function unionSet(scopes) {
-	let out;
-	for (const s of scopes) if (s.set) {
-		out ??= {};
-		Object.assign(out, s.set);
-	}
-	return out;
-}
-/**
-* Recurse the conjunction into joined-resource sub-scopes. A relation declared
-* on only one side is conjoined against the other side's silence (unrestricted
-* = identity), so a credential can narrow a relation the user left open but
-* never widen one the user restricted.
+* sub-scopes are conjoined without a schema. `checkRefs` enforces what either
+* side enforces (resolved against `refTable`'s foreign keys when given — the
+* evaluated table). A custom (declaration-merged) scope field is conjoined by
+* its `fields` rule; without one this THROWS — never dropped (fail closed).
+*
+* The third argument is the options object, or (legacy form) `childrenOf`.
 */
-function conjoinWith(userScopes, credScopes) {
-	const relNames = /* @__PURE__ */ new Set();
-	for (const s of userScopes) if (s.with) for (const k of Object.keys(s.with)) relNames.add(k);
-	for (const s of credScopes) if (s.with) for (const k of Object.keys(s.with)) relNames.add(k);
-	if (relNames.size === 0) return void 0;
-	const out = {};
-	for (const rel of relNames) out[rel] = conjoinArbacDbScopes(userScopes.map((s) => s.with?.[rel]).filter(Boolean), credScopes.map((s) => s.with?.[rel]).filter(Boolean))[0];
-	return out;
+function conjoinArbacDbScopes(userScopes, credScopes, opts) {
+	const { childrenOf, refTable, fields } = typeof opts === "function" ? { childrenOf: opts } : opts ?? {};
+	return [conjoinScopes(userScopes, credScopes, {
+		childrenOf,
+		checkRefs: refTable?.foreignKeys ? (u, c) => conjoinCheckRefs(u, c, refTable) : void 0,
+		fields
+	})];
 }
 //#endregion
 //#region src/db/field-children.ts
 const fieldChildrenCache = /* @__PURE__ */ new WeakMap();
+const NONE = /* @__PURE__ */ new Set();
 /**
 * The `TProjectionChildren` schema lookup for a table (its own `flatMap` paths —
-* navigation descendants excluded, they are joined rows, not columns);
+* navigation descendants excluded, they are joined rows, not columns; so are
+* the descendants of an atomic JSON column — `readable.jsonParents`);
 * `undefined` when the table exposes no flattened schema.
 */
 function fieldChildrenOf(table) {
-	if (!table?.flatMap) return void 0;
-	let lookup = fieldChildrenCache.get(table);
-	if (!lookup) {
-		const nav = table.navFields ?? new Set(table.relations?.keys());
+	const flatMap = table?.flatMap;
+	if (!flatMap) return void 0;
+	return getOrCreate(fieldChildrenCache, table, () => {
+		const nav = navFieldsOf(table);
+		const json = table.jsonParents ?? NONE;
 		const byParent = /* @__PURE__ */ new Map();
-		for (const path of table.flatMap.keys()) {
+		for (const path of flatMap.keys()) {
 			const dot = path.lastIndexOf(".");
 			if (dot === -1) continue;
 			const parent = path.slice(0, dot);
-			if (nav.has(parent) || findAncestorInSet(parent, nav) !== void 0) continue;
-			const list = byParent.get(parent);
-			if (list) list.push(path);
-			else byParent.set(parent, [path]);
+			if (hasSelfOrAncestor(nav, parent) || hasSelfOrAncestor(json, parent)) continue;
+			getOrCreate(byParent, parent, () => []).push(path);
 		}
-		lookup = (path) => byParent.get(path) ?? [];
-		fieldChildrenCache.set(table, lookup);
-	}
-	return lookup;
+		return (path) => byParent.get(path) ?? [];
+	});
 }
 //#endregion
 //#region src/moost-arbac.ts
-let MoostArbac = class MoostArbac extends Arbac$1 {};
+let MoostArbac = class MoostArbac extends Arbac$1 {
+	scopeFieldRules = {};
+	/**
+	* Register the conjunction rule of custom (declaration-merged) scope
+	* fields — used wherever two scope lists are conjoined into one composite
+	* scope (credential attenuation, and the `with` sub-scopes it builds). A
+	* custom field present in a conjunction without a rule fails the request
+	* with a generic 500 (never dropped: a dropped field would read as
+	* unrestricted). A rule's optional `rowFilter` turns the field into a ROW
+	* restriction every framework row path enforces (folded into each
+	* evaluated scope's `filter`). Each field is registered once; a built-in
+	* `ArbacDbScope` key is rejected.
+	*
+	* @example
+	* ```ts
+	* arbac.registerScopeFields({
+	*   teams: {
+	*     conjoin: (user, cred) => intersectTeams(user, cred),
+	*     rowFilter: (teams) => ({ teamId: { $in: teams } }),
+	*   },
+	* });
+	* ```
+	* @since 0.1.72
+	*/
+	registerScopeFields(rules) {
+		const entries = Object.entries(rules);
+		for (const [name, rule] of entries) {
+			if (DB_SCOPE_KEYS.includes(name)) throw new Error(`registerScopeFields: "${name}" is a built-in scope key`);
+			if (typeof rule?.conjoin !== "function") throw new TypeError(`registerScopeFields: "${name}" needs a conjoin(a, b) function`);
+			if (rule.rowFilter !== void 0 && typeof rule.rowFilter !== "function") throw new TypeError(`registerScopeFields: "${name}".rowFilter must be a function`);
+			const existing = this.scopeFieldRules[name];
+			if (existing && existing !== rule) throw new Error(`registerScopeFields: scope field "${name}" is already registered`);
+		}
+		this.scopeFieldRules = {
+			...this.scopeFieldRules,
+			...Object.fromEntries(entries)
+		};
+		return this;
+	}
+	/**
+	* The engine's evaluation with every custom field's `rowFilter` folded
+	* into each evaluated scope's `filter` (both passes of an attenuated
+	* evaluation, each with its own scopes) — so every consumer, direct
+	* engine calls included, sees the row restriction. A non-built-in scope
+	* key without a registered rule is warned about once.
+	*/
+	async evaluate(res, user) {
+		const result = await super.evaluate(res, user);
+		const fold = (list) => list && applyScopeFieldFilters(list, this.scopeFieldRules, { onUnknownField: this.warnUnknownField });
+		const scopes = fold(result.scopes);
+		const credScopes = fold(result.credScopes);
+		if (scopes === result.scopes && credScopes === result.credScopes) return result;
+		const out = {
+			...result,
+			scopes
+		};
+		if (credScopes !== void 0) out.credScopes = credScopes;
+		return out;
+	}
+	warnedFields = /* @__PURE__ */ new Set();
+	warnUnknownField = (field) => {
+		if (this.warnedFields.has(field)) return;
+		this.warnedFields.add(field);
+		console.warn(`[arbac] Scope field "${field}" has no rule registered with registerScopeFields: it reaches only your own code, and an attenuated request carrying it fails with 500.`);
+	};
+	/** The registered custom scope field rules. @since 0.1.72 */
+	getScopeFields() {
+		return this.scopeFieldRules;
+	}
+};
 MoostArbac = __decorate([Injectable()], MoostArbac);
 //#endregion
+//#region src/arbac.evaluate.ts
+/**
+* The ARBAC resource + action a handler is authorized as. Resource: method
+* `@ArbacResource` → class `@ArbacResource` → controller id → class name.
+* Action: method `@ArbacAction` → `@DbAction` name → class `@ArbacAction` →
+* method `@Id` → method name.
+*/
+function arbacIdsFromMeta(cMeta, mMeta, controller, methodName) {
+	return {
+		resource: mMeta?.arbacResourceId || cMeta?.arbacResourceId || cMeta?.id || getConstructor(controller).name,
+		action: mMeta?.arbacActionId || mMeta?.atscript_db_action?.name || cMeta?.arbacActionId || mMeta?.id || methodName
+	};
+}
+/** The 403 every ARBAC deny answers. */
+function insufficientPrivileges(resource, action) {
+	return new HttpError(403, `Insufficient privileges for action "${action}" on resource "${resource}"`);
+}
+async function loadPrincipal(user) {
+	const userId = await user.getUserId();
+	const [roles, att] = await Promise.all([user.getRoles(userId), user.getAttenuation?.()]);
+	let attrs;
+	return {
+		userId,
+		roles,
+		attenuate: att && (att.roles !== void 0 || att.attrs !== void 0) ? {
+			roles: att.roles,
+			attrs: att.attrs,
+			...att.allowUnheldRoles === true && { allowUnheldRoles: true }
+		} : void 0,
+		attrs: (id) => attrs ??= Promise.resolve(user.getAttrs(id))
+	};
+}
+const principalKey = key("arbac.principal");
+function isHttpEvent(ctx) {
+	return ctx.has(eventTypeKey) && ctx.get(eventTypeKey) === "http";
+}
+const evalMemo = cachedBy((_table) => /* @__PURE__ */ new Map());
+/**
+* Evaluate `target` for the current principal. Attenuated + allowed: the
+* ceiling pass and the narrowed pass are conjoined into ONE composite scope
+* (every downstream site unions the list per facet — a one-element union is
+* the identity). `table` defaults to the current controller's `readable`.
+*/
+function evaluateArbac(ctx, target, memoPrincipal = false) {
+	const cc = useControllerContext(ctx);
+	const table = target.table ?? cc.getController()?.readable;
+	const pending = (async () => {
+		const [user, arbac] = await Promise.all([cc.instantiate(ArbacUserProviderToken), cc.instantiate(MoostArbac)]);
+		let principal;
+		if (!memoPrincipal || !isHttpEvent(ctx)) principal = loadPrincipal(user);
+		else if (ctx.has(principalKey)) principal = ctx.get(principalKey);
+		else ctx.set(principalKey, principal = loadPrincipal(user));
+		const p = await principal;
+		const result = await arbac.evaluate({
+			resource: target.resource,
+			action: target.action
+		}, {
+			id: p.userId,
+			roles: p.roles,
+			attrs: p.attrs,
+			attenuate: p.attenuate
+		});
+		if (result.allowed && result.credScopes !== void 0) return {
+			allowed: true,
+			scopes: [conjoinForTable(result.scopes ?? [], result.credScopes, table, arbac.getScopeFields())],
+			userId: p.userId
+		};
+		return {
+			allowed: result.allowed,
+			scopes: result.scopes,
+			userId: p.userId
+		};
+	})();
+	evalMemo(table, ctx).set(`${target.resource}\u0000${target.action}`, pending);
+	return pending;
+}
+const loggedConfigErrors = /* @__PURE__ */ new Set();
+/**
+* Run `fn`; a {@link ScopeFieldConfigError} (a server misconfiguration)
+* becomes a generic 500 — the details are logged server-side once per
+* distinct error, never sent to the client. Fail closed either way.
+*/
+function asServerError(fn) {
+	try {
+		return fn();
+	} catch (error) {
+		if (!(error instanceof ScopeFieldConfigError)) throw error;
+		if (!loggedConfigErrors.has(error.message)) {
+			loggedConfigErrors.add(error.message);
+			useLogger("arbac").error(error.message);
+		}
+		throw new HttpError(500, "Internal Server Error");
+	}
+}
+/**
+* THE conjunction of two scope lists over `table` (credential attenuation,
+* and a `$with` sub-scope ∧ the caller's grant on the related table): the
+* table's schema subtracts nested exclusions exactly, its foreign keys
+* resolve `checkRefs`, `fields` conjoin custom scope fields — and an
+* unregistered custom field is a generic 500 ({@link asServerError}).
+*/
+function conjoinForTable(a, b, table, fields) {
+	return asServerError(() => conjoinArbacDbScopes(a, b, {
+		childrenOf: fieldChildrenOf(table),
+		refTable: table,
+		fields
+	})[0]);
+}
+const scopeFieldsSlot = cached(async (ctx) => (await useControllerContext(ctx).instantiate(MoostArbac)).getScopeFields());
+/** The current app's custom scope field rules — resolved once per event. */
+function currentScopeFields() {
+	return current().get(scopeFieldsSlot);
+}
+/**
+* {@link evaluateArbac} memoized for the current HTTP event (with the
+* per-event principal memo) — `/meta`, `$with` resolution and `checkRefs`
+* evaluate the same pairs repeatedly, and an evaluation the authorize
+* interceptor already ran is reused. Other events (a WF event spans steps)
+* evaluate afresh. `table` omitted → the current controller's readable.
+*/
+function evaluateArbacCached(resource, action, table) {
+	const ctx = current();
+	const normalized = table ?? useControllerContext(ctx).getController()?.readable;
+	return (isHttpEvent(ctx) ? evalMemo(normalized, ctx).get(`${resource}\u0000${action}`) : void 0) ?? evaluateArbac(ctx, {
+		resource,
+		action,
+		table: normalized
+	}, true);
+}
+//#endregion
 //#region src/arbac.composables.ts
 /**
 * Writable slot holding the evaluated scopes for the current event.
@@ -188,40 +903,18 @@ const useArbac = (_ctx) => {
 	};
 	const cMeta = cc.getControllerMeta();
 	const mMeta = cc.getMethodMeta();
-	const resource = mMeta?.arbacResourceId || cMeta?.arbacResourceId || cMeta?.id || getConstructor(cc.getController()).name;
-	const action = mMeta?.arbacActionId || mMeta?.atscript_db_action?.name || cMeta?.arbacActionId || mMeta?.id || (cc.getMethod() ?? "");
+	const { resource, action } = arbacIdsFromMeta(cMeta, mMeta, cc.getController(), cc.getMethod() ?? "");
 	const isPublic = mMeta?.arbacPublic || cMeta?.arbacPublic || false;
 	const evaluate = async (opts) => {
 		const effectiveResource = opts?.resource || resource;
 		const effectiveAction = opts?.action || action;
 		if (!effectiveResource) throw new Error("useArbac().evaluate(): `resource` is required — could not be resolved from controller/method metadata. Pass it explicitly.");
 		if (!effectiveAction) throw new Error("useArbac().evaluate(): `action` is required — could not be resolved from controller/method metadata. Pass it explicitly.");
-		const [user, arbac] = await Promise.all([cc.instantiate(ArbacUserProviderToken), cc.instantiate(MoostArbac)]);
-		const userId = await user.getUserId();
-		const att = user.getAttenuation ? await user.getAttenuation() : void 0;
-		const attenuate = att && (att.roles !== void 0 || att.attrs !== void 0) ? {
-			roles: att.roles,
-			attrs: att.attrs
-		} : void 0;
-		const result = await arbac.evaluate({
+		return evaluateArbac(ctx, {
 			resource: effectiveResource,
-			action: effectiveAction
-		}, {
-			id: userId,
-			roles: await user.getRoles(userId),
-			attrs: (id) => user.getAttrs(id),
-			attenuate
+			action: effectiveAction,
+			table: opts?.table
 		});
-		if (result.allowed && result.credScopes !== void 0) return {
-			allowed: true,
-			scopes: conjoinArbacDbScopes(result.scopes ?? [], result.credScopes, fieldChildrenOf(cc.getController()?.readable)),
-			userId
-		};
-		return {
-			allowed: result.allowed,
-			scopes: result.scopes,
-			userId
-		};
 	};
 	const evaluateOrThrow = async (opts) => {
 		const result = await evaluate(opts);
@@ -252,6 +945,18 @@ const useArbac = (_ctx) => {
 function getArbacMate() {
 	return getMoostMate();
 }
+/**
+* Marks a controller whose `prepareRequest` authorizes moost-db's delegated
+* handlers (the ones `getDbEndpoint` tags, e.g. `GET meta/actions/:id`) with
+* ARBAC: a method keyed by this symbol answers whether `method` is such a
+* handler. The authorize interceptor then skips its own evaluation for that
+* handler (the route has no grant of its own). `AsArbacDbController` /
+* `AsArbacDbReadableController` carry it; a controller without it keeps the
+* interceptor's normal (fail-closed) evaluation.
+*
+* @since 0.1.72
+*/
+const ARBAC_DELEGATED_AUTH = Symbol.for("aooth.arbac.delegatedAuth");
 //#endregion
 //#region src/arbac.decorator.ts
 /**
@@ -268,11 +973,12 @@ const arbacAuthorizeInterceptor = Object.assign(defineBeforeInterceptor(async ()
 	const ctx = current();
 	const { setScopes, evaluate, resource, action, isPublic } = useArbac(ctx);
 	if (!action || !resource || isPublic) return;
+	if (delegatesToArbacPrepareRequest(ctx)) return;
 	const logger = useLogger("arbac", ctx);
 	try {
 		const { allowed, scopes, userId } = await evaluate();
 		logger.debug(`[${userId}] ${allowed ? "Authorized" : "Blocked"} "${resource}" : "${action}"`);
-		if (!allowed) throw new HttpError(403, `Insufficient privileges for action "${action}" on resource "${resource}"`);
+		if (!allowed) throw insufficientPrivileges(resource, action);
 		setScopes(scopes);
 	} catch (error) {
 		if (error instanceof HttpError) throw error;
@@ -280,6 +986,13 @@ const arbacAuthorizeInterceptor = Object.assign(defineBeforeInterceptor(async ()
 		throw new HttpError(401, error instanceof Error ? error.message : String(error));
 	}
 }, TInterceptorPriority.GUARD), { __authTransports: {} });
+function delegatesToArbacPrepareRequest(ctx) {
+	const cc = useControllerContext(ctx);
+	const controller = cc.getController();
+	const method = cc.getMethod();
+	const check = controller?.[ARBAC_DELEGATED_AUTH];
+	return typeof method === "string" && typeof check === "function" && check.call(controller, method);
+}
 /** Wrapped via `Authenticate` so `@moostjs/swagger` picks up the auth-guard metadata. */
 const ArbacAuthorize = () => Authenticate(arbacAuthorizeInterceptor);
 /**
@@ -295,69 +1008,19 @@ const ArbacAction = (name) => getArbacMate().decorate("arbacActionId", name);
 //#endregion
 //#region src/db/meta-projection.ts
 /**
-* Union the per-scope `projection` whitelists into the single access-control
-* projection used for FIELD-EXISTENCE decisions (`hasField` parity + `/meta`
-* pruning). Returns `undefined` when the union imposes no restriction — no
-* scopes at all, or any scope without a `projection` (a universal grant makes
-* `unionProjections` collapse to the universe `{}`).
-*/
-function unionScopeProjection(scopes) {
-	if (scopes.length === 0) return void 0;
-	const allowed = unionProjections(...scopes.map((s) => s.projection ?? {}));
-	return Object.keys(allowed).length === 0 ? void 0 : allowed;
-}
-/**
-* Relation names any scope explicitly grants via `with.<name>` — an explicit
-* content grant implies the relation EXISTS for this principal even when the
-* projection union does not name it (the sub-scope, not the projection, owns
-* the joined rows' policy — see {@link ArbacDbScope.with}).
-*/
-function collectWithGrantNames(scopes) {
-	const out = /* @__PURE__ */ new Set();
-	for (const s of scopes) if (s.with) for (const name of Object.keys(s.with)) out.add(name);
-	return out;
-}
-/** Exact-or-ancestor membership: `credit.credentials.user` matches a `credit.credentials` grant. */
-function isPathWritable(path, writable) {
-	if (!writable) return false;
-	return writable === "all" || hasSelfOrAncestor(writable, path);
-}
-/**
-* Union of write-scope `allowedFields`; `"all"` for field-unrestricted write
-* access. Mirrors `prepareScopeOverlay`: the whitelist exists only when at
-* least one scope carries an `allowedFields` array — scoped-but-unlisted
-* writes are field-unrestricted.
-*/
-function collectWritableFields(scopes, unrestricted) {
-	if (unrestricted) return "all";
-	if (scopes.length === 0) return void 0;
-	const out = /* @__PURE__ */ new Set();
-	let sawWhitelist = false;
-	for (const s of scopes) if (Array.isArray(s.allowedFields)) {
-		sawWhitelist = true;
-		for (const f of s.allowedFields) out.add(f);
-	}
-	if (!sawWhitelist) return "all";
-	return out.size > 0 ? out : void 0;
-}
-/**
-* Whether a flattened dot-path field exists for this principal. A
-* `with`-granted relation itself is always visible (the grant implies it);
-* a path UNDER it (`rel.x.y`) is checked as `x.y` against the relation's
-* sub-scope visibility ({@link MetaVisibility.relation}) — so a field the
-* sub-scope hides is as unknown in a `$with` sub-query as a top-level hidden
-* column is in the main query (no filter/sort value oracle).
+* Exact-or-ancestor membership in the write whitelist: `credit.credentials.user`
+* matches a `credit.credentials` grant. A path through a nav relation is
+* writable only when the relation is opted into nested writes
+* ({@link MetaVisibility.nestedWrites}); a `@db.column.derived` field never is
+* (its payload value is dropped).
 */
-function isMetaFieldVisible(path, vis) {
-	if (vis.alwaysVisible.has(path)) return true;
+function isPathWritable(path, vis) {
+	const writable = vis.writable;
+	if (!writable || tablePolicy(vis.table).derived.has(path)) return false;
 	const dot = path.indexOf(".");
 	const head = dot === -1 ? path : path.slice(0, dot);
-	if (vis.withGrants.has(head)) {
-		if (dot === -1) return true;
-		const sub = vis.relation?.(head);
-		return sub ? isMetaFieldVisible(path.slice(dot + 1), sub) : true;
-	}
-	return vis.isAllowed ? vis.isAllowed(path) : isFieldAllowed(path, vis.allowed);
+	if ((vis.relationNames?.has(head) || vis.table?.navFields?.has(head)) && !vis.nestedWrites?.has(head)) return false;
+	return writable === "all" || hasSelfOrAncestor(writable, path);
 }
 /**
 * Prune a `/meta` envelope down to the fields the principal's read scopes can
@@ -367,19 +1030,21 @@ function isMetaFieldVisible(path, vis) {
 *
 * - `fields` — the flat capability map (sortable/filterable flags).
 * - `type` — the serialized annotated type (what dynamic clients build
-*   tables/forms from); nested object props prune by dot-path. A relation
-*   prop visible through the projection survives whole; a `with`-granted
-*   one is pruned by its sub-scope (recursively), matching `hasField`.
-* - `relations` — entries neither projected nor `with`-granted.
+*   tables/forms from); nested object props prune by dot-path. A visible
+*   relation's nav prop is pruned by that relation's visibility (declared
+*   sub-scope or the caller's own grant on the target), recursively. A
+*   `ref` whose target field is hidden (own table) or whose target table the
+*   caller cannot read (`refTargets`) is stripped.
+* - `relations` — hidden relations dropped.
 * - `versionColumn` — dropped when the OCC column itself is hidden.
 *
 * NEVER mutates the input — the base controller caches the static envelope
 * (`applyMetaOverlay` contract); every pruned branch is a fresh object.
 */
-function pruneMetaByVisibility(meta, vis) {
+function pruneMetaByVisibility(meta, vis, refTargets) {
 	const fields = {};
 	for (const [path, fieldMeta] of Object.entries(meta.fields)) if (isMetaFieldVisible(path, vis)) fields[path] = fieldMeta;
-	else if (isPathWritable(path, vis.writable)) fields[path] = {
+	else if (isPathWritable(path, vis)) fields[path] = {
 		...fieldMeta,
 		writeOnly: true,
 		filterable: false,
@@ -391,44 +1056,48 @@ function pruneMetaByVisibility(meta, vis) {
 		...meta,
 		fields,
 		relations,
-		type: pruneSerializedType(meta.type, "", vis, relationNames)
+		type: pruneSerializedType(meta.type, {
+			basePath: "",
+			vis,
+			relationNames,
+			refTargets
+		})
 	};
 	if (out.versionColumn !== void 0 && !isMetaFieldVisible(out.versionColumn, vis)) delete out.versionColumn;
 	return out;
 }
-/**
-* Copy-on-prune walk over a serialized type node. `basePath` is the flattened
-* dot-path prefix ("" at the root). Relation props (nav props named in
-* `meta.relations` at the root, or carrying a `db.rel.*` annotation inside a
-* joined type) are dropped when invisible; a `with`-granted one is pruned by
-* its sub-scope visibility (the same one `hasField` checks `rel.x` paths
-* against), any other visible one survives whole. Own-field subtrees prune
-* recursively so an include-mode union like `{ "password.hash": 1 }` keeps
-* `password` with only `hash` inside.
-*/
-function pruneSerializedType(node, basePath, vis, relationNames) {
+function pruneSerializedType(node, level) {
+	const { basePath, vis, relationNames, refTargets } = level;
 	const def = node.type;
 	if (def.kind === "object") {
 		const props = {};
 		for (const [name, prop] of Object.entries(def.props)) {
 			const path = basePath ? `${basePath}.${name}` : name;
 			if (basePath === "" && (relationNames.has(name) || isNavProp(prop))) {
-				if (!isMetaFieldVisible(name, vis)) continue;
-				const sub = vis.withGrants.has(name) ? vis.relation?.(name) : void 0;
-				props[name] = sub ? pruneSerializedType(prop, "", sub, NO_NAMES) : prop;
+				if (!isMetaFieldVisible(name, vis)) {
+					if (vis.nestedWrites?.has(name) && isPathWritable(name, vis)) props[name] = stampWriteOnly(prop);
+					continue;
+				}
+				const sub = vis.relation?.(name);
+				props[name] = sub ? pruneSerializedType(prop, {
+					basePath: "",
+					vis: sub,
+					relationNames: sub.relationNames ?? NO_NAMES,
+					refTargets
+				}) : prop;
 				continue;
 			}
+			const child = {
+				...level,
+				basePath: path
+			};
 			if (!isMetaFieldVisible(path, vis)) {
-				if (isPathWritable(path, vis.writable)) props[name] = {
-					...prop,
-					metadata: {
-						...prop.metadata,
-						"db.writeOnly": true
-					}
-				};
+				if (isPathWritable(path, vis)) props[name] = stampWriteOnly(prop);
+				else if (hasWritableDescendant(path, vis.writable)) props[name] = stampWriteOnly(pruneSerializedType(prop, child));
 				continue;
 			}
-			props[name] = pruneSerializedType(prop, path, vis, relationNames);
+			const pruned = pruneSerializedType(prop, child);
+			props[name] = pruned.ref && !isRefVisible(path, vis, refTargets) ? withoutRef(pruned) : pruned;
 		}
 		return {
 			...node,
@@ -442,304 +1111,580 @@ function pruneSerializedType(node, basePath, vis, relationNames) {
 		...node,
 		type: {
 			...def,
-			of: pruneSerializedType(def.of, basePath, vis, relationNames)
+			of: pruneSerializedType(def.of, level)
 		}
 	};
 	if (def.kind === "union" || def.kind === "intersection" || def.kind === "tuple") return {
 		...node,
 		type: {
 			...def,
-			items: def.items.map((item) => pruneSerializedType(item, basePath, vis, relationNames))
+			items: def.items.map((item) => pruneSerializedType(item, level))
 		}
 	};
 	return node;
 }
+function stampWriteOnly(node) {
+	return {
+		...node,
+		metadata: {
+			...node.metadata,
+			"db.writeOnly": true
+		}
+	};
+}
+/** A strict descendant of `path` is in the write whitelist. */
+function hasWritableDescendant(path, writable) {
+	if (!writable || writable === "all") return false;
+	const prefix = `${path}.`;
+	for (const f of writable) if (f.startsWith(prefix)) return true;
+	return false;
+}
+function withoutRef(node) {
+	const { ref: _ref, ...rest } = node;
+	return rest;
+}
+/** The field a runtime prop's `ref` finally points at (the same terminal `/meta` serializes). */
+function refTargetOf(entry) {
+	const def = entry;
+	if (!def?.ref) return void 0;
+	const terminal = resolveTerminalRef(def);
+	if (terminal) return terminal;
+	try {
+		return {
+			type: def.ref.type(),
+			field: def.ref.field
+		};
+	} catch {
+		return;
+	}
+}
+/**
+* A serialized `ref` at `path` survives when its target field is visible:
+* a self-reference (e.g. a derived column's source) against this level's
+* visibility; a foreign one against the caller's visibility on the target
+* table (`refTargets`, stripped when the caller cannot read it). Without
+* runtime schema info (`vis.table.flatMap`) or `refTargets`, refs are kept.
+*/
+function isRefVisible(path, vis, refTargets) {
+	const table = vis.table;
+	if (!table?.flatMap || !refTargets) return true;
+	const target = refTargetOf(table.flatMap.get(path));
+	if (!target || !target.field) return true;
+	if (target.type === table.type) return isMetaFieldVisible(target.field, vis);
+	const targetVis = refTargets.get(target.type);
+	return !!targetVis && isMetaFieldVisible(target.field, targetVis);
+}
 const NO_NAMES = /* @__PURE__ */ new Set();
 /** A nav prop inside a joined type: atscript-db stamps `db.rel.to` / `from` / `via`. */
 function isNavProp(prop) {
 	const meta = prop.metadata;
 	return !!meta && ("db.rel.to" in meta || "db.rel.from" in meta || "db.rel.via" in meta);
 }
-const identifierSetCache = /* @__PURE__ */ new WeakMap();
-/** PK + `preferredId` of a table — the identifiers reads always return. */
-function identifierSet(table) {
-	if (!table) return NO_NAMES;
-	let set = identifierSetCache.get(table);
-	if (!set) {
-		set = /* @__PURE__ */ new Set([...table.primaryKeys, ...table.preferredId]);
-		identifierSetCache.set(table, set);
+/**
+* The write CRUD ops. Everything else in `meta.crud` is row-returning read
+* surface whose scopes govern field VISIBILITY in `/meta` — classified by
+* complement so a read op added upstream defaults to READ and the pruning
+* fails closed (a principal whose only read grant is the new op still gets
+* a pruned envelope rather than the full field map).
+*/
+const WRITE_CRUD_OPS = /* @__PURE__ */ new Set([
+	"insert",
+	"update",
+	"replace",
+	"remove"
+]);
+/**
+* The handler methods serving a `/meta` crud op on this controller (a DB or
+* value-help controller — moost-db's handler maps); an op is allowed when
+* ANY of them is. An op no map lists is its own method name.
+*/
+function crudHandlers(op, methods) {
+	const found = [...DB_CRUD_HANDLERS[op] ?? [], ...VALUE_HELP_CRUD_HANDLERS[op] ?? []].filter((m) => methods.has(m));
+	return found.length > 0 ? found : [op];
+}
+/**
+* The full ARBAC `/meta` overlay, shared by the ARBAC DB and value-help
+* controllers.
+*
+* 1. `actions` and `crud` are filtered by evaluating each one exactly as its
+*    handler is authorized (`useArbac` precedence): a crud op through its
+*    handler method(s) — `one` via `getOne` / `getOneComposite`, `remove`
+*    via `remove` / `removeComposite` (allowed when any is) — and an action
+*    through its method (`@ArbacAction` → `@DbAction` name → …).
+* 2. The FIELD surface (`fields`, serialized `type`, `relations`,
+*    `versionColumn`) is pruned by the read scopes' visibility: the
+*    projection union, derived-column sources, atomic JSON columns, and the
+*    `$with` relation policy (declared `with` sub-scopes, else the caller's
+*    own grant on the related table — no grant → relation and nav type
+*    dropped). `ref`s to hidden targets are stripped. An allowed read op
+*    without scopes is an unscoped grant (no field restriction; relations
+*    still follow the relation policy). No read op allowed → no pruning:
+*    `crud` already advertises no read surface, and write-only principals
+*    still need `type` for their insert/update forms. PK + `preferredId` are
+*    never pruned.
+* 3. The search surface: `searchIndexes` reading a hidden field are dropped,
+*    `searchable` / `vectorSearchable` / `geoSearchable` recomputed, and the
+*    `query` / `pages` control lists lose the controls that became unusable
+*    (`crud.geo` goes when no geo index is left).
+*
+* @param source - the controller's `this.readable` (identifiers, relations
+*   and schema rules are derived from it); an identifier set (the 0.1.67
+*   signature) still works, without them
+* @param indexes - the controller's `indexFieldPaths()`; defaults to calling
+*   it on the current controller when it has one
+*/
+async function applyArbacMetaOverlay(meta, source, indexes) {
+	const instance = useControllerContext().getController();
+	const { methods } = controllerMethodIndex(instance);
+	const crudKeys = Object.keys(meta.crud);
+	const [allowedActions, crudScopes] = await Promise.all([grantedActions(instance, meta.actions.map((entry) => entry.name)), Promise.all(crudKeys.map((op) => evaluateHandlers(crudHandlers(op, methods).map((m) => resolveHandlerArbacIds(instance, m)))))]);
+	const allowed = new Set(allowedActions);
+	const actions = meta.actions.filter((entry) => allowed.has(entry.name));
+	const crud = {};
+	const readScopes = [];
+	const writeScopes = [];
+	for (let i = 0; i < crudKeys.length; i++) {
+		const scopes = crudScopes[i];
+		if (!scopes) continue;
+		crud[crudKeys[i]] = meta.crud[crudKeys[i]];
+		(WRITE_CRUD_OPS.has(crudKeys[i]) ? writeScopes : readScopes).push(...scopes);
+	}
+	const overlaid = {
+		...meta,
+		actions,
+		crud
+	};
+	if (readScopes.length === 0) return overlaid;
+	const writable = collectWritableFields(writeScopes, false);
+	const nestedWrites = effectiveScope(writeScopes).nestedWrites;
+	if (isIdentifierSet(source)) {
+		const vis = buildScopeVisibility(readScopes, void 0, source);
+		return Object.keys(vis.allowed).length > 0 || vis.withGrants.size > 0 ? pruneMetaByVisibility(overlaid, {
+			...vis,
+			writable,
+			nestedWrites
+		}) : overlaid;
 	}
-	return set;
+	const vis = buildScopeVisibility(readScopes, source, { relations: await resolveRelationTree(readScopes, source, metaRelationNames(meta), { listSiblings: false }) });
+	const refTargets = await resolveRefTargets(vis, meta);
+	return pruneSearchSurface(pruneMetaByVisibility(overlaid, {
+		...vis,
+		writable,
+		nestedWrites
+	}, refTargets), meta, vis, indexes ?? controllerIndexes(instance));
 }
-/** Pick `scopes[i].with?.[name]`, dropping undefined (silence wins when empty). */
-function collectSubScopes(scopes, name) {
-	const out = [];
-	for (const s of scopes) {
-		const sub = s.with?.[name];
-		if (sub) out.push(sub);
+const metaNamesCache = /* @__PURE__ */ new WeakMap();
+/** The relation names `/meta`'s serialized type reaches: root relations, then nav props of each nav body. */
+function metaRelationNames(meta) {
+	return getOrCreate(metaNamesCache, meta, () => buildMetaRelationNames(meta));
+}
+function buildMetaRelationNames(meta) {
+	const tree = /* @__PURE__ */ new Map();
+	const rootProps = objectProps(meta.type);
+	for (const r of meta.relations) {
+		const nested = /* @__PURE__ */ new Map();
+		tree.set(r.name, nested);
+		const prop = rootProps?.[r.name];
+		if (prop) collectNavNames(prop, nested, 0);
+	}
+	return tree;
+}
+/** Nested-relation walk bound — serialized nav bodies are finite, this only guards pathological input. */
+const MAX_NAV_DEPTH = 8;
+function collectNavNames(node, into, depth) {
+	if (depth >= MAX_NAV_DEPTH) return;
+	const props = objectProps(node);
+	if (!props) return;
+	for (const [name, prop] of Object.entries(props)) {
+		if (!isNavProp(prop)) continue;
+		collectNavNames(prop, getOrCreate(into, name, () => /* @__PURE__ */ new Map()), depth + 1);
 	}
+}
+/** The props of an object node (through arrays). */
+function objectProps(node) {
+	const def = node.type;
+	if (def.kind === "object") return def.props;
+	if (def.kind === "array") return objectProps(def.of);
+}
+/**
+* Foreign `ref` targets of every level the pruned `/meta` shows (the root
+* table and each visible relation's table): the caller's visibility on each
+* target table, or `null` when they cannot read it.
+*/
+async function resolveRefTargets(root, meta) {
+	const types = /* @__PURE__ */ new Set();
+	const visit = (vis, node, depth) => {
+		if (vis.table) for (const type of foreignRefTypes(vis.table)) types.add(type);
+		const props = objectProps(node);
+		if (!props || depth >= MAX_NAV_DEPTH) return;
+		for (const name of /* @__PURE__ */ new Set([...vis.relationNames ?? NO_NAMES, ...vis.withGrants])) {
+			const prop = props[name];
+			if (!prop || !isMetaFieldVisible(name, vis)) continue;
+			const sub = vis.relation?.(name);
+			if (sub) visit(sub, prop, depth + 1);
+		}
+	};
+	visit(root, meta.type, 0);
+	const out = /* @__PURE__ */ new Map();
+	await Promise.all([...types].map(async (type) => {
+		const read = await evaluateTypeRead(type);
+		out.set(type, read ? buildScopeVisibility(read.scopes, read.table) : null);
+	}));
 	return out;
 }
-/** `path` or one of its ancestors is in `set`. */
-function hasSelfOrAncestor(set, path) {
-	return set.has(path) || findAncestorInSet(path, set) !== void 0;
+const refTypesCache = /* @__PURE__ */ new WeakMap();
+function foreignRefTypes(table) {
+	const flatMap = table.flatMap;
+	if (!flatMap) return NO_TYPES;
+	return getOrCreate(refTypesCache, table, () => {
+		const nav = navFieldsOf(table);
+		const out = /* @__PURE__ */ new Set();
+		for (const [path, entry] of flatMap) {
+			if (hasSelfOrAncestor(nav, path)) continue;
+			const target = refTargetOf(entry);
+			if (target && target.type !== table.type) out.add(target.type);
+		}
+		return out;
+	});
 }
+const NO_TYPES = /* @__PURE__ */ new Set();
+/** Controls a text / vector search needs, dropped from `crud.query` / `crud.pages` when unusable. */
+const TEXT_SEARCH_CONTROLS = ["search", "fuzzy"];
+const VECTOR_CONTROLS = ["vector", "threshold"];
 /**
-* Precompiled {@link isFieldAllowed} for one projection: `hasField` asks it
-* for every referenced path, so the mode and key sets are computed once.
-* Inclusion: the path, an ancestor, or a descendant is listed. Exclusion: no
-* listed key is the path or an ancestor.
+* Drop `searchIndexes` reading a hidden field, recompute the search /
+* vector / geo flags over what is left (native search, or the visible
+* `@db.column.searchable` fallback), and remove the controls that became
+* unusable from the `query` / `pages` control lists (`crud.geo` goes with
+* the last visible geo index).
 */
-function compileProjection(projection) {
-	const keys = Object.keys(projection);
-	if (keys.length === 0) return () => true;
-	const listed = new Set(keys);
-	if (getProjectionMode(projection) === "exclude") return (path) => !hasSelfOrAncestor(listed, path);
-	const parents = /* @__PURE__ */ new Set();
-	for (const key of keys) {
-		let pos = key.length;
-		while ((pos = key.lastIndexOf(".", pos - 1)) !== -1) parents.add(key.slice(0, pos));
+function pruneSearchSurface(meta, original, vis, indexes) {
+	if (!indexes) return meta;
+	const shown = indexes.filter((e) => e.fields.every((f) => isMetaFieldVisible(f, vis)));
+	const shownOf = (type) => shown.some((e) => e.type === type);
+	const hasText = indexes.some((e) => e.type === "text");
+	const native = vis.table?.isSearchable?.() ?? hasText;
+	const fallback = searchFallbackVisible(meta, vis.table);
+	const searchable = original.searchable && (native && (!hasText || shownOf("text")) || fallback);
+	const vectorSearchable = original.vectorSearchable && shownOf("vector");
+	const geoSearchable = original.geoSearchable === true ? shownOf("geo") : original.geoSearchable;
+	const out = {
+		...meta,
+		searchIndexes: original.searchIndexes.filter((info) => shown.some((e) => e.name === info.name && e.type === (info.type ?? "text"))),
+		searchable,
+		vectorSearchable
+	};
+	if (geoSearchable !== void 0) out.geoSearchable = geoSearchable;
+	const drop = /* @__PURE__ */ new Set();
+	if (original.searchable && !searchable && !vectorSearchable) for (const c of TEXT_SEARCH_CONTROLS) drop.add(c);
+	if (original.vectorSearchable && !vectorSearchable) for (const c of VECTOR_CONTROLS) drop.add(c);
+	if (hasText && !shownOf("text")) drop.add("index");
+	if (drop.size > 0 || original.geoSearchable && !geoSearchable) {
+		const crud = { ...meta.crud };
+		for (const op of ["query", "pages"]) {
+			const list = crud[op];
+			if (list && drop.size > 0) crud[op] = list.filter((c) => !drop.has(c));
+		}
+		if (original.geoSearchable && !geoSearchable) delete crud.geo;
+		out.crud = crud;
 	}
-	return (path) => parents.has(path) || hasSelfOrAncestor(listed, path);
+	return out;
+}
+/** A `@db.column.searchable` field is still listed (visible) in the pruned `fields`. */
+function searchFallbackVisible(meta, table) {
+	if (!table?.flatMap) return false;
+	for (const path of Object.keys(meta.fields)) if (table.flatMap.get(path)?.metadata?.has?.("db.column.searchable") && !meta.fields[path].writeOnly) return true;
+	return false;
 }
+/** The current controller's `indexFieldPaths()` (moost-db 0.1.143 DB readables), if it has one. */
+function controllerIndexes(instance) {
+	const c = instance;
+	return typeof c.indexFieldPaths === "function" ? c.indexFieldPaths() : void 0;
+}
+const methodIndexCache = /* @__PURE__ */ new WeakMap();
 /**
-* Build the {@link MetaVisibility} a set of read scopes implies — the single
-* structure behind `hasField`, `/meta` pruning, `$select` value stripping
-* and the `$with` overlay, so they cannot drift. Own fields: the projection
-* union (`{}` when unrestricted), precompiled into `isAllowed`. A
-* `with`-granted relation: a lazily built (memoized) child visibility over
-* the union of its `with.<name>` sub-scopes — the same sub-scopes joined rows
-* are stripped with — whose `alwaysVisible` is the related table's own PK /
-* `preferredId` (reached through `table.relatedTable`; without it, no
-* related identifier is exempt).
+* THE ARBAC ids an action is authorized as — used by the `/meta` overlay,
+* `authorizeForm`, `GET meta/actions` and `actionRowScope` alike: every
+* method declaring the `@DbAction` (allowed when ANY is — a union), each
+* with `useArbac()` precedence; a class-level `@DbActions` entry (no handler
+* method) → `{ resource: defaultResource, action: name }`. `defaultResource`
+* defaults to the controller's class-level resource.
 *
-* @param alwaysVisible - identifiers exempt from the projection; defaults to
-*   the table's PK + `preferredId`
+* @since 0.1.72
 */
-function buildScopeVisibility(scopes, table, alwaysVisible = identifierSet(table)) {
-	const withGrants = collectWithGrantNames(scopes);
-	const allowed = unionScopeProjection(scopes) ?? {};
-	const children = /* @__PURE__ */ new Map();
-	return {
-		allowed,
-		alwaysVisible,
-		withGrants,
-		scopes,
-		table,
-		isAllowed: compileProjection(allowed),
-		relation(name) {
-			if (!withGrants.has(name)) return void 0;
-			let child = children.get(name);
-			if (!child) {
-				child = buildScopeVisibility(collectSubScopes(scopes, name), table?.relatedTable?.(name));
-				children.set(name, child);
-			}
-			return child;
-		}
-	};
+function actionArbacIds(instance, name, defaultResource = controllerArbacResource(instance)) {
+	const methods = controllerMethodIndex(instance).actionMethods.get(name);
+	return methods?.length ? methods.map((m) => resolveHandlerArbacIds(instance, m)) : [{
+		resource: defaultResource,
+		action: name
+	}];
 }
-const scopeVisibilityCache = /* @__PURE__ */ new WeakMap();
-const NO_TABLE = {
-	primaryKeys: [],
-	preferredId: []
-};
-/** `source` is an identifier set (the 0.1.67 signatures), not a readable. */
-function isIdentifierSet(source) {
-	return !("primaryKeys" in source);
+/**
+* The action `names` the caller holds a grant on — each evaluated as
+* {@link actionArbacIds} names it (memoized per event). THE action rule of
+* the `/meta` overlay, `allowedActions` (`$actions`, `GET meta/actions`).
+*/
+async function grantedActions(instance, names) {
+	const granted = await Promise.all(names.map((name) => evaluateHandlers(actionArbacIds(instance, name))));
+	return names.filter((_, i) => granted[i] !== void 0);
+}
+/** The controller's class-level ARBAC resource (`@ArbacResource` → controller id → class name). */
+function controllerArbacResource(instance) {
+	return arbacIdsFromMeta(getMoostMate().read(instance), void 0, instance, "").resource;
+}
+/** A controller class's methods and `@DbAction` name → methods map (memoized per class). */
+function controllerMethodIndex(instance) {
+	return getOrCreate(methodIndexCache, getConstructor(instance), () => {
+		const cc = useControllerContext();
+		const methods = new Set(collectMethodNames(instance));
+		const actionMethods = /* @__PURE__ */ new Map();
+		for (const methodName of methods) {
+			const name = cc.getMethodMeta(methodName)?.atscript_db_action?.name;
+			if (name) getOrCreate(actionMethods, name, () => []).push(methodName);
+		}
+		return {
+			actionMethods,
+			methods
+		};
+	});
 }
 /**
-* The event-cached {@link MetaVisibility} for `scopes` over `source` (a
-* readable, or an `alwaysVisible` identifier set).
+* Test-friendly internal helper — exported for unit tests and helper
+* composition; regular consumers should not call this directly.
+*
+* Method names of an instance, walking the full prototype chain via property
+* DESCRIPTORS. Deliberately NOT moost's `getInstanceOwnMethods`: that helper
+* evaluates `instance[name]` for every property to test "is it a function",
+* which fires accessors — and moost-db's inherited `.table` getter THROWS for
+* view-bound controllers, turning every `/meta` request into a 500. Accessor
+* properties are skipped entirely (a getter-valued property is not a method
+* and can never carry `@DbAction` metadata).
 */
-function scopeVisibility(scopes, source = NO_TABLE) {
-	let perSource = scopeVisibilityCache.get(scopes);
-	if (!perSource) {
-		perSource = /* @__PURE__ */ new WeakMap();
-		scopeVisibilityCache.set(scopes, perSource);
-	}
-	let vis = perSource.get(source);
-	if (!vis) {
-		vis = isIdentifierSet(source) ? buildScopeVisibility(scopes, void 0, source) : buildScopeVisibility(scopes, source === NO_TABLE ? void 0 : source);
-		perSource.set(source, vis);
+function collectMethodNames(instance) {
+	const names = /* @__PURE__ */ new Set();
+	let obj = instance;
+	while (obj && obj !== Object.prototype) {
+		for (const name of Object.getOwnPropertyNames(obj)) {
+			if (name === "constructor") continue;
+			const desc = Object.getOwnPropertyDescriptor(obj, name);
+			if (desc && typeof desc.value === "function") names.add(name);
+		}
+		obj = Object.getPrototypeOf(obj);
 	}
-	return vis;
+	return [...names];
+}
+//#endregion
+//#region src/db/request-scopes.ts
+/** Endpoints whose `prepareRequest` carries parsed Uniquery controls. */
+const READ_ENDPOINTS = /* @__PURE__ */ new Set([
+	"query",
+	"pages",
+	"geo",
+	"one"
+]);
+const requestScopesKey = key("arbac.db.scopes");
+/** Store the event's resolved scopes (for the handler `ids` resolves to). */
+function storeResolved(ctx, ids, source, scopes) {
+	ctx.set(requestScopesKey, {
+		resource: ids.resource,
+		action: ids.action,
+		source,
+		scopes,
+		visibility: /* @__PURE__ */ new Map()
+	});
+}
+function resolved() {
+	const ctx = tryGetCurrent();
+	return ctx?.has(requestScopesKey) ? ctx.get(requestScopesKey) : void 0;
+}
+/**
+* The scopes resolved for the current event, or `undefined` before
+* {@link resolveRequestScopes} ran.
+*
+* @since 0.1.72
+*/
+function cachedRequestScopes() {
+	return resolved()?.scopes;
+}
+/**
+* Resolve the current event's scopes once: the ones the authorize
+* interceptor cached, else an ARBAC evaluation of the handler's
+* resource/action. The empty-scope rule (`normalizeScopes` from
+* `@aooth/arbac`): an allowed grant without scopes is unrestricted (`[{}]`),
+* a scope predicate returning nothing contributes nothing, and an allowed
+* evaluation left with NO scope is a deny. A deny throws 403.
+*
+* @since 0.1.72
+*/
+async function resolveRequestScopes() {
+	const ctx = current();
+	const arbac = useArbac(ctx);
+	const fromInterceptor = arbac.getScopes();
+	const prior = resolved();
+	if (prior && prior.resource === arbac.resource && prior.action === arbac.action && prior.source === fromInterceptor) return prior.scopes;
+	const scopes = normalizeScopes(fromInterceptor !== void 0 ? {
+		allowed: true,
+		scopes: fromInterceptor
+	} : await evaluateArbacCached(arbac.resource, arbac.action));
+	if (!scopes) throw insufficientPrivileges(arbac.resource, arbac.action);
+	if (fromInterceptor === void 0) arbac.setScopes(scopes);
+	storeResolved(ctx, arbac, fromInterceptor ?? scopes, scopes);
+	return scopes;
 }
 /**
-* Shared body of both ARBAC controllers' `hasField` overrides (BUG-3 twin of
-* the `/meta` pruning): a field outside the read-scope projection union —
-* or, for a `rel.x` path under a `with`-granted relation, outside that
-* relation's sub-scope union — must be indistinguishable from a field that
-* does not exist. Returns `true` when there are no scopes (unscoped grant).
+* The resolved scopes, synchronously — for the hooks that run after the
+* entry point (`validateControls`, `transformFilter`, the write guards …).
+* Unresolved scopes are a 403, never "unrestricted".
+*
+* @since 0.1.72
+*/
+function requireRequestScopes() {
+	const scopes = cachedRequestScopes();
+	if (scopes) return scopes;
+	const { resource, action } = useArbac();
+	throw insufficientPrivileges(resource, action);
+}
+/**
+* The visibility `scopes` imply over `source`: the current request's scopes
+* over a readable carry the request's `$with` resolution; any other pair is
+* built without one (undeclared relations hidden).
+*/
+function visibilityFor(scopes, source) {
+	const request = resolved();
+	if (source && !isIdentifierSet(source) && request?.scopes === scopes) return getOrCreate(request.visibility, source, () => buildScopeVisibility(scopes, source, { relations: requestRelations() }));
+	return scopeVisibility(scopes, source);
+}
+/**
+* Shared body of the ARBAC controllers' `hasField` overrides: a field
+* outside the read-scope visibility — hidden by the projection union, a
+* derived field whose source is hidden, a path inside a hidden atomic JSON
+* column, a hidden relation, or a `rel.x` path the relation's policy hides —
+* is indistinguishable from a field that does not exist. Unresolved scopes
+* hide every field.
+*
+* @since 0.1.72
+*/
+function requestFieldVisible(path, source) {
+	const scopes = cachedRequestScopes();
+	return scopes !== void 0 && isMetaFieldVisible(path, visibilityFor(scopes, source));
+}
+/**
+* Whether `path` is visible to `scopes` over `source` (see
+* {@link requestFieldVisible}, which reads the request's scopes).
 *
 * @param source - the controller's `this.readable`; an identifier set (the
-*   0.1.67 signature) still works, without related-table identifiers
+*   0.1.67 signature) still works, without relation / schema rules
 */
 function isScopedFieldVisible(scopes, path, source) {
-	if (scopes.length === 0) return true;
-	return isMetaFieldVisible(path, scopeVisibility(scopes, source));
+	if (scopes.length === 0 && isIdentifierSet(source)) return true;
+	return isMetaFieldVisible(path, visibilityFor(scopes, source));
 }
 /**
-* PK + `preferredId` for a controller's table/readable — the
-* {@link MetaVisibility.alwaysVisible} set. Kept for compatibility: the
-* controllers now pass `this.readable` and it is derived there.
+* Body of the ARBAC DB / value-help controllers' `prepareRequest` — every
+* endpoint, `@DbAction` handlers included (`endpoint: "action"`, before any
+* action id / row is read): resolve the request's scopes
+* ({@link resolveRequestScopes} — 403 on denial, `arbacPublic` does not
+* bypass) and, on read endpoints, the `$with` relation policy for the
+* requested relations.
+*
+* @since 0.1.72
 */
-function metaAlwaysVisibleFields(_controller, source) {
-	return identifierSet(source);
+async function prepareArbacRequest(ctx, readable) {
+	if (ctx.endpoint === "availableActions") {
+		await authorizeAvailableActions();
+		return;
+	}
+	const scopes = await resolveRequestScopes();
+	if (ctx.controls && READ_ENDPOINTS.has(ctx.endpoint)) await resolveRequestRelations(scopes, ctx.controls, readable);
 }
 /**
-* The write CRUD ops. Everything else in `meta.crud` is row-returning read
-* surface whose scopes govern field VISIBILITY in `/meta` — classified by
-* complement so a read op added upstream defaults to READ and the pruning
-* fails closed (a principal whose only read grant is the new op still gets
-* a pruned envelope rather than the full field map).
+* `authorizeForm` for the ARBAC DB controllers: a form is served iff the
+* caller may run at least one of the actions that take it as input — each
+* evaluated as the resource/action its handler is authorized as.
+*
+* @since 0.1.72
 */
-const WRITE_CRUD_OPS = /* @__PURE__ */ new Set([
-	"insert",
-	"update",
-	"replace",
-	"remove"
-]);
+async function authorizeArbacForm(actionNames) {
+	return await evaluateHandlers(actionsIds(actionNames)) !== void 0;
+}
+/** The ARBAC ids of `names` on the current controller ({@link actionArbacIds}). */
+function actionsIds(names) {
+	const instance = useControllerContext().getController();
+	return names.flatMap((name) => actionArbacIds(instance, name));
+}
 /**
-* The full ARBAC `/meta` overlay, shared by `AsArbacDbController` and
-* `AsArbacDbReadableController`: filter `actions` + `crud` by per-action
-* evaluation, then prune the FIELD surface (`fields`, serialized `type`,
-* `relations`, `versionColumn`) by the read scopes' projection union.
-*
-* Field pruning (BUG-3): a scope projection must remove fields from the META
-* entirely — `transformProjection` already strips their VALUES from every
-* read, but the envelope still advertised the full field map, so a scoped UI
-* offered columns that could never populate, and secret-bearing column NAMES
-* leaked. The pruning union comes from the read-op evaluations already
-* computed for the `crud` overlay (same `unionProjections` the read path
-* applies). An allowed read op WITHOUT scopes is an unscoped grant —
-* universe, no pruning (unchanged behavior for unscoped roles). No read op
-* allowed → the projection union is empty → no pruning: `crud` already
-* advertises no read surface, and write-only principals still need `type`
-* for their insert/update forms. PK + `preferredId` are never pruned —
-* reads always return those fields (projection widening / id addressing).
-*
-* @param source - the controller's `this.readable` (identifiers and related
-*   tables are derived from it); an identifier set (the 0.1.67 signature)
-*   still works, without related-table identifiers
+* `GET /meta/actions/:id` (endpoint `"availableActions"`): served iff the
+* caller may run at least ONE row-level action of the controller (else 403).
+* The route has no grant of its own and needs no read grant. Its request
+* scopes are the granted row-level actions' scopes WITHOUT their row parts
+* (`filter` / `check`, which carry any custom-field row filter): the row
+* overlay stays unrestricted — each action's rows come from
+* `actionRowScope` ({@link arbacActionRowScope}) — while field visibility
+* is never wider than the widest granted action.
 */
-async function applyArbacMetaOverlay(meta, source) {
-	const arbac = useArbac();
-	const actionToMethodMeta = collectActionMetaByName();
-	const crudKeys = Object.keys(meta.crud);
-	const [actionResults, crudResults] = await Promise.all([Promise.all(meta.actions.map((entry) => {
-		const methodMeta = actionToMethodMeta.get(entry.name);
-		const arbacAction = methodMeta?.arbacActionId ?? methodMeta?.id ?? entry.name;
-		return arbac.evaluate({ action: arbacAction });
-	})), Promise.all(crudKeys.map((key) => arbac.evaluate({ action: key })))]);
-	const filteredActions = [];
-	for (let i = 0; i < meta.actions.length; i++) if (actionResults[i].allowed) filteredActions.push(meta.actions[i]);
-	const filteredCrud = {};
-	for (let i = 0; i < crudKeys.length; i++) if (crudResults[i].allowed) filteredCrud[crudKeys[i]] = meta.crud[crudKeys[i]];
-	let overlaid = {
-		...meta,
-		actions: filteredActions,
-		crud: filteredCrud
-	};
-	let readUnrestricted = false;
-	let writeUnrestricted = false;
-	const readScopes = [];
-	const writeScopes = [];
-	for (let i = 0; i < crudKeys.length; i++) {
-		if (!crudResults[i].allowed) continue;
-		const scopes = crudResults[i].scopes;
-		if (WRITE_CRUD_OPS.has(crudKeys[i])) {
-			if (!scopes || scopes.length === 0) writeUnrestricted = true;
-			else writeScopes.push(...scopes);
-			continue;
-		}
-		if (!scopes || scopes.length === 0) readUnrestricted = true;
-		else readScopes.push(...scopes);
-	}
-	if (!readUnrestricted && readScopes.length > 0) {
-		const vis = isIdentifierSet(source) ? buildScopeVisibility(readScopes, void 0, source) : buildScopeVisibility(readScopes, source);
-		if (Object.keys(vis.allowed).length > 0 || vis.withGrants.size > 0) overlaid = pruneMetaByVisibility(overlaid, {
-			...vis,
-			writable: collectWritableFields(writeScopes, writeUnrestricted)
-		});
-	}
-	return overlaid;
-}
-const actionMetaByClassCache = /* @__PURE__ */ new WeakMap();
-function collectActionMetaByName() {
-	const cc = useControllerContext();
-	const instance = cc.getController();
-	const ctor = getConstructor(instance);
-	const cached = actionMetaByClassCache.get(ctor);
-	if (cached) return cached;
-	const map = /* @__PURE__ */ new Map();
-	const ctrlMeta = cc.getControllerMeta();
-	for (const entry of ctrlMeta?.atscript_db_actions ?? []) map.set(entry.name, {});
-	for (const methodName of collectMethodNames(instance)) {
-		const m = cc.getMethodMeta(methodName);
-		if (!m) continue;
-		const actionMeta = m.atscript_db_action;
-		if (actionMeta?.name) map.set(actionMeta.name, {
-			arbacActionId: m.arbacActionId,
-			id: m.id
-		});
-	}
-	actionMetaByClassCache.set(ctor, map);
-	return map;
+async function authorizeAvailableActions() {
+	const ctx = current();
+	const instance = useControllerContext(ctx).getController();
+	const granted = await evaluateHandlers(actionsIds(discoverRowLevelActions(getConstructor(instance), instance.app, instance.logger).map((e) => e.info.name)));
+	const arbac = useArbac(ctx);
+	if (!granted) throw insufficientPrivileges(arbac.resource, arbac.action);
+	storeResolved(ctx, arbac, void 0, granted.map(withoutRowPolicy));
+}
+/** A scope without its row policy (`filter` / `check`). */
+function withoutRowPolicy(scope) {
+	if (scope.filter === void 0 && scope.check === void 0) return scope;
+	const { filter: _filter, check: _check, ...rest } = scope;
+	return rest;
 }
 /**
-* Test-friendly internal helper — exported for unit tests and helper
-* composition; regular consumers should not call this directly.
+* Body of the ARBAC DB controllers' `allowedActions`: the action `names` the
+* caller holds a grant on — each evaluated as {@link actionArbacIds} names
+* it, exactly the `/meta` overlay's action rule (memoized per event, so the
+* evaluations `prepareRequest` / the overlay already ran are reused).
 *
-* Method names of an instance, walking the full prototype chain via property
-* DESCRIPTORS. Deliberately NOT moost's `getInstanceOwnMethods`: that helper
-* evaluates `instance[name]` for every property to test "is it a function",
-* which fires accessors — and moost-db's inherited `.table` getter THROWS for
-* view-bound controllers, turning every `/meta` request into a 500. Accessor
-* properties are skipped entirely (a getter-valued property is not a method
-* and can never carry `@DbAction` metadata).
+* @since 0.1.72
 */
-function collectMethodNames(instance) {
-	const names = /* @__PURE__ */ new Set();
-	let obj = instance;
-	while (obj && obj !== Object.prototype) {
-		for (const name of Object.getOwnPropertyNames(obj)) {
-			if (name === "constructor") continue;
-			const desc = Object.getOwnPropertyDescriptor(obj, name);
-			if (desc && typeof desc.value === "function") names.add(name);
-		}
-		obj = Object.getPrototypeOf(obj);
-	}
-	return [...names];
+function arbacAllowedActions(names) {
+	return grantedActions(useControllerContext().getController(), names);
 }
-//#endregion
-//#region src/db/shared-read-helpers.ts
+const actionScopes = cached(() => /* @__PURE__ */ new Map());
 /**
-* Single point of access to the per-event scope cache. Reads the slot
-* directly — `hasField` calls this per referenced path, and `useArbac()`
-* would resolve controller metadata on every call.
+* Body of the ARBAC DB controllers' `actionRowScope`: the rows the
+* `@DbAction` `name` may run on — the filter of the caller's grant on the
+* action ({@link actionArbacIds}: every handler method of the action, or a
+* class-level entry's fallback ids), including custom-field row filters and
+* credential attenuation. No grant → a match-nothing filter (fail closed);
+* an unrestricted grant → `undefined`. When the current request IS that
+* action (its resolved scopes are the same evaluation), the row overlay
+* already applies it → `undefined`. Equal filters are returned as ONE
+* object per request.
+*
+* @since 0.1.72
 */
-function readCachedScopes() {
-	return getArbacScopes() ?? [];
+async function arbacActionRowScope(name) {
+	const ctx = current();
+	const ids = actionsIds([name]);
+	const outcomes = await evaluateHandlerOutcomes(ids);
+	const scopes = ids.length === 1 ? normalizeScopes(outcomes[0]) : unionOutcomes(outcomes);
+	if (!scopes) return DENY_FILTER;
+	const prior = resolved();
+	if (prior && ids.length === 1 && ids[0].resource === prior.resource && ids[0].action === prior.action && outcomes[0].scopes !== void 0 && (outcomes[0].scopes === prior.source || outcomes[0].scopes === prior.scopes)) return;
+	const filter = effectiveScope(scopes).filter;
+	if (!filter || Object.keys(filter).length === 0) return void 0;
+	return getOrCreate(ctx.get(actionScopes), stableKey(filter), () => filter);
 }
 /**
-* Full body of `transformFilter` for both ARBAC DB controllers: evaluate
-* ARBAC once, cache the scopes for the per-event hooks that follow
-* (`transformProjection`, `validateControls`), and merge the user filter
-* with the union of scope filters.
+* Body of the ARBAC controllers' `transformFilter` (and so of the row
+* overlay `/one`, `DELETE` and `@DbAction` ids use): the user filter
+* CONJOINED with the union of the request's scope filters.
 *
-* Combining is delegated to `conjoinScopeFilters`, which owns the
-* `$and`-never-spread invariant (a user filter constraining the same field as
-* the scope would otherwise replace it and widen access) and treats an empty
-* side as the identity. Returns a match-nothing filter on denial so the
-* downstream pipeline returns an empty result set without leaking rows.
+* @since 0.1.72
 */
-async function transformArbacFilter(filter) {
-	const arbac = useArbac();
-	const { allowed, scopes } = await arbac.evaluate();
-	if (!allowed) return DENY_FILTER;
-	arbac.setScopes(scopes);
-	return conjoinScopeFilters(mergeScopeFilters((scopes ?? []).map((s) => s.filter ?? {})), filter) ?? {};
+function arbacRowFilter(filter) {
+	return conjoinScopeFilters(effectiveScope(requireRequestScopes()).filter, filter) ?? {};
 }
+//#endregion
+//#region src/db/shared-read-helpers.ts
 /**
 * Restrict the user-supplied `$select` to the scopes' projection union.
 * Returns the original projection untouched when no scope declares a
@@ -760,9 +1705,11 @@ async function transformArbacFilter(filter) {
 * (`{ a: 0 }` → `{ "a.b": 0, "a.c": 0 }`): flattening adapters invert an
 * exclusion against their leaf columns, so a parent key alone would strip
 * nothing (a scope `{ a: 0 }` would otherwise return all of `a`).
+*
+* @since 0.1.72
 */
 function applyArbacProjection(projection, scopes, readable) {
-	return restrictSelect(projection, scopeVisibility(scopes, readable));
+	return restrictSelect(projection, visibilityFor(scopes, readable));
 }
 /** {@link applyArbacProjection} over an already-built visibility level. */
 function restrictSelect(projection, vis) {
@@ -773,52 +1720,54 @@ function restrictSelect(projection, vis) {
 /**
 * Enforce the union of per-scope `controls` gates against the parsed
 * Uniquery controls. Throws `HttpError(403)` on the first violation.
+*
+* @since 0.1.72
 */
 function applyArbacControls(controls, scopes) {
-	if (scopes.length === 0) return;
-	enforceControlsPolicy(unionControlsPolicy(scopes), controls);
+	enforceControlsPolicy(effectiveScope(scopes).controls, controls);
 }
 /**
-* Walk the user-supplied `$with` items in `controls` and inject per-relation
-* filter/projection/controls/nested-$with from the role scopes' `with` field.
+* Walk the user-supplied `$with` items in `controls` and overlay each joined
+* relation with the policy of its rows (the `$with` inherit-target policy):
+* a relation some scope declares `with.<name>` for gets the union of those
+* sub-scopes (parent authority — silent roles contribute nothing); any other
+* gets the caller's OWN read scopes on the related table, as resolved in
+* `prepareRequest` (for the request's own scopes). Filter conjoined, `$select`
+* restricted, per-relation `controls` gates enforced, recursively.
 *
 * Mutates `controls` in place (matches the `validateControls` contract).
-* Throws `HttpError(403)` if a per-relation control policy is violated
-* (delegates to `enforceControlsPolicy` like top-level `applyArbacControls`).
+* Throws `HttpError(403)` if a per-relation control policy is violated. A
+* hidden relation is skipped: moost-db (≥ 0.1.143) rejects it at every
+* level through `hasField`, byte-for-byte like a nonexistent one.
 *
-* Silence wins: if no role declares `with.<name>` for a relation, that entry
-* passes through unchanged. The outermost check skips the entire walk when no
-* scope declares `with` at all — this is the common case on every read.
+* @since 0.1.72
 */
 function applyArbacRelationScopes(controls, scopes, readable) {
-	if (scopes.length === 0) return;
-	if (!scopes.some((s) => s.with)) return;
-	applyRelationLevel(controls, scopeVisibility(scopes, readable));
+	const withArr = controls.$with;
+	if (!Array.isArray(withArr) || withArr.length === 0) return;
+	applyRelationLevel(controls, visibilityFor(scopes, readable));
 }
-/**
-* One `$with` level of {@link applyArbacRelationScopes}: each granted
-* relation's child visibility already carries its sub-scopes and target table.
-*/
+/** One `$with` level of {@link applyArbacRelationScopes}. */
 function applyRelationLevel(controls, vis) {
 	const withArr = controls.$with;
 	if (!Array.isArray(withArr) || withArr.length === 0) return;
 	for (const raw of withArr) {
 		if (!raw || typeof raw !== "object") continue;
 		const entry = raw;
-		if (typeof entry.name !== "string") continue;
-		const child = vis.relation?.(entry.name);
-		const subScopes = child?.scopes ?? [];
-		if (!child || subScopes.length === 0) continue;
-		const conjoined = conjoinScopeFilters(mergeScopeFilters(subScopes.map((s) => s.filter ?? {})), entry.filter);
+		if (typeof entry.name !== "string" || entry.name.includes(".")) continue;
+		const level = (!vis.relationNames || vis.relationNames.has(entry.name)) && isMetaFieldVisible(entry.name, vis) ? vis.relation?.(entry.name) : void 0;
+		if (!level) continue;
+		const sub = effectiveScope(level.scopes ?? []);
+		const conjoined = conjoinScopeFilters(sub.filter, entry.filter);
 		if (conjoined) entry.filter = conjoined;
 		const entryControls = entry.controls ?? {};
-		const restricted = restrictSelect(entryControls.$select, child);
+		const restricted = restrictSelect(entryControls.$select, level);
 		if (restricted !== void 0) {
 			entryControls.$select = restricted;
 			entry.controls = entryControls;
 		}
-		enforceControlsPolicy(unionControlsPolicy(subScopes), entryControls);
-		if (subScopes.some((s) => s.with)) applyRelationLevel(entryControls, child);
+		enforceControlsPolicy(sub.controls, entryControls);
+		applyRelationLevel(entryControls, level);
 	}
 }
 /**
@@ -838,13 +1787,339 @@ function normalizeSelect(value) {
 	if (typeof value === "object") return value;
 }
 //#endregion
+//#region src/db/write-fields.ts
+/**
+* Test-friendly internal helper — exported for unit tests and helper
+* composition; regular consumers should not call this directly.
+*
+* Apply the union of `allowedFields` whitelists (with `preserveFields`
+* always preserved) and overlay each scope's `set` overrides. Returns a
+* copy; the original `data` is not mutated.
+*
+* Path-aware: a top-level entry (`profile`) keeps the whole subtree; a
+* dotted entry (`profile.name`) keeps only that branch of a nested object
+* payload (`profile: { name, tenant }` → `profile: { name }`) — a non-object
+* value under a partially whitelisted key is dropped, never kept whole. A
+* dotted `set` key sets the nested path, merging into the payload's nested
+* object.
+*
+* Patches (`isMergePatch` given): a nested object is written as a whole
+* unless its path is a `@db.patch.strategy 'merge'` block, so a partially
+* whitelisted REPLACE block is dropped (a partial block would clear the
+* non-whitelisted leaves), and a dotted `set` under a replace block the patch
+* does not carry is skipped (adding the block would clear its other leaves).
+*/
+function applyAllowedFieldsAndSet(data, scopes, preserveFields = [], isMergePatch) {
+	if (scopes.length === 0) return data;
+	return applyPreparedOverlay(data, prepareScopeOverlay(scopes, preserveFields, isMergePatch));
+}
+function prepareScopeOverlay(scopes, preserveFields, isMergePatch) {
+	const { allowedFields, set } = effectiveScope(scopes);
+	let tree = null;
+	if (allowedFields) {
+		tree = newNode();
+		for (const f of allowedFields) addPath(tree, f);
+		for (const f of preserveFields) addPath(tree, f);
+	}
+	const setOverrides = set ? Object.entries(set).map(([k, v]) => [k.split("."), v]) : null;
+	return {
+		tree,
+		setOverrides,
+		isMergePatch
+	};
+}
+function newNode() {
+	return {
+		all: false,
+		children: /* @__PURE__ */ new Map()
+	};
+}
+function addPath(tree, path) {
+	let node = tree;
+	for (const seg of path.split(".")) {
+		if (node.all) return;
+		let next = node.children.get(seg);
+		if (!next) {
+			next = newNode();
+			node.children.set(seg, next);
+		}
+		node = next;
+	}
+	node.all = true;
+}
+/** `true` when `path` (dotted) is whitelisted by itself or an ancestor. */
+function coversPath(tree, path) {
+	let node = tree;
+	for (const seg of path.split(".")) {
+		node = node.children.get(seg);
+		if (!node) return false;
+		if (node.all) return true;
+	}
+	return false;
+}
+function pruneByTree(obj, tree, prefix, isMergePatch) {
+	const out = {};
+	for (const [k, v] of Object.entries(obj)) {
+		if (k.includes(".")) {
+			if (coversPath(tree, k)) out[k] = v;
+			continue;
+		}
+		const node = tree.children.get(k);
+		if (!node) continue;
+		if (node.all) {
+			out[k] = v;
+			continue;
+		}
+		const path = prefix + k;
+		if (!isPlainObject(v) || isMergePatch && !isMergePatch(path)) continue;
+		const pruned = pruneByTree(v, node, `${path}.`, isMergePatch);
+		if (Object.keys(pruned).length > 0) out[k] = pruned;
+	}
+	return out;
+}
+/**
+* Set `path` in `target` (copy-on-write for nested objects). On a patch, a
+* missing intermediate replace block is not created — returns without
+* setting (the stored block stays as it is).
+*/
+function setPath$1(target, path, value, isMergePatch, prefix = "") {
+	if (path.length === 1) {
+		target[path[0]] = value;
+		return;
+	}
+	delete target[path.join(".")];
+	const [head, ...rest] = path;
+	const existing = target[head];
+	const objectPath = prefix + head;
+	if (!isPlainObject(existing) && isMergePatch && !isMergePatch(objectPath)) return;
+	const child = isPlainObject(existing) ? { ...existing } : {};
+	target[head] = child;
+	setPath$1(child, rest, value, isMergePatch, `${objectPath}.`);
+}
+function applyPreparedOverlay(data, prepared) {
+	if (Array.isArray(data)) return data.map((row) => applyPreparedOverlay(row, prepared));
+	if (!data || typeof data !== "object") return data;
+	const source = data;
+	const merged = prepared.tree ? pruneByTree(source, prepared.tree, "", prepared.isMergePatch) : { ...source };
+	if (prepared.setOverrides) for (const [path, value] of prepared.setOverrides) setPath$1(merged, path, value, prepared.isMergePatch);
+	return merged;
+}
+//#endregion
+//#region src/db/write-check.ts
+/** Thrown by {@link compileScopeCheck} for an operator the evaluator does not model. */
+var UnsupportedCheckError = class extends Error {};
+/**
+* Compile a scope `check` filter into an in-memory predicate — used only when
+* the adapter cannot roll back (`!transactional`) and the check must run
+* BEFORE the write. Deliberately a small subset of the filter language
+* (`$eq`/`$ne`/`$in`/`$nin`/ordering/`$exists` + `$and`/`$or`/`$not`) with the
+* database's null model (`$eq: null` matches null or missing, `$exists`
+* means "holds a non-null value"); any other operator (e.g. `$regex`) throws
+* {@link UnsupportedCheckError} — callers fail closed.
+*/
+function compileScopeCheck(filter) {
+	return walkFilter(filter, checkVisitor) ?? (() => true);
+}
+/** The field paths a filter references (dotted, as written). */
+function checkFields(filter) {
+	return new Set(computeInsights(filter).keys());
+}
+function same(a, b) {
+	if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+	return a === b;
+}
+function eq(v, value) {
+	return value === null ? v == null : same(v, value);
+}
+function ordinal(v) {
+	return v instanceof Date ? v.getTime() : v;
+}
+const checkVisitor = {
+	and: (children) => (row) => children.every((c) => c(row)),
+	or: (children) => (row) => children.some((c) => c(row)),
+	not: (child) => (row) => !child(row),
+	comparison(field, op, value) {
+		const read = (row) => getPath(row, field);
+		const compare = (test) => (row) => {
+			const v = read(row);
+			return v != null && test(ordinal(v), ordinal(value));
+		};
+		switch (op) {
+			case "$eq": return (row) => eq(read(row), value);
+			case "$ne": return (row) => !eq(read(row), value);
+			case "$in": return (row) => Array.isArray(value) && value.some((x) => same(read(row), x));
+			case "$nin": return (row) => !(Array.isArray(value) && value.some((x) => same(read(row), x)));
+			case "$exists": return (row) => read(row) != null === Boolean(value);
+			case "$gt": return compare((a, b) => a > b);
+			case "$gte": return compare((a, b) => a >= b);
+			case "$lt": return compare((a, b) => a < b);
+			case "$lte": return compare((a, b) => a <= b);
+			default: throw new UnsupportedCheckError(`${field}: ${op}`);
+		}
+	}
+};
+/**
+* The post-image of an update patch for the fields a check references, or
+* `undefined` when it cannot be known without the database (fail closed):
+* every referenced path must be untouched by the patch or set by a plain
+* scalar at exactly that path — a nested object / array / operator value
+* (`$inc`, `$insert`, …) over or under a referenced path is not modelled.
+*/
+function patchPostImage(current, patch, fields) {
+	const out = structuredCloneRow(current);
+	for (const field of fields) for (const [key, value] of Object.entries(patch)) if (key === field) {
+		if (!isComparable(value)) return void 0;
+		setPath(out, field, value);
+	} else if (field.startsWith(`${key}.`) || key.startsWith(`${field}.`)) return;
+	return out;
+}
+/**
+* A value the in-memory evaluator compares faithfully: a primitive, `null`
+* or a `Date` — other class instances (e.g. a Mongo `ObjectId`) compare by
+* identity here, so a SET of one over a checked field is not modelled.
+*/
+function isComparable(v) {
+	return v === null || v instanceof Date || typeof v !== "object" && typeof v !== "function";
+}
+function structuredCloneRow(row) {
+	const out = {};
+	for (const [k, v] of Object.entries(row)) out[k] = isPlainObject(v) ? structuredCloneRow(v) : v;
+	return out;
+}
+function setPath(target, path, value) {
+	const segs = path.split(".");
+	let node = target;
+	for (let i = 0; i < segs.length - 1; i++) {
+		const next = node[segs[i]];
+		if (!next || typeof next !== "object" || Array.isArray(next)) node[segs[i]] = {};
+		node = node[segs[i]];
+	}
+	node[segs.at(-1)] = value;
+}
+//#endregion
+//#region src/db/write-policy.ts
+const OUT_OF_SCOPE = "Row outside your write scope";
+/**
+* Nested writes through nav props are denied unless a write scope opts the
+* relation in via `nestedWrites` (an unrestricted scope does not). A dotted
+* key whose head is a nav prop counts as that relation.
+*/
+function assertNestedWritesAllowed(data, scopes, navFields) {
+	if (navFields.size === 0) return;
+	const rows = Array.isArray(data) ? data : [data];
+	for (const row of rows) {
+		if (!row || typeof row !== "object") continue;
+		for (const key of Object.keys(row)) {
+			const dot = key.indexOf(".");
+			const rel = dot === -1 ? key : key.slice(0, dot);
+			if (navFields.has(rel) && !effectiveScope(scopes).nestedWrites.has(rel)) throw new HttpError(403, `Nested writes through "${rel}" are not allowed`);
+		}
+	}
+}
+/**
+* Every exact id filter (one row each, duplicates counted once) must match
+* a row inside `filter` — ONE count; else the same 404 a missing row gets
+* (no existence leak).
+*/
+async function assertIdFiltersInScope(table, idFilters, filter) {
+	const unique = /* @__PURE__ */ new Map();
+	for (const f of idFilters) unique.set(stableKey(f), f);
+	if (unique.size === 0) return;
+	const ids = [...unique.values()];
+	const idFilter = ids.length === 1 ? ids[0] : { $or: ids };
+	if (await table.count({
+		filter: filter ? { $and: [idFilter, filter] } : idFilter,
+		controls: {}
+	}) < ids.length) throw new HttpError(404, "Not found");
+}
+/**
+* WITH CHECK before the write (adapters without real transactions): insert /
+* replace rows are full rows, evaluated as-is; an update patch is evaluated
+* over its pre-image when every check-referenced field is untouched or a
+* plain scalar SET. Anything the in-memory evaluator cannot decide (an
+* unsupported operator, an operator / nested patch over a checked field, a
+* missing pre-image) is rejected — fail closed.
+*/
+async function assertCheckBeforeWrite(ctx, check) {
+	let predicate;
+	try {
+		predicate = compileScopeCheck(check);
+	} catch (error) {
+		if (error instanceof UnsupportedCheckError) throw new HttpError(403, OUT_OF_SCOPE);
+		throw error;
+	}
+	const fields = isPatchAction(ctx.action) ? checkFields(check) : void 0;
+	const images = fields ? (await ctx.currentAll()).map((current, i) => current ? patchPostImage(current, ctx.rows[i], fields) : void 0) : ctx.rows;
+	for (const image of images) if (!image || !predicate(image)) throw new HttpError(403, OUT_OF_SCOPE);
+}
+/** WITH CHECK after the write (inside the transaction — a throw rolls back). */
+async function assertWrittenRowsInCheck(ctx, check) {
+	if (ctx.filters.length === 0) return;
+	const written = ctx.filters.length === 1 ? ctx.filters[0] : { $or: [...ctx.filters] };
+	if (await ctx.count({ $and: [written, check] }) !== ctx.filters.length) throw new HttpError(403, OUT_OF_SCOPE);
+}
+/**
+* The in-transaction write guard of the ARBAC DB layer — the body of
+* `AsArbacDbController.guardWrite` and of `useArbacDbScope().writeOptions()`'s
+* `guard`:
+*
+* - USING — every update / replace target (the exact record filter the
+*   write uses) must match the scope filter — one count, no pre-image read
+*   (missing or out of scope → 404);
+* - `checkRefs` — every enforced FK the write sets must reference rows the
+*   caller can read on the target table (→ 403);
+* - WITH CHECK when the adapter cannot roll back — validated here, before
+*   the write (see {@link checkArbacWrite} for the transactional path).
+*/
+async function guardArbacWrite(ctx, scopes, table, refs) {
+	const eff = effectiveScope(scopes);
+	if (eff.filter && hasPreImage(ctx.action)) await assertIdFiltersInScope(table, ctx.rows.map((_row, i) => {
+		const filter = ctx.filterFor(i);
+		if (!filter) throw new HttpError(404, "Not found");
+		return filter;
+	}), eff.filter);
+	await assertRefsInScope(ctx, scopes, refs);
+	if (eff.check && !table.getAdapter().isInTransaction()) await assertCheckBeforeWrite(ctx, eff.check);
+}
+/**
+* WITH CHECK after the write, inside its transaction: every written row must
+* match the scopes' `check` (default `filter`) — else 403 and the write rolls
+* back. Non-transactional adapters were checked in {@link guardArbacWrite}.
+*/
+async function checkArbacWrite(ctx, scopes) {
+	if (!ctx.transactional) return;
+	const check = effectiveScope(scopes).check;
+	if (check) await assertWrittenRowsInCheck(ctx, check);
+}
+/** USING for deletes: the exact row the delete targets must match the scope filter (else 404). */
+async function guardArbacRemove(ctx, scopes, table) {
+	const filter = effectiveScope(scopes).filter;
+	if (!filter) return;
+	if (await table.count({
+		filter: { $and: [ctx.filter, filter] },
+		controls: {}
+	}) === 0) throw new HttpError(404, "Not found");
+}
+//#endregion
 //#region src/db/as-arbac-db-controller.ts
 let AsArbacDbController = class AsArbacDbController extends AsDbController {
+	/** Makes this controller the `$with` policy source for its table's ARBAC resource. */
+	_arbacRelationTarget = registerArbacDbTarget(this);
+	/**
+	* Resolve the request's ARBAC scopes before anything else consults them:
+	* reuse the ones the authorize interceptor cached, else evaluate the
+	* handler's resource/action now — a deny is a 403 (`arbacPublic` never
+	* bypasses a DB controller). On read endpoints the `$with` relation policy
+	* is resolved for the requested relations.
+	*/
+	prepareRequest(ctx) {
+		return prepareArbacRequest(ctx, this.readable);
+	}
 	transformFilter(filter) {
-		return transformArbacFilter(filter);
+		return arbacRowFilter(filter);
 	}
 	transformProjection(projection) {
-		return applyArbacProjection(projection, readCachedScopes(), this.readable);
+		return applyArbacProjection(projection, requireRequestScopes(), this.readable);
 	}
 	/**
 	* Translate `@uniqu/url` parser failures into HTTP 400 instead of letting them
@@ -882,18 +2157,14 @@ let AsArbacDbController = class AsArbacDbController extends AsDbController {
 	* controls of a request. Runs after the base validator (which checks the
 	* controls DTO shape) and BEFORE the query/aggregation pipeline executes.
 	*
-	* Reads the scopes the route-level authorize interceptor cached via
-	* `arbac.setScopes(...)` — validation runs before `transformFilter`, so
-	* this hook never re-evaluates ARBAC.
-	*
-	* On a violation we throw `HttpError(403)`. moost-db's `query` / `pages` /
-	* `getOne` handlers do NOT wrap `validateParsed` in try/catch, so the
-	* thrown error bubbles to moost which translates it to a 403 response.
+	* Reads the scopes `prepareRequest` resolved — unresolved scopes are a 403
+	* (never "unrestricted"). A violation throws `HttpError(403)`, which
+	* moost-db's read handlers let bubble.
 	*/
 	validateControls(controls, type) {
 		const baseErr = super.validateControls(controls, type);
 		if (baseErr) return baseErr;
-		const scopes = readCachedScopes();
+		const scopes = requireRequestScopes();
 		applyArbacControls(controls, scopes);
 		applyArbacRelationScopes(controls, scopes, this.readable);
 	}
@@ -901,50 +2172,104 @@ let AsArbacDbController = class AsArbacDbController extends AsDbController {
 		return applyArbacMetaOverlay(meta, this.readable);
 	}
 	/**
-	* Scope-aware field visibility (BUG-3 twin of the `/meta` pruning above): a
+	* `GET /meta/form/:name` serves a form only when the caller may run at
+	* least one of the actions taking it as input (else the unknown-form 404).
+	*/
+	authorizeForm(_name, actionNames) {
+		return authorizeArbacForm(actionNames);
+	}
+	/**
+	* The rows each `@DbAction` may run on: the caller's grant on that action
+	* (see `arbacActionRowScope`). Enforced by the action gate and reflected
+	* in `$actions` and `GET /meta/actions/:id`. Since 0.1.72.
+	*/
+	actionRowScope(name) {
+		return arbacActionRowScope(name);
+	}
+	/**
+	* The row-level actions `$actions` and `GET /meta/actions/:id` may list:
+	* those the caller holds a grant on (the `/meta` overlay's rule, without
+	* building the overlay). Since 0.1.72.
+	*/
+	allowedActions(names) {
+		return arbacAllowedActions(names);
+	}
+	/**
+	* moost-db handlers that delegate their authorization to `prepareRequest`
+	* (`getDbEndpoint` — `GET /meta/actions/:id`): the authorize interceptor
+	* skips them; `prepareRequest` serves them iff the caller may run at least
+	* one row-level action (else 403). Since 0.1.72.
+	*/
+	[ARBAC_DELEGATED_AUTH](method) {
+		return getDbEndpoint(this, method) !== void 0;
+	}
+	/**
+	* Scope-aware field visibility (the twin of the `/meta` pruning above): a
 	* field outside the read-scope projection union answers `false`, which
 	* moost-db's visibility hook turns into the same `Unknown field "x"` 400 a
 	* nonexistent field gets at every gated query position — see the docs'
 	* "Column-scope security floor". Identifiers stay visible. A `rel.x` path
-	* under a `with`-granted relation (`$with=rel(x>1)`, `$with=rel($sort=x)`,
-	* `$with=rel($select=x)`) is checked as `x` against the union of the
-	* `with.rel` sub-scopes, recursively; the related table's own PK /
-	* `preferredId` stay visible.
+	* (`$with=rel(x>1)`, `$with=rel($sort=x)`, `$with=rel($select=x)`) is
+	* checked as `x` against the relation's policy, recursively; the related
+	* table's own PK / `preferredId` stay visible. Unresolved scopes hide every
+	* field.
 	*/
 	hasField(path) {
-		return super.hasField(path) && isScopedFieldVisible(readCachedScopes(), path, this.readable);
-	}
-	async onWrite(action, data) {
-		const scopes = readCachedScopes();
-		if (action !== "insert" && action !== "insertMany") await this.assertInScope(data, scopes);
-		return applyAllowedFieldsAndSet(data, scopes, this.identifierFields());
-	}
-	async onRemove(id) {
-		await this.assertInScope(id, readCachedScopes());
-		return id;
-	}
-	async assertInScope(idOrIds, scopes) {
-		const scopeFilter = mergeScopeFilters(scopes.map((s) => s.filter ?? {}));
-		if (!scopeFilter) return;
-		const ids = Array.isArray(idOrIds) ? idOrIds : [idOrIds];
-		const idFilters = ids.map((id) => this.readable.resolveIdFilter(id, this._idOpts));
-		if (idFilters.some((f) => !f)) throw new HttpError(404, "Not found");
-		const idFilter = idFilters.length === 1 ? idFilters[0] : { $or: idFilters };
-		if (await this.readable.count({ filter: { $and: [idFilter, scopeFilter] } }) < ids.length) throw new HttpError(404, "Not found");
-	}
-	identifierFields() {
+		return super.hasField(path) && requestFieldVisible(path, this.readable);
+	}
+	/**
+	* Untrusted-body stage: reject nested writes the scopes do not opt in
+	* (`nestedWrites`), then apply the `allowedFields` whitelist and `set`.
+	*/
+	onWrite(action, data) {
+		const scopes = requireRequestScopes();
+		assertNestedWritesAllowed(data, scopes, this.readable.navFields);
+		prefetchRefTargets(scopes, this.readable);
+		return applyAllowedFieldsAndSet(data, scopes, this.preservedWriteFields(), isPatchAction(action) ? (path) => this.isMergeBlock(path) : void 0);
+	}
+	/** `true` when a patch merges into the nested object at `path` (`@db.patch.strategy 'merge'`). */
+	isMergeBlock(path) {
+		return this.readable.flatMap.get(path)?.metadata.get("db.patch.strategy") === "merge";
+	}
+	/** In-transaction stage — USING, `checkRefs`, and WITH CHECK on non-transactional adapters. */
+	guardWrite(ctx) {
+		return guardArbacWrite(ctx, requireRequestScopes(), this.guardedTable, this.readable);
+	}
+	/** USING for deletes: the exact row the delete targets must match the scope filter (else 404). */
+	guardRemove(ctx) {
+		return guardArbacRemove(ctx, requireRequestScopes(), this.guardedTable);
+	}
+	/**
+	* WITH CHECK: after the write, inside its transaction, every written row
+	* must match the scopes' `check` (default `filter`) — else 403 and the
+	* write rolls back. Non-transactional adapters were checked in
+	* {@link guardWrite}.
+	*/
+	checkWrite(ctx) {
+		return checkArbacWrite(ctx, requireRequestScopes());
+	}
+	/** `this.table` as the write guards see it (the generic `T` defeats structural matching). */
+	get guardedTable() {
+		return this.table;
+	}
+	preservedWriteFields() {
 		const ctor = this.constructor;
-		const cached = identifierFieldsCache.get(ctor);
+		const cached = preservedFieldsCache.get(ctor);
 		if (cached) return cached;
 		const out = /* @__PURE__ */ new Set();
 		for (const ident of this.readable.identifications) for (const f of ident.fields) out.add(f);
+		const version = this.readable.versionColumn;
+		if (version) {
+			out.add(version);
+			out.add("$cas");
+		}
 		const arr = [...out];
-		identifierFieldsCache.set(ctor, arr);
+		preservedFieldsCache.set(ctor, arr);
 		return arr;
 	}
 };
 AsArbacDbController = __decorate([Inherit()], AsArbacDbController);
-const identifierFieldsCache = /* @__PURE__ */ new WeakMap();
+const preservedFieldsCache = /* @__PURE__ */ new WeakMap();
 /**
 * Test-friendly internal helper — exported for unit tests and helper
 * composition; regular consumers should not call this directly.
@@ -1011,47 +2336,6 @@ function extractUsedControlValues(key, value, controls) {
 	return [];
 }
 /**
-* Test-friendly internal helper — exported for unit tests and helper
-* composition; regular consumers should not call this directly.
-*
-* Apply the union of `allowedFields` whitelists (with `preserveFields`
-* always preserved) and overlay each scope's `set` overrides. Returns a
-* shallow copy; original `data` is not mutated.
-*/
-function applyAllowedFieldsAndSet(data, scopes, preserveFields = []) {
-	if (scopes.length === 0) return data;
-	const prepared = prepareScopeOverlay(scopes, preserveFields);
-	if (Array.isArray(data)) return data.map((row) => applyPreparedOverlay(row, prepared));
-	return applyPreparedOverlay(data, prepared);
-}
-function prepareScopeOverlay(scopes, preserveFields) {
-	let union = null;
-	for (const s of scopes) if (Array.isArray(s.allowedFields)) {
-		if (!union) union = /* @__PURE__ */ new Set();
-		for (const f of s.allowedFields) union.add(f);
-	}
-	if (union) for (const f of preserveFields) union.add(f);
-	let setOverrides = null;
-	for (const s of scopes) if (s.set) {
-		if (!setOverrides) setOverrides = {};
-		Object.assign(setOverrides, s.set);
-	}
-	return {
-		union,
-		setOverrides
-	};
-}
-function applyPreparedOverlay(data, prepared) {
-	if (Array.isArray(data)) return data.map((row) => applyPreparedOverlay(row, prepared));
-	if (!data || typeof data !== "object") return data;
-	const merged = { ...data };
-	if (prepared.union) {
-		for (const k of Object.keys(merged)) if (!prepared.union.has(k)) delete merged[k];
-	}
-	if (prepared.setOverrides) Object.assign(merged, prepared.setOverrides);
-	return merged;
-}
-/**
 * Translate a `@uniqu/url` parser `SyntaxError` into `HttpError(400)`. Any
 * other error (including a pre-existing `HttpError`) is returned as-is so the
 * caller's `throw remapUniquUrlSyntaxError(err)` preserves the original
@@ -1072,35 +2356,297 @@ function remapUniquUrlSyntaxError(err) {
 //#endregion
 //#region src/db/as-arbac-db-readable-controller.ts
 let AsArbacDbReadableController = class AsArbacDbReadableController extends AsDbReadableController {
+	/** Makes this controller the `$with` policy source for its table's ARBAC resource. */
+	_arbacRelationTarget = registerArbacDbTarget(this);
+	/** Same contract as {@link AsArbacDbController.prepareRequest}. */
+	prepareRequest(ctx) {
+		return prepareArbacRequest(ctx, this.readable);
+	}
+	/** Same contract as {@link AsArbacDbController.transformFilter}. */
 	transformFilter(filter) {
-		return transformArbacFilter(filter);
+		return arbacRowFilter(filter);
 	}
+	/** Same contract as {@link AsArbacDbController.transformProjection}. */
 	transformProjection(projection) {
-		return applyArbacProjection(projection, readCachedScopes(), this.readable);
+		return applyArbacProjection(projection, requireRequestScopes(), this.readable);
 	}
+	/** Same contract as {@link AsArbacDbController.validateControls}. */
 	validateControls(controls, type) {
 		const baseErr = super.validateControls(controls, type);
 		if (baseErr) return baseErr;
-		const scopes = readCachedScopes();
+		const scopes = requireRequestScopes();
 		applyArbacControls(controls, scopes);
 		applyArbacRelationScopes(controls, scopes, this.readable);
 	}
-	/**
-	* Same ARBAC `/meta` overlay as the writable controller (actions/crud
-	* filtering + BUG-3 field-surface pruning by the read scopes' projection
-	* union) — view-style metas leak hidden field names identically.
-	*/
+	/** Same contract as {@link AsArbacDbController.applyMetaOverlay}. */
 	applyMetaOverlay(meta) {
 		return applyArbacMetaOverlay(meta, this.readable);
 	}
-	/**
-	* Scope-aware field visibility — same contract as
-	* {@link AsArbacDbController.hasField}.
-	*/
+	/** Same contract as {@link AsArbacDbController.authorizeForm}. */
+	authorizeForm(_name, actionNames) {
+		return authorizeArbacForm(actionNames);
+	}
+	/** Same contract as {@link AsArbacDbController.actionRowScope}. */
+	actionRowScope(name) {
+		return arbacActionRowScope(name);
+	}
+	/** Same contract as {@link AsArbacDbController.allowedActions}. */
+	allowedActions(names) {
+		return arbacAllowedActions(names);
+	}
+	/** Same contract as {@link AsArbacDbController.[ARBAC_DELEGATED_AUTH]}. */
+	[ARBAC_DELEGATED_AUTH](method) {
+		return getDbEndpoint(this, method) !== void 0;
+	}
+	/** Same contract as {@link AsArbacDbController.hasField}. */
 	hasField(path) {
-		return super.hasField(path) && isScopedFieldVisible(readCachedScopes(), path, this.readable);
+		return super.hasField(path) && requestFieldVisible(path, this.readable);
 	}
 };
 AsArbacDbReadableController = __decorate([Inherit()], AsArbacDbReadableController);
 //#endregion
-export { Arbac, ArbacAction, ArbacAuthorize, ArbacResource, ArbacUserProvider, ArbacUserProviderToken, AsArbacDbController, AsArbacDbReadableController, MoostArbac, applyAllowedFieldsAndSet, applyArbacMetaOverlay, arbacAuthorizeInterceptor, arbacPatternToRegex, buildScopeVisibility, collectMethodNames, collectWithGrantNames, collectWritableFields, conjoinArbacDbScopes, enforceControlsPolicy, extractUsedControlValues, getArbacMate, getArbacScopes, isMetaFieldVisible, isScopedFieldVisible, metaAlwaysVisibleFields, pruneMetaByVisibility, unionScopeProjection, useArbac };
+//#region src/db/as-arbac-value-help-controller.ts
+function valueHelpHost(fields, primaryKey, searchableFields) {
+	const ids = primaryKey ? [primaryKey] : [];
+	return {
+		primaryKey,
+		searchableFields,
+		source: {
+			primaryKeys: ids,
+			preferredId: ids,
+			flatMap: fields
+		}
+	};
+}
+function transformValueHelpProjection(host, select) {
+	return widenPrimaryKey(applyArbacProjection(select, requireRequestScopes(), host.source), select, host.primaryKey);
+}
+/**
+* The PK is always visible (`hasField`, `/meta`), so a scope projection
+* never strips it — mirroring the DB controllers' `preferredId` widening.
+* An explicit `$select` that leaves the PK out (or excludes it) still wins.
+*/
+function widenPrimaryKey(projection, requested, pk) {
+	if (!pk || !projection || Array.isArray(projection)) return projection;
+	const mode = getProjectionMode(projection);
+	if (mode === "empty") return projection;
+	if (!requestsField(requested, pk)) return projection;
+	if (mode === "include" && !projection[pk]) return {
+		...projection,
+		[pk]: 1
+	};
+	if (mode === "exclude" && projection[pk] === 0) {
+		const { [pk]: _dropped, ...rest } = projection;
+		return Object.keys(rest).length > 0 ? rest : void 0;
+	}
+	return projection;
+}
+/** Whether a raw value-help `$select` (absent, list, or `{ f: 0 | 1 }` map) asks for `field`. */
+function requestsField(requested, field) {
+	if (requested === void 0 || requested === null) return true;
+	if (Array.isArray(requested)) return requested.length === 0 || requested.includes(field);
+	if (typeof requested !== "object") return true;
+	const map = requested;
+	const values = Object.values(map);
+	if (values.length === 0) return true;
+	return values.every((v) => v === 0 || v === false) ? map[field] === void 0 : !!map[field];
+}
+async function applyValueHelpMetaOverlay(host, meta) {
+	const overlaid = await applyArbacMetaOverlay(meta, host.source);
+	if (!overlaid.searchable || overlaid.fields === meta.fields) return overlaid;
+	return host.searchableFields.some((f) => f in overlaid.fields) ? overlaid : {
+		...overlaid,
+		searchable: false
+	};
+}
+let AsArbacValueHelpController = class AsArbacValueHelpController extends AsValueHelpController {
+	_arbacHost;
+	get arbacHost() {
+		return this._arbacHost ??= valueHelpHost(this.fieldMeta, this.primaryKey, this.searchableFields);
+	}
+	async prepareRequest(_ctx) {
+		await resolveRequestScopes();
+	}
+	transformFilter(filter) {
+		return arbacRowFilter(filter);
+	}
+	transformProjection(select) {
+		return transformValueHelpProjection(this.arbacHost, select);
+	}
+	hasField(path) {
+		return super.hasField(path) && requestFieldVisible(path, this.arbacHost.source);
+	}
+	validateControls(controls, type) {
+		const baseErr = super.validateControls(controls, type);
+		if (baseErr) return baseErr;
+		applyArbacControls(controls, requireRequestScopes());
+	}
+	applyMetaOverlay(meta) {
+		return applyValueHelpMetaOverlay(this.arbacHost, meta);
+	}
+	runQuery(url) {
+		return super.runQuery(url);
+	}
+	runPages(url) {
+		return super.runPages(url);
+	}
+	runGetOne(id) {
+		return super.runGetOne(id);
+	}
+	runGetOneComposite(query) {
+		return super.runGetOneComposite(query);
+	}
+};
+__decorate([
+	ArbacAction("query"),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [String]),
+	__decorateMetadata("design:returntype", void 0)
+], AsArbacValueHelpController.prototype, "runQuery", null);
+__decorate([
+	ArbacAction("pages"),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [String]),
+	__decorateMetadata("design:returntype", void 0)
+], AsArbacValueHelpController.prototype, "runPages", null);
+__decorate([
+	ArbacAction("getOne"),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [String]),
+	__decorateMetadata("design:returntype", void 0)
+], AsArbacValueHelpController.prototype, "runGetOne", null);
+__decorate([
+	ArbacAction("getOneComposite"),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [typeof Record === "undefined" ? Object : Record]),
+	__decorateMetadata("design:returntype", void 0)
+], AsArbacValueHelpController.prototype, "runGetOneComposite", null);
+AsArbacValueHelpController = __decorate([Inherit()], AsArbacValueHelpController);
+let AsArbacJsonValueHelpController = class AsArbacJsonValueHelpController extends AsJsonValueHelpController {
+	_arbacHost;
+	get arbacHost() {
+		return this._arbacHost ??= valueHelpHost(this.fieldMeta, this.primaryKey, this.searchableFields);
+	}
+	async prepareRequest(_ctx) {
+		await resolveRequestScopes();
+	}
+	transformFilter(filter) {
+		return arbacRowFilter(filter);
+	}
+	transformProjection(select) {
+		return transformValueHelpProjection(this.arbacHost, select);
+	}
+	hasField(path) {
+		return super.hasField(path) && requestFieldVisible(path, this.arbacHost.source);
+	}
+	validateControls(controls, type) {
+		const baseErr = super.validateControls(controls, type);
+		if (baseErr) return baseErr;
+		applyArbacControls(controls, requireRequestScopes());
+	}
+	applyMetaOverlay(meta) {
+		return applyValueHelpMetaOverlay(this.arbacHost, meta);
+	}
+	runQuery(url) {
+		return super.runQuery(url);
+	}
+	runPages(url) {
+		return super.runPages(url);
+	}
+	runGetOne(id) {
+		return super.runGetOne(id);
+	}
+	runGetOneComposite(query) {
+		return super.runGetOneComposite(query);
+	}
+};
+__decorate([
+	ArbacAction("query"),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [String]),
+	__decorateMetadata("design:returntype", void 0)
+], AsArbacJsonValueHelpController.prototype, "runQuery", null);
+__decorate([
+	ArbacAction("pages"),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [String]),
+	__decorateMetadata("design:returntype", void 0)
+], AsArbacJsonValueHelpController.prototype, "runPages", null);
+__decorate([
+	ArbacAction("getOne"),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [String]),
+	__decorateMetadata("design:returntype", void 0)
+], AsArbacJsonValueHelpController.prototype, "runGetOne", null);
+__decorate([
+	ArbacAction("getOneComposite"),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [typeof Record === "undefined" ? Object : Record]),
+	__decorateMetadata("design:returntype", void 0)
+], AsArbacJsonValueHelpController.prototype, "runGetOneComposite", null);
+AsArbacJsonValueHelpController = __decorate([Inherit()], AsArbacJsonValueHelpController);
+//#endregion
+//#region src/db/use-arbac-db-scope.ts
+/**
+* The current event's merged ARBAC DB scope, for custom routes and
+* `@DbAction` handlers that query the table directly. Resolves the event's
+* scopes once (the ones the authorize interceptor cached, else an ARBAC
+* evaluation of the current resource/action) — a deny, or an allowed
+* evaluation with no scope left, throws 403.
+*
+* @example
+* ```ts
+* const scope = await useArbacDbScope<typeof Task>();
+* await scope.assertRowsInScope(this.table, [id]);
+* await this.table.updateMany(scope.filter({ id }), { ...patch, ...scope.set() });
+* // A handler-side insert with the CRUD endpoints' write enforcement.
+* await this.table.insertOne({ ...row, ...scope.set() }, scope.writeOptions(this.table));
+* ```
+*/
+async function useArbacDbScope() {
+	const scopes = await resolveRequestScopes();
+	const eff = effectiveScope(scopes);
+	const visibleOn = (table) => (path) => isScopedFieldVisible(scopes, path, table);
+	return {
+		scopes,
+		filter: (extra) => conjoinScopeFilters(eff.filter, extra) ?? {},
+		set: () => ({ ...eff.set }),
+		check: () => eff.check ?? {},
+		async assertRowsInScope(table, ids) {
+			const isFieldVisible = visibleOn(table);
+			const scope = eff.filter;
+			await assertIdFiltersInScope(table, await Promise.all(ids.map(async (id) => {
+				const f = await table.resolveRowFilter(id, {
+					isFieldVisible,
+					scope
+				});
+				if (!f) throw new HttpError(404, "Not found");
+				return f;
+			})), eff.filter);
+		},
+		assertRefsInScope: (table, rows) => assertRefsInScope({
+			action: "insertMany",
+			rows: [...rows],
+			expectedVersions: [],
+			current: async () => null,
+			currentAll: async () => rows.map(() => null),
+			filterFor: () => null
+		}, scopes, table),
+		writeOptions: (table) => ({
+			isFieldVisible: visibleOn(table),
+			guard: async (ctx) => {
+				const rows = ctx;
+				assertNestedWritesAllowed(rows.rows, scopes, navFieldsOf(table));
+				await guardArbacWrite(rows, scopes, table, table);
+			},
+			check: (ctx) => checkArbacWrite(ctx, scopes)
+		}),
+		removeOptions: (table) => ({
+			isFieldVisible: visibleOn(table),
+			...eff.filter ? { scope: eff.filter } : {},
+			guard: (ctx) => guardArbacRemove(ctx, scopes, table)
+		})
+	};
+}
+//#endregion
+export { ARBAC_DELEGATED_AUTH, Arbac, ArbacAction, ArbacAuthorize, ArbacResource, ArbacUserProvider, ArbacUserProviderToken, AsArbacDbController, AsArbacDbReadableController, AsArbacJsonValueHelpController, AsArbacValueHelpController, MoostArbac, applyAllowedFieldsAndSet, applyArbacControls, applyArbacMetaOverlay, applyArbacProjection, applyArbacRelationScopes, arbacActionRowScope, arbacAllowedActions, arbacAuthorizeInterceptor, arbacPatternToRegex, arbacRowFilter, authorizeArbacForm, buildScopeVisibility, cachedRequestScopes, checkArbacWrite, collectMethodNames, collectWithGrantNames, collectWritableFields, conjoinArbacDbScopes, enforceControlsPolicy, extractUsedControlValues, getArbacMate, getArbacScopes, guardArbacRemove, guardArbacWrite, isMetaFieldVisible, isScopedFieldVisible, metaAlwaysVisibleFields, prepareArbacRequest, pruneMetaByVisibility, registerArbacDbTarget, requestFieldVisible, requireRequestScopes, resolveHandlerArbacIds, resolveRequestScopes, unionScopeProjection, useArbac, useArbacDbScope };