@atscript/moost-db 0.1.140 → 0.1.141

package/dist/index.cjs

@@ -546,14 +546,18 @@ function resolveProp(type, field) {
 /**
 * Follows `def.ref` hop by hop until a prop without a `ref` (a primary key or
 * a plain column) is reached. Cycle-safe (visited on `<typeId>.<field>`) and
-* bounded by chain length.
+* bounded by chain length. Only chain hops count — a plain ref (`field: ""`,
+* a column typed with a named type) is the end of the chain. A hop into a
+* `@db.alias` type (a view's join alias, since 0.1.141) continues on the
+* aliased table / view — the alias is no value domain for a picker.
 */
 function resolveTerminalRef(def) {
 	const ref = def.ref;
-	if (!ref) return void 0;
+	if (!ref?.field) return void 0;
 	let type = ref.type();
 	let field = ref.field;
 	if (!type) return void 0;
+	type = (0, _atscript_db.aliasTargetOf)(type) ?? type;
 	let fk = def.metadata.has("db.rel.FK");
 	const visited = new Set([`${type.id ?? ""}.${field}`]);
 	for (;;) {
@@ -561,9 +565,10 @@ function resolveTerminalRef(def) {
 		if (!prop) break;
 		if (prop.metadata.has("db.rel.FK")) fk = true;
 		const next = prop.ref;
-		if (!next) break;
-		const nextType = next.type();
-		if (!nextType) break;
+		if (!next?.field) break;
+		const resolved = next.type();
+		if (!resolved) break;
+		const nextType = (0, _atscript_db.aliasTargetOf)(resolved) ?? resolved;
 		const key = `${nextType.id ?? ""}.${next.field}`;
 		if (visited.has(key)) break;
 		visited.add(key);
@@ -615,7 +620,7 @@ function walk(node, def, shallow) {
 			const sProp = sType.props[name];
 			if (!sProp) continue;
 			if (isNav(prop.metadata)) continue;
-			if (prop.ref && sProp.ref && !("type" in sProp.ref.type)) {
+			if (prop.ref?.field && sProp.ref && !("type" in sProp.ref.type)) {
 				const terminal = resolveTerminalRef(prop);
 				if (terminal) {
 					const direct = prop.ref.type();
@@ -732,9 +737,9 @@ let AsReadableController = class AsReadableController {
 	* The shallow shape emits `{ field, type: { id, metadata } }` for every FK,
 	* which carries the target's `db.http.path` so clients can resolve value-help
 	* URLs and lazy-fetch target `/meta` when deeper structure is needed. Nav
-	* props (`@db.rel.from` / `@db.rel.to` / `@db.rel.via`) are not `.ref` nodes
-	* and always expand fully regardless of `refDepth` — the write-payload shape
-	* clients need is unaffected.
+	* props (`@db.rel.from` / `@db.rel.to` / `@db.rel.via`) carry only a plain
+	* `ref` (`field: ""`) and their bodies always expand fully regardless of
+	* `refDepth` — the write-payload shape clients need is unaffected.
 	*
 	* Annotation whitelist: keeps `meta.*`, `expect.*`, and `db.rel.*`; strips
 	* other `db.*` (table, column, index, default, etc.). Override in subclass
@@ -973,10 +978,14 @@ AsReadableController = __decorate([UseValidationErrorTransform(), __decorateMeta
 ])], AsReadableController);
 //#endregion
 //#region src/actions/verdict.ts
-/** Assert that a `disabled` predicate returned a `boolean[]` of the expected length; throws HTTP 500 otherwise. */
+/** 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 _moostjs_event_http.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();
@@ -1017,7 +1026,8 @@ function computeStripFields(candidates, resolvedProjection) {
 	return strip;
 }
 /**
-* Sets `$actions` on every row and strips the columns fetched only for an
+* 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.
 */
@@ -1034,15 +1044,19 @@ function augmentRowsWithActions(args) {
 	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 v = verdicts[j];
-			if (v === void 0) {
-				names.push(candidates[j].envelope.info.name);
+			const name = candidates[j].envelope.info.name;
+			const verdict = verdicts[j]?.[i];
+			if (!verdict) {
+				names.push(name);
 				continue;
 			}
-			if (!v[i]) names.push(candidates[j].envelope.info.name);
+			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);
@@ -2433,6 +2447,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			if (geoIndexedPhysical.has(fd.physicalName)) entry.geo = true;
 			if (this._writeOnlySet.has(path)) entry.writeOnly = true;
 			if (cap.bucketable) entry.bucketable = true;
+			if (fd.derived) entry.derived = true;
 			fields[path] = entry;
 		}
 		return {
@@ -3116,6 +3131,7 @@ function assertExposed(app, models, options) {
 	}
 	const missing = [];
 	for (const model of models) {
+		if ((0, _atscript_db.aliasTargetOf)(model)) continue;
 		const httpPath = model.metadata.get("db.http.path");
 		if (!auditAll && httpPath === void 0) continue;
 		if (excluded.has(model) || exposed.has(model)) continue;
@@ -3127,31 +3143,58 @@ function assertExposed(app, models, options) {
 }
 //#endregion
 //#region src/actions/action-disabled-error.ts
-function buildMessage(action, ids) {
-	if (ids !== void 0) return `Action "${action}" is disabled for ${ids.length} of the selected rows`;
-	return `Action "${action}" is disabled for this row`;
+/** Distinct reasons quoted in a mixed `'rows'` message before `(+N more)`. */
+const MAX_LISTED_REASONS = 3;
+function sharedReason(reasons) {
+	const first = reasons[0];
+	if (first === null || first === void 0) return void 0;
+	return reasons.every((r) => r === first) ? first : void 0;
+}
+function rowsMessage(action, count, reasons) {
+	const base = `Action "${action}" is disabled for ${count} of the selected rows`;
+	const distinct = [...new Set(reasons.filter((r) => r !== null))];
+	if (distinct.length === 0) return base;
+	const listed = distinct.slice(0, MAX_LISTED_REASONS).join("; ");
+	const more = distinct.length - MAX_LISTED_REASONS;
+	return `${base}: ${listed}${more > 0 ? ` (+${more} more)` : ""}`;
 }
 /**
 * Thrown by the gate interceptor when `disabled` returns truthy. Composes
 * with Moost's existing error mapper to produce HTTP 409 with the wire body
 * defined by {@link ActionDisabledErrorBody}.
 *
-* - `'row'`-level rejection: pass `(action, id)` — the body emits `id`.
-* - `'rows'`-level rejection: pass `(action, undefined, ids)` — the body
-*   emits `ids` (the FULL list of failing IDs in reject mode; the FULL list
-*   of request IDs in skip mode with zero survivors).
+* - `'row'`-level rejection: pass `(action, id, undefined, [reason])` — the
+*   body emits `id` (+ `reason` when given).
+* - `'rows'`-level rejection: pass `(action, undefined, ids, reasons?)` — the
+*   body emits `ids` (the FULL list of failing IDs in reject mode; the FULL
+*   list of request IDs in skip mode with zero survivors) and, when any
+*   reason exists, `reasons` aligned with `ids`.
+*
+* `reasons` entries are verdict reasons (`verdictReason`): anything but a
+* non-empty string counts as "no reason".
 */
 var ActionDisabledError = class extends _moostjs_event_http.HttpError {
 	name = "ActionDisabledError";
-	constructor(action, id, ids) {
+	constructor(action, id, ids, reasons) {
 		const body = {
 			name: "ActionDisabledError",
-			message: buildMessage(action, ids),
+			message: "",
 			statusCode: 409,
 			action
 		};
-		if (ids !== void 0) body.ids = ids;
-		else if (id !== void 0) body.id = id;
+		if (ids !== void 0) {
+			const aligned = ids.map((_, i) => verdictReason(reasons?.[i]) ?? null);
+			const reason = sharedReason(aligned);
+			body.message = reason ?? rowsMessage(action, ids.length, aligned);
+			body.ids = ids;
+			if (reason !== void 0) body.reason = reason;
+			if (aligned.some((r) => r !== null)) body.reasons = aligned;
+		} else {
+			const reason = verdictReason(reasons?.[0]);
+			body.message = reason ?? `Action "${action}" is disabled for this row`;
+			if (id !== void 0) body.id = id;
+			if (reason !== void 0) body.reason = reason;
+		}
 		super(409, body);
 	}
 };
@@ -3442,7 +3485,7 @@ function buildGateInterceptor(opts) {
 		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));
+			if (verdicts[0]) throw new ActionDisabledError(action, await ctx.get(dbActionIdSlot), void 0, [verdictReason(verdicts[0])]);
 			return;
 		}
 		const ids = await ctx.get(dbActionIdsSlot);
@@ -3452,26 +3495,30 @@ function buildGateInterceptor(opts) {
 		const verdicts = disabled(existingRows);
 		assertVerdictLength(action, verdicts, existingRows.length);
 		const failingIds = [];
+		const failingReasons = [];
 		const passingRows = [];
 		const passingIds = [];
 		let verdictIndex = 0;
 		for (let i = 0; i < ids.length; i++) {
 			const row = rows[i];
-			if (row === void 0 || verdicts[verdictIndex++]) failingIds.push(ids[i]);
-			else {
+			const verdict = row === void 0 ? void 0 : verdicts[verdictIndex++];
+			if (row === void 0 || verdict) {
+				failingIds.push(ids[i]);
+				failingReasons.push(verdictReason(verdict));
+			} else {
 				passingRows.push(row);
 				passingIds.push(ids[i]);
 			}
 		}
 		if (onDisabledRows === "skip") {
-			if (passingRows.length === 0) throw new ActionDisabledError(action, void 0, [...ids]);
+			if (passingRows.length === 0) throw new ActionDisabledError(action, void 0, [...ids], failingReasons);
 			if (failingIds.length > 0) {
 				ctx.set(dbActionRowsSlot, Promise.resolve(passingRows));
 				ctx.set(dbActionIdsSlot, Promise.resolve(passingIds));
 			}
 			return;
 		}
-		if (failingIds.length > 0) throw new ActionDisabledError(action, void 0, failingIds);
+		if (failingIds.length > 0) throw new ActionDisabledError(action, void 0, failingIds, failingReasons);
 	}, GATE_PRIORITY);
 }
 /** Thin interceptor for `@DbActionRow*` without `disabled` — injects only the bound table. */
@@ -3760,7 +3807,8 @@ function InputForm(formType, validatorOpts) {
 /**
 * Lift a per-row predicate into the batch shape required by
 * `@DbAction` opts.`disabled` and class-level dict `disabled`. Polarity is
-* preserved — `true` from `fn` means the action is disabled for that row.
+* preserved — `true` from `fn` means the action is disabled for that row; a
+* non-empty string disables it with that reason.
 *
 * ```ts
 * @DbAction<Order>('archive', {

package/dist/index.d.cts

@@ -77,9 +77,9 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * The shallow shape emits `{ field, type: { id, metadata } }` for every FK,
    * which carries the target's `db.http.path` so clients can resolve value-help
    * URLs and lazy-fetch target `/meta` when deeper structure is needed. Nav
-   * props (`@db.rel.from` / `@db.rel.to` / `@db.rel.via`) are not `.ref` nodes
-   * and always expand fully regardless of `refDepth` — the write-payload shape
-   * clients need is unaffected.
+   * props (`@db.rel.from` / `@db.rel.to` / `@db.rel.via`) carry only a plain
+   * `ref` (`field: ""`) and their bodies always expand fully regardless of
+   * `refDepth` — the write-payload shape clients need is unaffected.
    *
    * Annotation whitelist: keeps `meta.*`, `expect.*`, and `db.rel.*`; strips
    * other `db.*` (table, column, index, default, etc.). Override in subclass
@@ -589,7 +589,7 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    *
    * Convention (not enforced): name decoration keys with a `$` prefix, like
    * `$actions` and `$distance`, so they can never collide with a field name.
-   * Do not overwrite `$actions`. Columns the
+   * Do not overwrite `$actions` or `$disabledReasons`. Columns the
    * hook needs but the client did not select must be added in
    * {@link transformProjection} — they are then part of the response.
    *
@@ -1006,6 +1006,15 @@ declare class AsJsonValueHelpController<T extends TAtscriptAnnotatedType = TAtsc
 }
 //#endregion
 //#region src/actions/types.d.ts
+/**
+ * One entry of a `disabled` predicate's result. Truthy = the action is
+ * disabled for that row; falsy (`false`, `""`) = enabled. A non-empty string
+ * disables the action AND carries a human-readable reason — surfaced in the
+ * 409 `ActionDisabledError` message/body and in the row's `$disabledReasons`.
+ *
+ * @since 0.1.141 (`string`)
+ */
+type TDbActionDisabledVerdict = boolean | string;
 /** `'rows'`-level batch policy — controls whether failing rows reject or are filtered out. */
 type TOnDisabledRows = "reject" | "skip";
 /**
@@ -1034,15 +1043,17 @@ interface WithGate<TRow, R extends readonly FlatKey<TRow>[]> {
    */
   requiredFields: R;
   /**
-   * Sync batch gate predicate — returns a parallel `boolean[]` aligned with
-   * the input. `true` = disabled for the corresponding row. The `rows`
+   * Sync batch gate predicate — returns a parallel array aligned with the
+   * input. Per entry: truthy = disabled for the corresponding row; a
+   * non-empty string also gives the reason (see
+   * {@link TDbActionDisabledVerdict}). The `rows`
    * argument is type-narrowed to `Pick<FlatOf<TRow>, R[number]>[]`; reading
    * a field not listed in `requiredFields` is a compile error.
    *
    * Promise return is NOT permitted — the predicate is consumed in the
    * same tick by the gate and the augmenter.
    */
-  disabled?: (rows: DisabledRowsArg<TRow, R>) => boolean[];
+  disabled?: (rows: DisabledRowsArg<TRow, R>) => TDbActionDisabledVerdict[];
   /**
    * `'rows'`-level batch policy. Default `'reject'`.
    *
@@ -1062,7 +1073,7 @@ interface WithGate<TRow, R extends readonly FlatKey<TRow>[]> {
  */
 interface LooseGate {
   requiredFields?: string[];
-  disabled?: (rows: any[]) => boolean[];
+  disabled?: (rows: any[]) => TDbActionDisabledVerdict[];
   onDisabledRows?: TOnDisabledRows;
 }
 type GateOpts<TRow, R extends readonly FlatKey<TRow>[]> = unknown extends TRow ? LooseGate : NoGate | WithGate<TRow, R>;
@@ -1700,17 +1711,21 @@ declare const useDbActionInput: import("@wooksjs/event-core").WookComposable<{
  * Wire-body shape for server-side gate rejections. The `name` discriminator
  * lets `@atscript/db-client` recognise the response and construct the typed
  * `ActionDisabledError` subclass. The shape extends Moost's standard
- * `ServerError` envelope (`{ message, statusCode, errors? }`) with three
- * additional fields:
+ * `ServerError` envelope (`{ message, statusCode, errors? }`) with:
  *
  * - `name: 'ActionDisabledError'` — discriminator the client matches.
  * - `action` — the `@DbAction` name that rejected the request.
  * - `id?` — present only for `'row'`-level rejections.
  * - `ids?` — present only for `'rows'`-level rejections.
+ * - `reason?` — the reason shared by every rejected row, when the
+ *   `disabled` predicate returned one (since 0.1.141).
+ * - `reasons?` — `'rows'` level only: index-aligned with `ids`, `null` where
+ *   that row carries no reason. Present only when at least one reason exists
+ *   (since 0.1.141).
  *
  * `message` is populated with a human-readable string so generic
  * `ClientError` consumers (which read `body.message`) still get something
- * useful without typed-catch dispatch.
+ * useful without typed-catch dispatch — the reason itself when there is one.
  */
 interface ActionDisabledErrorBody {
   name: "ActionDisabledError";
@@ -1719,27 +1734,37 @@ interface ActionDisabledErrorBody {
   action: string;
   id?: Record<string, unknown>;
   ids?: Record<string, unknown>[];
+  /** @since 0.1.141 */
+  reason?: string;
+  /** @since 0.1.141 */
+  reasons?: (string | null)[];
 }
 /**
  * Thrown by the gate interceptor when `disabled` returns truthy. Composes
  * with Moost's existing error mapper to produce HTTP 409 with the wire body
  * defined by {@link ActionDisabledErrorBody}.
  *
- * - `'row'`-level rejection: pass `(action, id)` — the body emits `id`.
- * - `'rows'`-level rejection: pass `(action, undefined, ids)` — the body
- *   emits `ids` (the FULL list of failing IDs in reject mode; the FULL list
- *   of request IDs in skip mode with zero survivors).
+ * - `'row'`-level rejection: pass `(action, id, undefined, [reason])` — the
+ *   body emits `id` (+ `reason` when given).
+ * - `'rows'`-level rejection: pass `(action, undefined, ids, reasons?)` — the
+ *   body emits `ids` (the FULL list of failing IDs in reject mode; the FULL
+ *   list of request IDs in skip mode with zero survivors) and, when any
+ *   reason exists, `reasons` aligned with `ids`.
+ *
+ * `reasons` entries are verdict reasons (`verdictReason`): anything but a
+ * non-empty string counts as "no reason".
  */
 declare class ActionDisabledError extends HttpError<ActionDisabledErrorBody> {
   name: string;
-  constructor(action: string, id?: Record<string, unknown>, ids?: Record<string, unknown>[]);
+  constructor(action: string, id?: Record<string, unknown>, ids?: Record<string, unknown>[], reasons?: readonly (string | null | undefined)[]);
 }
 //#endregion
 //#region src/actions/per-row.d.ts
 /**
  * Lift a per-row predicate into the batch shape required by
  * `@DbAction` opts.`disabled` and class-level dict `disabled`. Polarity is
- * preserved — `true` from `fn` means the action is disabled for that row.
+ * preserved — `true` from `fn` means the action is disabled for that row; a
+ * non-empty string disables it with that reason.
  *
  * ```ts
  * @DbAction<Order>('archive', {
@@ -1748,7 +1773,7 @@ declare class ActionDisabledError extends HttpError<ActionDisabledErrorBody> {
  * })
  * ```
  */
-declare const perRow: <TRow>(fn: (row: TRow) => boolean) => (rows: TRow[]) => boolean[];
+declare const perRow: <TRow>(fn: (row: TRow) => TDbActionDisabledVerdict) => (rows: TRow[]) => TDbActionDisabledVerdict[];
 //#endregion
 //#region src/permissions/crud-controls.d.ts
 declare const QUERY_CONTROLS: readonly string[];
@@ -1785,7 +1810,10 @@ declare function resolveProp(type: TAtscriptAnnotatedType, field: string): TAtsc
 /**
  * Follows `def.ref` hop by hop until a prop without a `ref` (a primary key or
  * a plain column) is reached. Cycle-safe (visited on `<typeId>.<field>`) and
- * bounded by chain length.
+ * bounded by chain length. Only chain hops count — a plain ref (`field: ""`,
+ * a column typed with a named type) is the end of the chain. A hop into a
+ * `@db.alias` type (a view's join alias, since 0.1.141) continues on the
+ * aliased table / view — the alias is no value domain for a picker.
  */
 declare function resolveTerminalRef(def: TAtscriptAnnotatedType): TTerminalRef | undefined;
 /**
@@ -1801,4 +1829,4 @@ declare function resolveTerminalRef(def: TAtscriptAnnotatedType): TTerminalRef |
  */
 declare function applyTerminalRefs(serialized: TSerializedAnnotatedType, runtime: TAtscriptAnnotatedType, options: TSerializeOptions): TSerializedAnnotatedType;
 //#endregion
-export { ActionDisabledError, type ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbClassActionMeta, TDbDecorateContext, TDbDecorateEndpoint, type TDbRemoveGuardContext, type TDbWriteAction, type TDbWriteGuardContext, type TFieldCapability, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };
+export { ActionDisabledError, type ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionDisabledVerdict, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbClassActionMeta, TDbDecorateContext, TDbDecorateEndpoint, type TDbRemoveGuardContext, type TDbWriteAction, type TDbWriteGuardContext, type TFieldCapability, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };

package/dist/index.d.mts

@@ -77,9 +77,9 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * The shallow shape emits `{ field, type: { id, metadata } }` for every FK,
    * which carries the target's `db.http.path` so clients can resolve value-help
    * URLs and lazy-fetch target `/meta` when deeper structure is needed. Nav
-   * props (`@db.rel.from` / `@db.rel.to` / `@db.rel.via`) are not `.ref` nodes
-   * and always expand fully regardless of `refDepth` — the write-payload shape
-   * clients need is unaffected.
+   * props (`@db.rel.from` / `@db.rel.to` / `@db.rel.via`) carry only a plain
+   * `ref` (`field: ""`) and their bodies always expand fully regardless of
+   * `refDepth` — the write-payload shape clients need is unaffected.
    *
    * Annotation whitelist: keeps `meta.*`, `expect.*`, and `db.rel.*`; strips
    * other `db.*` (table, column, index, default, etc.). Override in subclass
@@ -589,7 +589,7 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    *
    * Convention (not enforced): name decoration keys with a `$` prefix, like
    * `$actions` and `$distance`, so they can never collide with a field name.
-   * Do not overwrite `$actions`. Columns the
+   * Do not overwrite `$actions` or `$disabledReasons`. Columns the
    * hook needs but the client did not select must be added in
    * {@link transformProjection} — they are then part of the response.
    *
@@ -1006,6 +1006,15 @@ declare class AsJsonValueHelpController<T extends TAtscriptAnnotatedType = TAtsc
 }
 //#endregion
 //#region src/actions/types.d.ts
+/**
+ * One entry of a `disabled` predicate's result. Truthy = the action is
+ * disabled for that row; falsy (`false`, `""`) = enabled. A non-empty string
+ * disables the action AND carries a human-readable reason — surfaced in the
+ * 409 `ActionDisabledError` message/body and in the row's `$disabledReasons`.
+ *
+ * @since 0.1.141 (`string`)
+ */
+type TDbActionDisabledVerdict = boolean | string;
 /** `'rows'`-level batch policy — controls whether failing rows reject or are filtered out. */
 type TOnDisabledRows = "reject" | "skip";
 /**
@@ -1034,15 +1043,17 @@ interface WithGate<TRow, R extends readonly FlatKey<TRow>[]> {
    */
   requiredFields: R;
   /**
-   * Sync batch gate predicate — returns a parallel `boolean[]` aligned with
-   * the input. `true` = disabled for the corresponding row. The `rows`
+   * Sync batch gate predicate — returns a parallel array aligned with the
+   * input. Per entry: truthy = disabled for the corresponding row; a
+   * non-empty string also gives the reason (see
+   * {@link TDbActionDisabledVerdict}). The `rows`
    * argument is type-narrowed to `Pick<FlatOf<TRow>, R[number]>[]`; reading
    * a field not listed in `requiredFields` is a compile error.
    *
    * Promise return is NOT permitted — the predicate is consumed in the
    * same tick by the gate and the augmenter.
    */
-  disabled?: (rows: DisabledRowsArg<TRow, R>) => boolean[];
+  disabled?: (rows: DisabledRowsArg<TRow, R>) => TDbActionDisabledVerdict[];
   /**
    * `'rows'`-level batch policy. Default `'reject'`.
    *
@@ -1062,7 +1073,7 @@ interface WithGate<TRow, R extends readonly FlatKey<TRow>[]> {
  */
 interface LooseGate {
   requiredFields?: string[];
-  disabled?: (rows: any[]) => boolean[];
+  disabled?: (rows: any[]) => TDbActionDisabledVerdict[];
   onDisabledRows?: TOnDisabledRows;
 }
 type GateOpts<TRow, R extends readonly FlatKey<TRow>[]> = unknown extends TRow ? LooseGate : NoGate | WithGate<TRow, R>;
@@ -1700,17 +1711,21 @@ declare const useDbActionInput: import("@wooksjs/event-core").WookComposable<{
  * Wire-body shape for server-side gate rejections. The `name` discriminator
  * lets `@atscript/db-client` recognise the response and construct the typed
  * `ActionDisabledError` subclass. The shape extends Moost's standard
- * `ServerError` envelope (`{ message, statusCode, errors? }`) with three
- * additional fields:
+ * `ServerError` envelope (`{ message, statusCode, errors? }`) with:
  *
  * - `name: 'ActionDisabledError'` — discriminator the client matches.
  * - `action` — the `@DbAction` name that rejected the request.
  * - `id?` — present only for `'row'`-level rejections.
  * - `ids?` — present only for `'rows'`-level rejections.
+ * - `reason?` — the reason shared by every rejected row, when the
+ *   `disabled` predicate returned one (since 0.1.141).
+ * - `reasons?` — `'rows'` level only: index-aligned with `ids`, `null` where
+ *   that row carries no reason. Present only when at least one reason exists
+ *   (since 0.1.141).
  *
  * `message` is populated with a human-readable string so generic
  * `ClientError` consumers (which read `body.message`) still get something
- * useful without typed-catch dispatch.
+ * useful without typed-catch dispatch — the reason itself when there is one.
  */
 interface ActionDisabledErrorBody {
   name: "ActionDisabledError";
@@ -1719,27 +1734,37 @@ interface ActionDisabledErrorBody {
   action: string;
   id?: Record<string, unknown>;
   ids?: Record<string, unknown>[];
+  /** @since 0.1.141 */
+  reason?: string;
+  /** @since 0.1.141 */
+  reasons?: (string | null)[];
 }
 /**
  * Thrown by the gate interceptor when `disabled` returns truthy. Composes
  * with Moost's existing error mapper to produce HTTP 409 with the wire body
  * defined by {@link ActionDisabledErrorBody}.
  *
- * - `'row'`-level rejection: pass `(action, id)` — the body emits `id`.
- * - `'rows'`-level rejection: pass `(action, undefined, ids)` — the body
- *   emits `ids` (the FULL list of failing IDs in reject mode; the FULL list
- *   of request IDs in skip mode with zero survivors).
+ * - `'row'`-level rejection: pass `(action, id, undefined, [reason])` — the
+ *   body emits `id` (+ `reason` when given).
+ * - `'rows'`-level rejection: pass `(action, undefined, ids, reasons?)` — the
+ *   body emits `ids` (the FULL list of failing IDs in reject mode; the FULL
+ *   list of request IDs in skip mode with zero survivors) and, when any
+ *   reason exists, `reasons` aligned with `ids`.
+ *
+ * `reasons` entries are verdict reasons (`verdictReason`): anything but a
+ * non-empty string counts as "no reason".
  */
 declare class ActionDisabledError extends HttpError<ActionDisabledErrorBody> {
   name: string;
-  constructor(action: string, id?: Record<string, unknown>, ids?: Record<string, unknown>[]);
+  constructor(action: string, id?: Record<string, unknown>, ids?: Record<string, unknown>[], reasons?: readonly (string | null | undefined)[]);
 }
 //#endregion
 //#region src/actions/per-row.d.ts
 /**
  * Lift a per-row predicate into the batch shape required by
  * `@DbAction` opts.`disabled` and class-level dict `disabled`. Polarity is
- * preserved — `true` from `fn` means the action is disabled for that row.
+ * preserved — `true` from `fn` means the action is disabled for that row; a
+ * non-empty string disables it with that reason.
  *
  * ```ts
  * @DbAction<Order>('archive', {
@@ -1748,7 +1773,7 @@ declare class ActionDisabledError extends HttpError<ActionDisabledErrorBody> {
  * })
  * ```
  */
-declare const perRow: <TRow>(fn: (row: TRow) => boolean) => (rows: TRow[]) => boolean[];
+declare const perRow: <TRow>(fn: (row: TRow) => TDbActionDisabledVerdict) => (rows: TRow[]) => TDbActionDisabledVerdict[];
 //#endregion
 //#region src/permissions/crud-controls.d.ts
 declare const QUERY_CONTROLS: readonly string[];
@@ -1785,7 +1810,10 @@ declare function resolveProp(type: TAtscriptAnnotatedType, field: string): TAtsc
 /**
  * Follows `def.ref` hop by hop until a prop without a `ref` (a primary key or
  * a plain column) is reached. Cycle-safe (visited on `<typeId>.<field>`) and
- * bounded by chain length.
+ * bounded by chain length. Only chain hops count — a plain ref (`field: ""`,
+ * a column typed with a named type) is the end of the chain. A hop into a
+ * `@db.alias` type (a view's join alias, since 0.1.141) continues on the
+ * aliased table / view — the alias is no value domain for a picker.
  */
 declare function resolveTerminalRef(def: TAtscriptAnnotatedType): TTerminalRef | undefined;
 /**
@@ -1801,4 +1829,4 @@ declare function resolveTerminalRef(def: TAtscriptAnnotatedType): TTerminalRef |
  */
 declare function applyTerminalRefs(serialized: TSerializedAnnotatedType, runtime: TAtscriptAnnotatedType, options: TSerializeOptions): TSerializedAnnotatedType;
 //#endregion
-export { ActionDisabledError, type ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbClassActionMeta, TDbDecorateContext, TDbDecorateEndpoint, type TDbRemoveGuardContext, type TDbWriteAction, type TDbWriteGuardContext, type TFieldCapability, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };
+export { ActionDisabledError, type ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionDisabledVerdict, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbClassActionMeta, TDbDecorateContext, TDbDecorateEndpoint, type TDbRemoveGuardContext, type TDbWriteAction, type TDbWriteGuardContext, type TFieldCapability, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };

package/dist/index.mjs

@@ -3,7 +3,7 @@ import { ValidatorError, defineAnnotatedType, isAnnotatedType, serializeAnnotate
 import { Body, Delete, Get, HttpError, Patch, Post, Put, Query, Url } from "@moostjs/event-http";
 import { ApplyDecorators, Controller, Inherit, Inject, Intercept, Moost, Optional, Param, Provide, Resolve, TInterceptorPriority, defineBeforeInterceptor, defineInterceptor, getMoostMate, useControllerContext } from "moost";
 import { parseUrl } from "@uniqu/url";
-import { ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, DbError, ENCRYPTED_REASON, acceptedOperatorsHint, bucketSourceVerdict, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, collectQueryPaths as collectQueryPaths$1, findAncestorInSet, isJsonValueField, isPlainObject, narrowerFilterOps, normalizeComputedSelect, reconcileCas, unsupportedOperatorMessage } from "@atscript/db";
+import { ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, DbError, ENCRYPTED_REASON, acceptedOperatorsHint, aliasTargetOf, bucketSourceVerdict, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, collectQueryPaths as collectQueryPaths$1, findAncestorInSet, isJsonValueField, isPlainObject, narrowerFilterOps, normalizeComputedSelect, reconcileCas, unsupportedOperatorMessage } from "@atscript/db";
 import { BUCKET_UNITS } from "@uniqu/core";
 import { buildMemoryPredicate, projectRow, sortRows } from "@atscript/db-memory";
 import { cached, current, defineWook, key } from "@wooksjs/event-core";
@@ -545,14 +545,18 @@ function resolveProp(type, field) {
 /**
 * Follows `def.ref` hop by hop until a prop without a `ref` (a primary key or
 * a plain column) is reached. Cycle-safe (visited on `<typeId>.<field>`) and
-* bounded by chain length.
+* bounded by chain length. Only chain hops count — a plain ref (`field: ""`,
+* a column typed with a named type) is the end of the chain. A hop into a
+* `@db.alias` type (a view's join alias, since 0.1.141) continues on the
+* aliased table / view — the alias is no value domain for a picker.
 */
 function resolveTerminalRef(def) {
 	const ref = def.ref;
-	if (!ref) return void 0;
+	if (!ref?.field) return void 0;
 	let type = ref.type();
 	let field = ref.field;
 	if (!type) return void 0;
+	type = aliasTargetOf(type) ?? type;
 	let fk = def.metadata.has("db.rel.FK");
 	const visited = new Set([`${type.id ?? ""}.${field}`]);
 	for (;;) {
@@ -560,9 +564,10 @@ function resolveTerminalRef(def) {
 		if (!prop) break;
 		if (prop.metadata.has("db.rel.FK")) fk = true;
 		const next = prop.ref;
-		if (!next) break;
-		const nextType = next.type();
-		if (!nextType) break;
+		if (!next?.field) break;
+		const resolved = next.type();
+		if (!resolved) break;
+		const nextType = aliasTargetOf(resolved) ?? resolved;
 		const key = `${nextType.id ?? ""}.${next.field}`;
 		if (visited.has(key)) break;
 		visited.add(key);
@@ -614,7 +619,7 @@ function walk(node, def, shallow) {
 			const sProp = sType.props[name];
 			if (!sProp) continue;
 			if (isNav(prop.metadata)) continue;
-			if (prop.ref && sProp.ref && !("type" in sProp.ref.type)) {
+			if (prop.ref?.field && sProp.ref && !("type" in sProp.ref.type)) {
 				const terminal = resolveTerminalRef(prop);
 				if (terminal) {
 					const direct = prop.ref.type();
@@ -731,9 +736,9 @@ let AsReadableController = class AsReadableController {
 	* The shallow shape emits `{ field, type: { id, metadata } }` for every FK,
 	* which carries the target's `db.http.path` so clients can resolve value-help
 	* URLs and lazy-fetch target `/meta` when deeper structure is needed. Nav
-	* props (`@db.rel.from` / `@db.rel.to` / `@db.rel.via`) are not `.ref` nodes
-	* and always expand fully regardless of `refDepth` — the write-payload shape
-	* clients need is unaffected.
+	* props (`@db.rel.from` / `@db.rel.to` / `@db.rel.via`) carry only a plain
+	* `ref` (`field: ""`) and their bodies always expand fully regardless of
+	* `refDepth` — the write-payload shape clients need is unaffected.
 	*
 	* Annotation whitelist: keeps `meta.*`, `expect.*`, and `db.rel.*`; strips
 	* other `db.*` (table, column, index, default, etc.). Override in subclass
@@ -972,10 +977,14 @@ AsReadableController = __decorate([UseValidationErrorTransform(), __decorateMeta
 ])], AsReadableController);
 //#endregion
 //#region src/actions/verdict.ts
-/** Assert that a `disabled` predicate returned a `boolean[]` of the expected length; throws HTTP 500 otherwise. */
+/** 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();
@@ -1016,7 +1025,8 @@ function computeStripFields(candidates, resolvedProjection) {
 	return strip;
 }
 /**
-* Sets `$actions` on every row and strips the columns fetched only for an
+* 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.
 */
@@ -1033,15 +1043,19 @@ function augmentRowsWithActions(args) {
 	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 v = verdicts[j];
-			if (v === void 0) {
-				names.push(candidates[j].envelope.info.name);
+			const name = candidates[j].envelope.info.name;
+			const verdict = verdicts[j]?.[i];
+			if (!verdict) {
+				names.push(name);
 				continue;
 			}
-			if (!v[i]) names.push(candidates[j].envelope.info.name);
+			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);
@@ -2432,6 +2446,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			if (geoIndexedPhysical.has(fd.physicalName)) entry.geo = true;
 			if (this._writeOnlySet.has(path)) entry.writeOnly = true;
 			if (cap.bucketable) entry.bucketable = true;
+			if (fd.derived) entry.derived = true;
 			fields[path] = entry;
 		}
 		return {
@@ -3115,6 +3130,7 @@ function assertExposed(app, models, options) {
 	}
 	const missing = [];
 	for (const model of models) {
+		if (aliasTargetOf(model)) continue;
 		const httpPath = model.metadata.get("db.http.path");
 		if (!auditAll && httpPath === void 0) continue;
 		if (excluded.has(model) || exposed.has(model)) continue;
@@ -3126,31 +3142,58 @@ function assertExposed(app, models, options) {
 }
 //#endregion
 //#region src/actions/action-disabled-error.ts
-function buildMessage(action, ids) {
-	if (ids !== void 0) return `Action "${action}" is disabled for ${ids.length} of the selected rows`;
-	return `Action "${action}" is disabled for this row`;
+/** Distinct reasons quoted in a mixed `'rows'` message before `(+N more)`. */
+const MAX_LISTED_REASONS = 3;
+function sharedReason(reasons) {
+	const first = reasons[0];
+	if (first === null || first === void 0) return void 0;
+	return reasons.every((r) => r === first) ? first : void 0;
+}
+function rowsMessage(action, count, reasons) {
+	const base = `Action "${action}" is disabled for ${count} of the selected rows`;
+	const distinct = [...new Set(reasons.filter((r) => r !== null))];
+	if (distinct.length === 0) return base;
+	const listed = distinct.slice(0, MAX_LISTED_REASONS).join("; ");
+	const more = distinct.length - MAX_LISTED_REASONS;
+	return `${base}: ${listed}${more > 0 ? ` (+${more} more)` : ""}`;
 }
 /**
 * Thrown by the gate interceptor when `disabled` returns truthy. Composes
 * with Moost's existing error mapper to produce HTTP 409 with the wire body
 * defined by {@link ActionDisabledErrorBody}.
 *
-* - `'row'`-level rejection: pass `(action, id)` — the body emits `id`.
-* - `'rows'`-level rejection: pass `(action, undefined, ids)` — the body
-*   emits `ids` (the FULL list of failing IDs in reject mode; the FULL list
-*   of request IDs in skip mode with zero survivors).
+* - `'row'`-level rejection: pass `(action, id, undefined, [reason])` — the
+*   body emits `id` (+ `reason` when given).
+* - `'rows'`-level rejection: pass `(action, undefined, ids, reasons?)` — the
+*   body emits `ids` (the FULL list of failing IDs in reject mode; the FULL
+*   list of request IDs in skip mode with zero survivors) and, when any
+*   reason exists, `reasons` aligned with `ids`.
+*
+* `reasons` entries are verdict reasons (`verdictReason`): anything but a
+* non-empty string counts as "no reason".
 */
 var ActionDisabledError = class extends HttpError {
 	name = "ActionDisabledError";
-	constructor(action, id, ids) {
+	constructor(action, id, ids, reasons) {
 		const body = {
 			name: "ActionDisabledError",
-			message: buildMessage(action, ids),
+			message: "",
 			statusCode: 409,
 			action
 		};
-		if (ids !== void 0) body.ids = ids;
-		else if (id !== void 0) body.id = id;
+		if (ids !== void 0) {
+			const aligned = ids.map((_, i) => verdictReason(reasons?.[i]) ?? null);
+			const reason = sharedReason(aligned);
+			body.message = reason ?? rowsMessage(action, ids.length, aligned);
+			body.ids = ids;
+			if (reason !== void 0) body.reason = reason;
+			if (aligned.some((r) => r !== null)) body.reasons = aligned;
+		} else {
+			const reason = verdictReason(reasons?.[0]);
+			body.message = reason ?? `Action "${action}" is disabled for this row`;
+			if (id !== void 0) body.id = id;
+			if (reason !== void 0) body.reason = reason;
+		}
 		super(409, body);
 	}
 };
@@ -3441,7 +3484,7 @@ function buildGateInterceptor(opts) {
 		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));
+			if (verdicts[0]) throw new ActionDisabledError(action, await ctx.get(dbActionIdSlot), void 0, [verdictReason(verdicts[0])]);
 			return;
 		}
 		const ids = await ctx.get(dbActionIdsSlot);
@@ -3451,26 +3494,30 @@ function buildGateInterceptor(opts) {
 		const verdicts = disabled(existingRows);
 		assertVerdictLength(action, verdicts, existingRows.length);
 		const failingIds = [];
+		const failingReasons = [];
 		const passingRows = [];
 		const passingIds = [];
 		let verdictIndex = 0;
 		for (let i = 0; i < ids.length; i++) {
 			const row = rows[i];
-			if (row === void 0 || verdicts[verdictIndex++]) failingIds.push(ids[i]);
-			else {
+			const verdict = row === void 0 ? void 0 : verdicts[verdictIndex++];
+			if (row === void 0 || verdict) {
+				failingIds.push(ids[i]);
+				failingReasons.push(verdictReason(verdict));
+			} else {
 				passingRows.push(row);
 				passingIds.push(ids[i]);
 			}
 		}
 		if (onDisabledRows === "skip") {
-			if (passingRows.length === 0) throw new ActionDisabledError(action, void 0, [...ids]);
+			if (passingRows.length === 0) throw new ActionDisabledError(action, void 0, [...ids], failingReasons);
 			if (failingIds.length > 0) {
 				ctx.set(dbActionRowsSlot, Promise.resolve(passingRows));
 				ctx.set(dbActionIdsSlot, Promise.resolve(passingIds));
 			}
 			return;
 		}
-		if (failingIds.length > 0) throw new ActionDisabledError(action, void 0, failingIds);
+		if (failingIds.length > 0) throw new ActionDisabledError(action, void 0, failingIds, failingReasons);
 	}, GATE_PRIORITY);
 }
 /** Thin interceptor for `@DbActionRow*` without `disabled` — injects only the bound table. */
@@ -3759,7 +3806,8 @@ function InputForm(formType, validatorOpts) {
 /**
 * Lift a per-row predicate into the batch shape required by
 * `@DbAction` opts.`disabled` and class-level dict `disabled`. Polarity is
-* preserved — `true` from `fn` means the action is disabled for that row.
+* preserved — `true` from `fn` means the action is disabled for that row; a
+* non-empty string disables it with that reason.
 *
 * ```ts
 * @DbAction<Order>('archive', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/moost-db",
-  "version": "0.1.140",
+  "version": "0.1.141",
   "description": "Generic database controller for Moost with Atscript.",
   "keywords": [
     "annotations",
@@ -44,27 +44,27 @@
   },
   "dependencies": {
     "@uniqu/url": "^0.1.11",
-    "@atscript/db-memory": "^0.1.140"
+    "@atscript/db-memory": "^0.1.141"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.92",
-    "@atscript/typescript": "^0.1.92",
+    "@atscript/core": "^0.1.95",
+    "@atscript/typescript": "^0.1.95",
     "@moostjs/event-http": "^0.6.37",
     "@uniqu/core": "^0.1.11",
     "@wooksjs/event-core": "^0.7.23",
     "@wooksjs/event-http": "^0.7.23",
     "@wooksjs/http-body": "^0.7.23",
     "moost": "^0.6.37",
-    "unplugin-atscript": "^0.1.92"
+    "unplugin-atscript": "^0.1.95"
   },
   "peerDependencies": {
-    "@atscript/typescript": "^0.1.92",
+    "@atscript/typescript": "^0.1.95",
     "@moostjs/event-http": "^0.6.37",
     "@uniqu/core": "^0.1.11",
     "@wooksjs/event-core": "^0.7.23",
     "@wooksjs/http-body": "^0.7.23",
     "moost": "^0.6.37",
-    "@atscript/db": "^0.1.140"
+    "@atscript/db": "^0.1.141"
   },
   "scripts": {
     "postinstall": "asc -f dts",