@atscript/moost-db 0.1.144 → 0.1.145

package/dist/index.mjs

@@ -347,7 +347,11 @@ function discoverActions(controllerCtor, app, logger) {
 	actionsCache.set(controllerCtor, out);
 	return out;
 }
-/** Row/rows-level subset of {@link discoverActions}; memoized per ctor. */
+/**
+* The `'row'` / `'rows'`-level subset of {@link discoverActions} (since
+* 0.1.145 public) — the actions `$actions` and `GET /meta/actions/:id`
+* consider, in `/meta.actions` order. Memoized per controller class.
+*/
 function discoverRowLevelActions(controllerCtor, app, logger) {
 	const cached = rowLevelActionsCache.get(controllerCtor);
 	if (cached) return cached;
@@ -1109,94 +1113,6 @@ AsReadableController = __decorate([UseValidationErrorTransform(), __decorateMeta
 	Object
 ])], AsReadableController);
 //#endregion
-//#region src/actions/verdict.ts
-/** Assert that a `disabled` predicate returned an array of the expected length; throws HTTP 500 otherwise. */
-function assertVerdictLength(action, verdicts, expected) {
-	if (!Array.isArray(verdicts) || verdicts.length !== expected) throw new HttpError(500, `Action "${action}" disabled predicate returned an invalid verdict array`);
-}
-/** The reason a verdict carries — a non-empty string; `undefined` for `true` / falsy verdicts. */
-function verdictReason(verdict) {
-	return typeof verdict === "string" && verdict !== "" ? verdict : void 0;
-}
-//#endregion
-//#region src/actions/list-augmenter.ts
-const candidateCache = /* @__PURE__ */ new WeakMap();
-/** WHY: envelopes are immutable post-discovery, so derived `Candidate` shape is cached for the envelope's lifetime; `null` sentinel pins table-level skip. */
-function getCandidate(e) {
-	const cached = candidateCache.get(e);
-	if (cached !== void 0) return cached;
-	if (e.info.level !== "row" && e.info.level !== "rows") {
-		candidateCache.set(e, null);
-		return null;
-	}
-	const raw = e.raw;
-	const c = {
-		envelope: e,
-		disabledFn: typeof raw.disabled === "function" ? raw.disabled : void 0,
-		requiredFields: Array.isArray(raw.requiredFields) ? raw.requiredFields : []
-	};
-	candidateCache.set(e, c);
-	return c;
-}
-function collectCandidates(envelopes) {
-	const out = [];
-	for (const e of envelopes) {
-		const c = getCandidate(e);
-		if (c !== null) out.push(c);
-	}
-	return out;
-}
-function computeStripFields(candidates, resolvedProjection) {
-	let userSet = null;
-	let strip = null;
-	for (const c of candidates) for (const f of c.requiredFields) {
-		if (userSet === null) userSet = new Set(resolvedProjection);
-		if (userSet.has(f)) continue;
-		if (strip === null) strip = /* @__PURE__ */ new Set();
-		strip.add(f);
-	}
-	return strip;
-}
-/**
-* Sets `$actions` on every row (plus `$disabledReasons` on rows where a
-* predicate returned a reason string) and strips the columns fetched only for an
-* action's `requiredFields` — IN PLACE; returns the same array, typed as
-* augmented.
-*/
-function augmentRowsWithActions(args) {
-	const { envelopes, rows, resolvedProjection } = args;
-	const candidates = collectCandidates(envelopes);
-	if (candidates.length === 0 || rows.length === 0) return rows;
-	const verdicts = candidates.map((c) => {
-		if (!c.disabledFn) return void 0;
-		const out = c.disabledFn(rows);
-		assertVerdictLength(c.envelope.info.name, out, rows.length);
-		return out;
-	});
-	for (let i = 0; i < rows.length; i++) {
-		const row = rows[i];
-		const names = [];
-		let reasons;
-		for (let j = 0; j < candidates.length; j++) {
-			const name = candidates[j].envelope.info.name;
-			const verdict = verdicts[j]?.[i];
-			if (!verdict) {
-				names.push(name);
-				continue;
-			}
-			const reason = verdictReason(verdict);
-			if (reason !== void 0) (reasons ??= {})[name] = reason;
-		}
-		row.$actions = names;
-		if (reasons) row.$disabledReasons = reasons;
-	}
-	if (resolvedProjection !== null) {
-		const stripFields = computeStripFields(candidates, resolvedProjection);
-		if (stripFields !== null) for (const row of rows) for (const f of stripFields) delete row[f];
-	}
-	return rows;
-}
-//#endregion
 //#region src/actions/current-action.ts
 /** Read the current action's `TDbActionMeta` from the wook context. Returns undefined outside a controller (e.g. direct-wook test paths). */
 function readCurrentActionMeta(ctx) {
@@ -1434,6 +1350,13 @@ const useDbActionIds = defineWook((ctx) => ({ load: () => ctx.get(dbActionIdsSlo
 //#endregion
 //#region src/actions/row-scope.ts
 /**
+* The key of `AsDbReadableController`'s internal action-overlay method —
+* `rowOverlay()` AND (since 0.1.145) the action's `actionRowScope`. A
+* registered symbol: not an overridable seam, and still found when
+* moost-db loads in two module realms (moost-vite SSR).
+*/
+const ACTION_OVERLAY = Symbol.for("atscript-db.actionOverlay");
+/**
 * The controller whose hooks govern this action's rows: only when the action
 * runs against the controller's OWN readable — an `opts.table` binding on a
 * plain controller has no row overlay or visibility hook. Once per event.
@@ -1450,18 +1373,24 @@ const scopedControllerSlot = cached((ctx) => {
 	return ctrl;
 });
 /**
-* The controller's row overlay for action ids / rows — its `rowOverlay()`,
-* the same overlay `/one/:id` ANDs in (no hook call, no extra query when the
-* controller overrides neither `transformOne` nor `transformFilter`), `null`
-* when there is none. Evaluated once per request, after the controller's
-* `prepareRequest` (since 0.1.143).
+* The controller's row overlay for this action's ids / rows — its
+* `rowOverlay()` (the overlay `/one/:id` ANDs in) AND, since 0.1.145, the
+* action's `actionRowScope`; `null` when both are empty (no hook call, no
+* extra query when the controller overrides none of `transformOne`,
+* `transformFilter`, `actionRowScope`). Evaluated once per request, after
+* the controller's `prepareRequest` (since 0.1.143).
 */
 const dbActionOverlaySlot = cached(async (ctx) => {
 	const ctrl = ctx.get(scopedControllerSlot);
-	if (!ctrl?.rowOverlay) return null;
+	const overlayOf = ctrl?.[ACTION_OVERLAY];
+	if (!overlayOf) return null;
 	await awaitActionPrepared(ctx);
-	return await ctrl.rowOverlay() ?? null;
+	return await overlayOf.call(ctrl, readCurrentActionMeta(ctx)?.name) ?? null;
 });
+/** `filter` unless it is absent or `{}`. */
+function nonEmptyFilter(filter) {
+	return filter && !isEmptyObject(filter) ? filter : void 0;
+}
 /** `filter` AND the overlay (identity without one). */
 function withOverlay(filter, overlay) {
 	return overlay ? { $and: [filter, overlay] } : filter;
@@ -1476,6 +1405,232 @@ function actionFieldVisibility(ctx) {
 	return visibility?.scoped ? visibility.isVisible : void 0;
 }
 //#endregion
+//#region src/actions/rows-by-id.ts
+function stringifyScalar(value) {
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	return String(value);
+}
+/**
+* The identity of `id`'s values over `fields` (sorted) — equal for equal
+* keys across driver representations (a number vs its string, an ObjectId
+* vs its hex). `undefined` when `row` lacks one of the fields.
+*/
+function idKey(row, fields) {
+	let key = "";
+	for (const f of fields) {
+		const v = row[f];
+		if (v === void 0) return void 0;
+		key += `${f}\x1f${stringifyScalar(v)}\x1e`;
+	}
+	return key;
+}
+/**
+* The rows `ids` address that also match `scope` (none = every row),
+* aligned with `ids` — `undefined` where nothing matched. One `findMany`
+* over the deduped ids (`{ $or: ids } AND scope`) selecting `select` plus
+* every id field; ids of different identification shapes may be mixed.
+* The action row loader and `$actions` scope check share it.
+*/
+async function findRowsByIds(source, ids, scope, select) {
+	if (ids.length === 0) return [];
+	const fields = new Set(select);
+	const shapes = /* @__PURE__ */ new Map();
+	const idKeys = [];
+	const dedupedIds = [];
+	const seenKeys = /* @__PURE__ */ new Set();
+	for (const id of ids) {
+		const sortedFields = Object.keys(id).toSorted();
+		for (const f of sortedFields) fields.add(f);
+		const sig = sortedFields.join("");
+		if (!shapes.has(sig)) shapes.set(sig, sortedFields);
+		const key = idKey(id, sortedFields);
+		idKeys.push(key);
+		if (key !== void 0 && !seenKeys.has(key)) {
+			seenKeys.add(key);
+			dedupedIds.push(id);
+		}
+	}
+	const rows = await source.findMany({
+		filter: withOverlay({ $or: dedupedIds }, scope),
+		controls: { $select: [...fields] }
+	});
+	const rowByKey = /* @__PURE__ */ new Map();
+	for (const row of rows) for (const sortedFields of shapes.values()) {
+		const key = idKey(row, sortedFields);
+		if (key !== void 0 && !rowByKey.has(key)) rowByKey.set(key, row);
+	}
+	return idKeys.map((key) => key === void 0 ? void 0 : rowByKey.get(key));
+}
+/** The `requiredFields` of action opts (`@DbAction` opts or a discovered envelope's raw entry). */
+function requiredFieldsOf(opts) {
+	const fields = opts?.requiredFields;
+	return Array.isArray(fields) ? fields : [];
+}
+/**
+* Id columns (`preferredId`, else the primary key) plus `requiredFields` —
+* minus any `isVisible` hides (since 0.1.143; `hasField`, and a derived
+* field over a hidden source): a hidden column is never loaded, so a
+* `disabled` predicate sees it as `undefined`. What an action's gate loads.
+*/
+function actionRowFields(table, requiredFields, isVisible) {
+	const fields = new Set(table.preferredId ?? table.primaryKeys);
+	for (const f of requiredFields) if (!isVisible || isVisible(f)) fields.add(f);
+	return fields;
+}
+/** `true` when `row` carries a top-level key outside `fields` (projecting it would drop something). */
+function exceedsFields(row, fields) {
+	for (const key in row) if (!fields.has(key)) return true;
+	return false;
+}
+/** `row` narrowed to `fields` (dot paths copied into fresh nested objects). */
+function projectRow$1(row, fields) {
+	const out = {};
+	for (const path of fields) {
+		const parts = path.split(".");
+		let src = row;
+		for (const p of parts) src = src?.[p];
+		if (src === void 0) continue;
+		let dst = out;
+		for (let i = 0; i < parts.length - 1; i++) dst = dst[parts[i]] ??= {};
+		dst[parts.at(-1)] = src;
+	}
+	return out;
+}
+//#endregion
+//#region src/actions/verdict.ts
+/** Assert that a `disabled` predicate returned an array of the expected length; throws HTTP 500 otherwise. */
+function assertVerdictLength(action, verdicts, expected) {
+	if (!Array.isArray(verdicts) || verdicts.length !== expected) throw new HttpError(500, `Action "${action}" disabled predicate returned an invalid verdict array`);
+}
+/** Runs `disabled` over `rows` — one verdict per row (a wrong-length answer → HTTP 500). */
+function judgeRows(action, disabled, rows) {
+	const verdicts = disabled(rows);
+	assertVerdictLength(action, verdicts, rows.length);
+	return verdicts;
+}
+/** {@link judgeRows} for one row. */
+function judgeRow(action, disabled, row) {
+	return judgeRows(action, disabled, [row])[0];
+}
+/** The reason a verdict carries — a non-empty string; `undefined` for `true` / falsy verdicts. */
+function verdictReason(verdict) {
+	return typeof verdict === "string" && verdict !== "" ? verdict : void 0;
+}
+//#endregion
+//#region src/actions/list-augmenter.ts
+const candidateCache = /* @__PURE__ */ new WeakMap();
+/** WHY: envelopes are immutable post-discovery, so derived `Candidate` shape is cached for the envelope's lifetime; `null` sentinel pins table-level skip. */
+function getCandidate(e) {
+	const cached = candidateCache.get(e);
+	if (cached !== void 0) return cached;
+	if (e.info.level !== "row" && e.info.level !== "rows") {
+		candidateCache.set(e, null);
+		return null;
+	}
+	const raw = e.raw;
+	const c = {
+		envelope: e,
+		disabledFn: typeof raw.disabled === "function" ? raw.disabled : void 0,
+		requiredFields: requiredFieldsOf(e.raw)
+	};
+	candidateCache.set(e, c);
+	return c;
+}
+function collectCandidates(envelopes) {
+	const out = [];
+	for (const e of envelopes) {
+		const c = getCandidate(e);
+		if (c !== null) out.push(c);
+	}
+	return out;
+}
+function computeStripFields(candidates, resolvedProjection) {
+	let userSet = null;
+	let strip = null;
+	for (const c of candidates) for (const f of c.requiredFields) {
+		if (userSet === null) userSet = new Set(resolvedProjection);
+		if (userSet.has(f)) continue;
+		if (strip === null) strip = /* @__PURE__ */ new Set();
+		strip.add(f);
+	}
+	return strip;
+}
+/**
+* Sets `$actions` on every row (plus `$disabledReasons` on rows where a
+* predicate returned a reason string) and strips the columns fetched only for an
+* action's `requiredFields` — IN PLACE; returns the same array, typed as
+* augmented.
+*/
+function augmentRowsWithActions(args) {
+	const { envelopes, rows, resolvedProjection, outOfScope, gateFields } = args;
+	const candidates = collectCandidates(envelopes);
+	if (candidates.length === 0 || rows.length === 0) return rows;
+	const verdicts = candidates.map((c) => {
+		if (!c.disabledFn) return void 0;
+		const fields = gateFields?.(c.envelope);
+		const input = fields && rows.some((row) => exceedsFields(row, fields)) ? rows.map((row) => projectRow$1(row, fields)) : rows;
+		return judgeRows(c.envelope.info.name, c.disabledFn, input);
+	});
+	const masks = outOfScope && candidates.map((c) => outOfScope.get(c.envelope.info.name));
+	for (let i = 0; i < rows.length; i++) {
+		const row = rows[i];
+		const names = [];
+		let reasons;
+		for (let j = 0; j < candidates.length; j++) {
+			if (masks?.[j]?.[i]) continue;
+			const name = candidates[j].envelope.info.name;
+			const verdict = verdicts[j]?.[i];
+			if (!verdict) {
+				names.push(name);
+				continue;
+			}
+			const reason = verdictReason(verdict);
+			if (reason !== void 0) (reasons ??= {})[name] = reason;
+		}
+		row.$actions = names;
+		if (reasons) row.$disabledReasons = reasons;
+	}
+	if (resolvedProjection !== null) {
+		const stripFields = computeStripFields(candidates, resolvedProjection);
+		if (stripFields !== null) for (const row of rows) for (const f of stripFields) delete row[f];
+	}
+	return rows;
+}
+//#endregion
+//#region src/db-endpoint.ts
+/**
+* Tags a framework handler whose authorization is delegated to the
+* controller's `prepareRequest` (it runs first with `endpoint`), so a
+* permission layer can recognise it without knowing its method name.
+* Internal — moost-db tags its own handlers.
+*/
+function DbEndpoint(endpoint) {
+	return getAtscriptDbMate().decorate("atscript_db_endpoint", endpoint);
+}
+/**
+* The `prepareRequest` endpoint a controller handler delegates its
+* authorization to (since 0.1.145) — `undefined` for a handler that is
+* authorized on its own like any other route. `target` is the controller
+* instance or class; the tag is inherited through the class chain (a
+* subclass override of a tagged handler keeps it). Today only
+* `GET /meta/actions/:id` and `/meta/actions?…` are tagged
+* (`"availableActions"`).
+*
+* ```ts
+* const endpoint = getDbEndpoint(controller, methodName);
+* if (endpoint) return; // prepareRequest({ endpoint }) authorizes this call
+* ```
+*/
+function getDbEndpoint(target, method) {
+	const mate = getAtscriptDbMate();
+	let proto = typeof target === "function" ? target.prototype : Object.getPrototypeOf(target);
+	for (; proto && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
+		const endpoint = mate.read(proto, method)?.atscript_db_endpoint;
+		if (endpoint) return endpoint;
+	}
+}
+//#endregion
 //#region src/decorators.ts
 /**
 * DI token under which the {@link AtscriptDbReadable} instance
@@ -1981,6 +2136,8 @@ function writeOnlyError(path, op) {
 	const verdict = writeOnlyVerdict(path, op);
 	return badRequest(verdict.path, verdict.message);
 }
+/** Controller classes already warned that `actionRowScope` has no row identity to match by. */
+const warnedNoIdentity = /* @__PURE__ */ new WeakSet();
 let AsDbReadableController = _AsDbReadableController = class AsDbReadableController extends AsReadableController {
 	/** Reference to the underlying readable (table or view). */
 	readable;
@@ -2054,6 +2211,12 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	_decorates;
 	/** `true` when a subclass overrides {@link transformOne} or {@link transformFilter} (a row overlay may exist). */
 	_hasRowOverlay;
+	/** Per-envelope gate fields, memoized while field visibility is not request-scoped. */
+	_gateFieldsMemo = /* @__PURE__ */ new WeakMap();
+	/** `true` when a subclass overrides {@link allowedActions}. */
+	_hasAllowedActions;
+	/** `true` when a subclass overrides {@link actionRowScope} (the gate, `$actions` and `/meta/actions` apply it). */
+	_hasActionRowScope;
 	/** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
 	_quantityRefByPath;
 	/** `@db.column.searchable` paths — the `$search` fallback when the adapter has no native search. */
@@ -2081,6 +2244,12 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		this._decorates = typeof this.decorateRows === "function";
 		const proto = _AsDbReadableController.prototype;
 		this._hasRowOverlay = this.transformOne !== proto.transformOne || this.transformFilter !== proto.transformFilter;
+		this._hasActionRowScope = this.actionRowScope !== proto.actionRowScope;
+		this._hasAllowedActions = this.allowedActions !== proto.allowedActions;
+		if (this._hasActionRowScope && resolved.preferredId.length === 0 && !warnedNoIdentity.has(new.target)) {
+			warnedNoIdentity.add(new.target);
+			this.logger.warn(`actionRowScope() is overridden but "${resolved.tableName}" has no primary key — \`$actions\` withholds every action with a non-empty row scope`);
+		}
 		const scoped = this.hasField !== proto.hasField;
 		this._hasFieldOverridden = scoped;
 		const isVisible = (path) => {
@@ -2560,6 +2729,50 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		return this.transformFilter(filter);
 	}
 	/**
+	* The subset of the row-level action `names` the caller may run (since
+	* 0.1.145) — what `$actions` and `GET /meta/actions/:id` list from. The
+	* default keeps the names present in the per-request `/meta` envelope
+	* (`applyMetaOverlay` over the cached one), or all of them when
+	* `applyMetaOverlay` is not overridden (no call). Override it to answer
+	* from per-action permission checks without building the whole `/meta`
+	* overlay on every `$actions` read. Runs after {@link prepareRequest}.
+	* Names it returns that are not in `names` are ignored.
+	*
+	* @since 0.1.145
+	*/
+	allowedActions(names) {
+		if (this._overlayIsNoOp) return names;
+		return (async () => {
+			const present = new Set((await this.resolveMeta()).actions.map((a) => a.name));
+			return names.filter((name) => present.has(name));
+		})();
+	}
+	/**
+	* The rows the row-level action `actionName` may run on (since 0.1.145),
+	* as an extra row filter; `undefined` or `{}` = no restriction (the
+	* default). Enforced by the action gate — ANDed with the {@link rowOverlay}
+	* the action's ids / rows are loaded under, so an id outside it gets the
+	* same 404 "Row not found for action identifier" as a missing one — and
+	* reflected in `$actions` and `GET /meta/actions`, which list the action
+	* only on rows inside it.
+	*
+	* Runs after {@link prepareRequest}, once per action per request. `$actions`
+	* checks the page's rows with one id-only query per distinct filter
+	* OBJECT (return the same object for several actions to share one query),
+	* straight against the bound readable: the filter may use fields
+	* {@link hasField} hides, and nothing of it reaches the response. Not
+	* overriding it costs nothing.
+	*
+	* ```ts
+	* protected actionRowScope(action: string) {
+	*   return action === "approve" ? { ownerId: currentUserId() } : undefined
+	* }
+	* ```
+	*
+	* @since 0.1.145
+	*/
+	actionRowScope(_actionName) {}
+	/**
 	* Transform projection before querying.
 	* May return a Promise for async lookups.
 	*/
@@ -2687,14 +2900,13 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		if (excluded.length > 0 && included.length === 0) return this._invertExclusion(new Set(excluded));
 		throw new HttpError(500, "[moost-db] mixed inclusion/exclusion projection reached augmenter; widenPreferredIdProjection should have rejected it");
 	}
-	/** WHY: filter row/rows envelopes by the per-request `applyMetaOverlay` action set; skip `meta()` when overlay is identity. */
+	/** Row/rows envelopes narrowed to {@link allowedActions}; no hook call when neither it nor `applyMetaOverlay` is overridden. */
 	async _resolveAugmentEnvelopes() {
 		const rowLevelEnvelopes = discoverRowLevelActions(this.constructor, this.app, this.logger);
 		if (rowLevelEnvelopes.length === 0) return null;
-		if (this._overlayIsNoOp) return rowLevelEnvelopes;
-		const overlayMeta = await this.resolveMeta();
-		const allowedNames = new Set(overlayMeta.actions.map((a) => a.name));
-		const filtered = rowLevelEnvelopes.filter((e) => allowedNames.has(e.info.name));
+		if (this._overlayIsNoOp && !this._hasAllowedActions) return rowLevelEnvelopes;
+		const allowed = new Set(await this.allowedActions(rowLevelEnvelopes.map((e) => e.info.name)));
+		const filtered = rowLevelEnvelopes.filter((e) => allowed.has(e.info.name));
 		return filtered.length === 0 ? null : filtered;
 	}
 	/**
@@ -2706,18 +2918,14 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	_widenSelectForActions(envelopes, baseSelect) {
 		let resultSet = null;
 		let result = null;
-		for (const e of envelopes) {
-			const raw = e.raw;
-			if (!Array.isArray(raw.requiredFields)) continue;
-			for (const f of raw.requiredFields) {
-				if ((resultSet ? resultSet.has(f) : baseSelect.includes(f)) || !this.fieldVisibility.isVisible(f)) continue;
-				if (resultSet === null) {
-					resultSet = new Set(baseSelect);
-					result = [...baseSelect];
-				}
-				resultSet.add(f);
-				result.push(f);
+		for (const e of envelopes) for (const f of requiredFieldsOf(e.raw)) {
+			if ((resultSet ? resultSet.has(f) : baseSelect.includes(f)) || !this.fieldVisibility.isVisible(f)) continue;
+			if (resultSet === null) {
+				resultSet = new Set(baseSelect);
+				result = [...baseSelect];
 			}
+			resultSet.add(f);
+			result.push(f);
 		}
 		return result;
 	}
@@ -2725,14 +2933,104 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		if (!controls.$actions) return null;
 		const envelopes = await this._resolveAugmentEnvelopes();
 		if (envelopes === null) return null;
+		let scopeGroups = null;
+		if (this._hasActionRowScope) {
+			scopeGroups = this._resolveActionScopeGroups(envelopes);
+			scopeGroups.catch(() => {});
+		}
 		const resolvedProjection = this._resolveProjectionForAugmenter(select);
 		return {
 			envelopes,
 			resolvedProjection,
-			widenedSelect: resolvedProjection === null ? null : this._widenSelectForActions(envelopes, resolvedProjection)
+			widenedSelect: resolvedProjection === null ? null : this._widenSelectForActions(envelopes, resolvedProjection),
+			scopeGroups
 		};
 	}
 	/**
+	* {@link actionRowScope} of every offered action (in parallel, alongside
+	* `overlay`), grouped by filter object; each group's filter is composed
+	* with the row overlay exactly as the gate composes it.
+	*/
+	async _resolveActionScopeGroups(envelopes, overlay = this.rowOverlay()) {
+		const [rowOverlay, scopes] = await Promise.all([overlay, Promise.all(envelopes.map(async (e) => this._actionScope(e.info.name)))]);
+		const groups = /* @__PURE__ */ new Map();
+		for (let i = 0; i < envelopes.length; i++) {
+			const scope = scopes[i];
+			if (!scope) continue;
+			let group = groups.get(scope);
+			if (!group) {
+				group = {
+					filter: withOverlay(scope, rowOverlay),
+					actions: []
+				};
+				groups.set(scope, group);
+			}
+			group.actions.push(envelopes[i].info.name);
+		}
+		return [...groups.values()];
+	}
+	/** Per scoped action, a per-row mask of rows outside its scope (one id-only read per group). */
+	async _outOfScopeMasks(rows, groups) {
+		const idFields = this.readable.preferredId;
+		const idIndex = [];
+		const ids = [];
+		for (const row of rows) {
+			const id = {};
+			let complete = idFields.length > 0;
+			for (const f of idFields) {
+				const value = row[f];
+				if (value === void 0 || value === null) {
+					complete = false;
+					break;
+				}
+				id[f] = value;
+			}
+			idIndex.push(complete ? ids.push(id) - 1 : -1);
+		}
+		const source = this.readable;
+		const found = await Promise.all(groups.map((group) => findRowsByIds(source, ids, group.filter, [])));
+		const masks = /* @__PURE__ */ new Map();
+		for (let g = 0; g < groups.length; g++) {
+			const mask = idIndex.map((i) => i < 0 || found[g][i] === void 0);
+			for (const name of groups[g].actions) masks.set(name, mask);
+		}
+		return masks;
+	}
+	/**
+	* The row filter {@link actionRowScope} returns for `action` — `undefined`
+	* when empty or when the hook is not overridden (no call). THE per-action
+	* scope rule: the action gate, `$actions` and `/meta/actions` all read it here.
+	*/
+	async _actionScope(action) {
+		if (!this._hasActionRowScope) return void 0;
+		return nonEmptyFilter(await this.actionRowScope(action));
+	}
+	/**
+	* The fields `envelope`'s gate loads ({@link actionRowFields} under this
+	* request's field visibility) — memoized unless visibility is request-scoped.
+	*/
+	_gateFields(envelope) {
+		const visibility = this.fieldVisibility;
+		const required = requiredFieldsOf(envelope.raw);
+		if (visibility.scoped) return actionRowFields(this.readable, required, visibility.isVisible);
+		let fields = this._gateFieldsMemo.get(envelope);
+		if (!fields) {
+			fields = actionRowFields(this.readable, required, void 0);
+			this._gateFieldsMemo.set(envelope, fields);
+		}
+		return fields;
+	}
+	/**
+	* @internal The action gate's overlay (reached by the `@DbAction`
+	* interceptor through {@link ACTION_OVERLAY}): {@link rowOverlay} AND the
+	* action's {@link actionRowScope} (since 0.1.145) — `undefined` when both
+	* are empty.
+	*/
+	async [ACTION_OVERLAY](action) {
+		const [overlay, scope] = await Promise.all([this.rowOverlay(), action === void 0 ? void 0 : this._actionScope(action)]);
+		return scope ? withOverlay(scope, overlay) : overlay;
+	}
+	/**
 	* `@db.column.searchable` paths, minus anything the adapter can't filter
 	* (JSON storage, encrypted), `@db.writeOnly` fields and navigation
 	* descendants — physical capability only (manual-mode policy does not
@@ -2801,7 +3099,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		if (fields.length === 0) return filter;
 		const rx = `/${term.replace(/[.*+?^${}()|[\]\\/]/g, String.raw`\$&`)}/i`;
 		const fragment = { $or: fields.map((f) => ({ [f]: { $regex: rx } })) };
-		return filter && !isEmptyObject(filter) ? { $and: [filter, fragment] } : fragment;
+		const base = nonEmptyFilter(filter);
+		return base ? { $and: [base, fragment] } : fragment;
 	}
 	/**
 	* The controls a grouped query hands to the adapter. `$search` has two
@@ -2847,15 +3146,27 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	}
 	/**
 	* Finishes a read's top-level rows in place: `$actions` augmentation (when
-	* the request asked for it — `prep`), then {@link decorateRows} when a
+	* the request asked for it — `prep`; minus actions whose
+	* {@link actionRowScope} a row misses), then {@link decorateRows} when a
 	* subclass implements it. Returns the hook's result — `undefined`, with no
 	* promise or microtask, when there is no hook or it is synchronous.
 	*/
 	_finishRows(rows, prep, ctx) {
+		const groups = prep?.scopeGroups;
+		if (!groups) return this._augmentAndDecorate(rows, prep, ctx);
+		return (async () => {
+			const masks = await this._outOfScopeMasks(rows, await groups);
+			await this._augmentAndDecorate(rows, prep, ctx, masks);
+		})();
+	}
+	/** `$actions` augmentation (when `prep`), then {@link decorateRows} when implemented. */
+	_augmentAndDecorate(rows, prep, ctx, outOfScope) {
 		if (prep) augmentRowsWithActions({
 			envelopes: prep.envelopes,
 			rows,
-			resolvedProjection: prep.resolvedProjection
+			resolvedProjection: prep.resolvedProjection,
+			gateFields: (e) => this._gateFields(e),
+			outOfScope
 		});
 		return this._decorates ? this.decorateRows(rows, ctx) : void 0;
 	}
@@ -2930,8 +3241,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	*/
 	async rowOverlay() {
 		if (!this._hasRowOverlay) return void 0;
-		const overlay = await this.transformOne({});
-		return overlay && !isEmptyObject(overlay) ? overlay : void 0;
+		return nonEmptyFilter(await this.transformOne({}));
 	}
 	/**
 	* Pick the first identification (PK or unique index) whose fields are all
@@ -3174,6 +3484,71 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		return item;
 	}
 	/**
+	* **GET /meta/actions/:id** — the row-level actions the caller may run on
+	* the row `id` addresses (the `/one/:id` id forms), as
+	* `{ actions, disabledReasons? }` — no row data (since 0.1.145). Exactly
+	* what calling each action would do: the action survives
+	* {@link applyMetaOverlay}, the row resolves under its gate overlay
+	* ({@link actionOverlay}) and its `disabled` rule passes on the fields the
+	* gate loads. Needs no read grant; an unknown or out-of-scope id answers
+	* `{ actions: [] }`. {@link prepareRequest} runs first with
+	* `endpoint: "availableActions"`.
+	*/
+	async availableActionsById(id) {
+		await this.parseRequest("availableActions");
+		return this._availableActions(id);
+	}
+	/**
+	* **GET /meta/actions?field1=val1&…** — {@link availableActionsById} by
+	* composite key (composite primary key or compound unique index), the
+	* `/one?…` rules.
+	*/
+	async availableActions(query) {
+		await this.parseRequest("availableActions");
+		const idObj = this.extractIdShape(query);
+		if (idObj instanceof HttpError) return idObj;
+		return this._availableActions(idObj);
+	}
+	/**
+	* The row resolves ONCE, like `/one/:id` under {@link rowOverlay}; scoped
+	* actions are then checked on it exactly like `$actions` rows.
+	*/
+	async _availableActions(id) {
+		const envelopes = await this._resolveAugmentEnvelopes();
+		if (envelopes === null) return { actions: [] };
+		const overlay = this.rowOverlay();
+		const groups = this._hasActionRowScope ? this._resolveActionScopeGroups(envelopes, overlay) : void 0;
+		groups?.catch(() => {});
+		const idKeys = id !== null && typeof id === "object" ? Object.keys(id) : [];
+		const fieldsOf = envelopes.map((e) => {
+			const fields = this._gateFields(e);
+			return idKeys.every((k) => fields.has(k)) ? fields : new Set([...fields, ...idKeys]);
+		});
+		const select = /* @__PURE__ */ new Set();
+		for (const fields of fieldsOf) for (const f of fields) select.add(f);
+		const row = await this._findRow(id, await overlay, { $select: [...select] });
+		if (!row) return { actions: [] };
+		const masks = groups ? await this._outOfScopeMasks([row], await groups) : void 0;
+		const actions = [];
+		let disabledReasons;
+		for (let i = 0; i < envelopes.length; i++) {
+			const name = envelopes[i].info.name;
+			if (masks?.get(name)?.[0]) continue;
+			const disabled = getCandidate(envelopes[i])?.disabledFn;
+			const verdict = disabled ? judgeRow(name, disabled, projectRow$1(row, fieldsOf[i])) : false;
+			if (!verdict) {
+				actions.push(name);
+				continue;
+			}
+			const reason = verdictReason(verdict);
+			if (reason !== void 0) (disabledReasons ??= {})[name] = reason;
+		}
+		return disabledReasons ? {
+			actions,
+			disabledReasons
+		} : { actions };
+	}
+	/**
 	* **GET /meta** — returns table/view metadata for UI.
 	*
 	* Overrides the base's minimal envelope to add relations, searchable flags,
@@ -3278,6 +3653,22 @@ __decorate([
 	__decorateMetadata("design:paramtypes", [typeof Record === "undefined" ? Object : Record, String]),
 	__decorateMetadata("design:returntype", Promise)
 ], AsDbReadableController.prototype, "getOneComposite", null);
+__decorate([
+	Get("meta/actions/:id"),
+	DbEndpoint("availableActions"),
+	__decorateParam(0, Param("id")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [String]),
+	__decorateMetadata("design:returntype", Promise)
+], AsDbReadableController.prototype, "availableActionsById", null);
+__decorate([
+	Get("meta/actions"),
+	DbEndpoint("availableActions"),
+	__decorateParam(0, Query()),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [typeof Record === "undefined" ? Object : Record]),
+	__decorateMetadata("design:returntype", Promise)
+], AsDbReadableController.prototype, "availableActions", null);
 AsDbReadableController = _AsDbReadableController = __decorate([
 	Inherit(),
 	__decorateParam(1, Inject(READABLE_DEF)),
@@ -4073,33 +4464,13 @@ function asFetchTable(value) {
 	if (Array.isArray(v.primaryKeys) && typeof v.findOne === "function" && typeof v.findMany === "function") return v;
 	return null;
 }
-function stringifyScalar(value) {
-	if (value === null) return "null";
-	if (value === void 0) return "undefined";
-	return String(value);
-}
-/** Returns the action's `requiredFields` or null when called outside a controller context (e.g. direct wook usage in tests). */
-function readActionFieldSet(ctx) {
-	const action = readCurrentActionMeta(ctx);
-	if (!action) return null;
-	const opts = action.opts;
-	return Array.isArray(opts.requiredFields) ? opts.requiredFields : null;
-}
 /**
-* Id columns plus the action's `requiredFields` — minus any the controller's
-* field visibility hides (since 0.1.143; `hasField`, and a derived field over
-* a hidden source): a hidden column is never loaded, so a `disabled`
-* predicate sees it as `undefined`.
+* What this action's gate loads: {@link actionRowFields} of its
+* `requiredFields` (none outside a controller context, e.g. direct wook
+* usage in tests) under the controller's field visibility.
 */
 function seedActionFields(ctx, table) {
-	const fields = /* @__PURE__ */ new Set();
-	for (const f of table.preferredId ?? table.primaryKeys) fields.add(f);
-	const action = readActionFieldSet(ctx);
-	if (action) {
-		const visible = actionFieldVisibility(ctx);
-		for (const f of action) if (!visible || visible(f)) fields.add(f);
-	}
-	return fields;
+	return actionRowFields(table, requiredFieldsOf(readCurrentActionMeta(ctx)?.opts), actionFieldVisibility(ctx));
 }
 /**
 * Loaded row / rows are ANDed with the controller's row overlay (see
@@ -4132,46 +4503,7 @@ async function loadRows(ctx) {
 	const ids = await ctx.get(dbActionIdsSlot);
 	const table = asFetchTable(getActionTable(ctx));
 	if (!table) throw noTableError(ctx);
-	if (ids.length === 0) return [];
-	const fields = seedActionFields(ctx, table);
-	const idKeys = [];
-	const shapes = /* @__PURE__ */ new Map();
-	const dedupedIds = [];
-	const seenKeys = /* @__PURE__ */ new Set();
-	for (const id of ids) {
-		const sortedFields = Object.keys(id).toSorted();
-		const sig = sortedFields.join("");
-		let key = "";
-		for (const f of sortedFields) {
-			fields.add(f);
-			key += `${f}\x1f${stringifyScalar(id[f])}\x1e`;
-		}
-		idKeys.push(key);
-		if (!shapes.has(sig)) shapes.set(sig, sortedFields);
-		if (!seenKeys.has(key)) {
-			seenKeys.add(key);
-			dedupedIds.push(id);
-		}
-	}
-	const rows = await table.findMany({
-		filter: withOverlay({ $or: dedupedIds }, overlay),
-		controls: { $select: [...fields] }
-	});
-	const rowByKey = /* @__PURE__ */ new Map();
-	for (const row of rows) for (const sortedFields of shapes.values()) {
-		let key = "";
-		let ok = true;
-		for (const f of sortedFields) {
-			const v = row[f];
-			if (v === void 0) {
-				ok = false;
-				break;
-			}
-			key += `${f}\x1f${stringifyScalar(v)}\x1e`;
-		}
-		if (ok && !rowByKey.has(key)) rowByKey.set(key, row);
-	}
-	return ids.map((_, i) => rowByKey.get(idKeys[i]));
+	return findRowsByIds(table, ids, overlay, seedActionFields(ctx, table));
 }
 const dbActionRowSlot = cached((ctx) => loadRow(ctx));
 const dbActionRowsSlot = cached((ctx) => loadRows(ctx));
@@ -4193,9 +4525,8 @@ function buildGateInterceptor(opts) {
 		injectBoundTable(table);
 		await ctx.get(dbActionOverlaySlot);
 		if (level === "row") {
-			const verdicts = disabled([await ctx.get(dbActionRowSlot)]);
-			assertVerdictLength(action, verdicts, 1);
-			if (verdicts[0]) throw new ActionDisabledError(action, await ctx.get(dbActionIdSlot), void 0, [verdictReason(verdicts[0])]);
+			const verdict = judgeRow(action, disabled, await ctx.get(dbActionRowSlot));
+			if (verdict) throw new ActionDisabledError(action, await ctx.get(dbActionIdSlot), void 0, [verdictReason(verdict)]);
 			return;
 		}
 		await gateRows(ctx, action, disabled, onDisabledRows);
@@ -4213,11 +4544,7 @@ async function gateRows(ctx, action, disabled, onDisabledRows) {
 	const rows = await ctx.get(dbActionRowsSlot);
 	const existingRows = [];
 	for (const row of rows) if (row !== void 0) existingRows.push(row);
-	let verdicts;
-	if (disabled) {
-		verdicts = disabled(existingRows);
-		assertVerdictLength(action, verdicts, existingRows.length);
-	}
+	const verdicts = disabled ? judgeRows(action, disabled, existingRows) : void 0;
 	const failingIds = [];
 	const failingReasons = [];
 	const passingRows = [];
@@ -4249,7 +4576,8 @@ async function gateRows(ctx, action, disabled, onDisabledRows) {
 * `@DbActionRow*` handler of any other level: bound-table injection only):
 * runs the controller's `prepareRequest` (when defined, since 0.1.143),
 * injects the bound table and — only when the controller has a row overlay
-* (`transformOne` / `transformFilter` overridden, non-empty) — verifies the
+* for the action (`transformOne` / `transformFilter` overridden, or — since
+* 0.1.145 — an `actionRowScope` for it; non-empty) — verifies the
 * requested ids against it before the handler runs by loading the row(s)
 * the handler would get: `'row'` → the 404 of a missing row; `'rows'` →
 * out-of-scope and missing ids fail like disabled rows with no reason
@@ -4612,4 +4940,4 @@ const VALUE_HELP_CRUD_HANDLERS = Object.freeze({
 	one: ["runGetOne", "runGetOneComposite"]
 });
 //#endregion
-export { ActionDisabledError, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DB_CRUD_HANDLERS, DEFAULT_DB_SPACE, DbAction, DbActionDefault, DbActionID, DbActionIDs, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, VALUE_HELP_CRUD_HANDLERS, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };
+export { ActionDisabledError, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DB_CRUD_HANDLERS, DEFAULT_DB_SPACE, DbAction, DbActionDefault, DbActionID, DbActionIDs, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, VALUE_HELP_CRUD_HANDLERS, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, discoverRowLevelActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, getDbEndpoint, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };