@atscript/moost-db 0.1.57 → 0.1.58

package/dist/index.mjs

@@ -1,8 +1,9 @@
 import { ValidatorError, defineAnnotatedType, serializeAnnotatedType, throwFeatureDisabled } from "@atscript/typescript/utils";
 import { Body, Delete, Get, HttpError, Patch, Post, Put, Query, Url } from "@moostjs/event-http";
-import { ApplyDecorators, Controller, Inherit, Inject, Intercept, Moost, Param, Provide, Resolve, TInterceptorPriority, defineInterceptor, getMoostMate, useControllerContext } from "moost";
+import { ApplyDecorators, Controller, Inherit, Inject, Intercept, Moost, Param, Provide, Resolve, TInterceptorPriority, defineBeforeInterceptor, defineInterceptor, getMoostMate, useControllerContext } from "moost";
 import { parseUrl } from "@uniqu/url";
 import { DbError } from "@atscript/db";
+import { cached, current, defineWook, key } from "@wooksjs/event-core";
 import { useBody } from "@wooksjs/http-body";
 //#region src/validation-interceptor.ts
 const dbErrorCodeToStatus = { CONFLICT: 409 };
@@ -180,13 +181,39 @@ function findSortOffender(sort, isAllowed) {
 	}
 }
 //#endregion
+//#region src/actions/controller-registry.ts
+let asDbReadableCtor = null;
+let asValueHelpCtor = null;
+function registerAsDbReadableController(ctor) {
+	asDbReadableCtor = ctor;
+}
+function registerAsValueHelpController(ctor) {
+	asValueHelpCtor = ctor;
+}
+function isAsDbReadableControllerSubclass(ctor) {
+	if (!asDbReadableCtor) return false;
+	return asDbReadableCtor.prototype.isPrototypeOf(ctor.prototype);
+}
+function isAsValueHelpControllerSubclass(ctor) {
+	if (!asValueHelpCtor) return false;
+	return asValueHelpCtor.prototype.isPrototypeOf(ctor.prototype);
+}
+function isAsDbReadableControllerInstance(value) {
+	return !!asDbReadableCtor && value instanceof asDbReadableCtor;
+}
+//#endregion
 //#region src/actions/keys.ts
+/** Log-message prefix for warnings emitted from the actions subsystem. */
+const WARN_PREFIX = "[moost-db actions]";
 /** Method-level metadata key — written by `@DbAction(name, opts)`. */
 const MOOST_DB_ACTION = "atscript_db_action";
 /** Class-level metadata key — written by `@DbActions` and the level-pinned shortcuts. Stored as an array; decorators accumulate. */
 const MOOST_DB_ACTIONS = "atscript_db_actions";
 /** Param-level metadata key — written by `@DbActionPK()` / `@DbActionPKs()`. Drives level inference. */
 const MOOST_DB_ACTION_PARAM = "atscript_db_action_param";
+/** Param-level marker keys — written by `@DbActionRow()` / `@DbActionRows()`. */
+const MOOST_DB_ACTION_ROW = "atscript_db_action_row";
+const MOOST_DB_ACTION_ROWS = "atscript_db_action_rows";
 /**
 * Shared method-decorator update used by `@DbAction` and `@DbActionDefault`:
 * read the existing `MOOST_DB_ACTION` slot, merge the patch (later-applied
@@ -204,17 +231,50 @@ function mergeActionMeta(current, patch) {
 	};
 }
 //#endregion
+//#region src/actions/param-level.ts
+function scanParamLevel(params) {
+	let single = false;
+	let multi = false;
+	let hasRowParam = false;
+	let hasBody = false;
+	for (const p of params) {
+		const kind = p[MOOST_DB_ACTION_PARAM];
+		if (kind === "pk") single = true;
+		else if (kind === "pks") multi = true;
+		if (p["atscript_db_action_row"]) {
+			single = true;
+			hasRowParam = true;
+		}
+		if (p["atscript_db_action_rows"]) {
+			multi = true;
+			hasRowParam = true;
+		}
+		if (p.paramSource === "BODY") hasBody = true;
+	}
+	return {
+		level: single && multi ? "table" : single ? "row" : multi ? "rows" : "table",
+		single,
+		multi,
+		hasRowParam,
+		hasBody
+	};
+}
+//#endregion
 //#region src/actions/discover.ts
-/** Optional fields shared between method opts and class-level entries. */
+/**
+* Pure structural-copy fields. `disabled` and `requiredFields` are handled
+* as special cases in {@link emitInfo} so the function-to-string transform
+* stays out of the copy loop.
+*/
 const OPTIONAL_FIELDS = [
 	"icon",
 	"intent",
 	"description",
 	"order",
 	"default",
-	"promptText"
+	"promptText",
+	"shortcut"
 ];
-const WARN_PREFIX = "[moost-db actions]";
 const actionsCache = /* @__PURE__ */ new WeakMap();
 /**
 * Discover all actions declared on a controller and produce the `/meta` array.
@@ -255,9 +315,21 @@ function collectMethodActions(ctor, overview, logger, out) {
 		const levelInfer = inferMethodLevel(methodMeta.params ?? [], action.name, logger);
 		if (!levelInfer) continue;
 		if (levelInfer.bodyConflict) {
-			logger.warn(`${WARN_PREFIX} action "${action.name}" cannot mix @DbActionPK*/@DbActionPKs with @Body() — dropping`);
+			logger.warn(`${WARN_PREFIX} action "${action.name}" cannot mix @DbActionPK*/@DbActionPKs/@DbActionRow*/@DbActionRows with @Body() — dropping`);
 			continue;
 		}
+		if (levelInfer.level === "table" && action.opts.disabled !== void 0) {
+			logger.warn(`${WARN_PREFIX} action "${action.name}" — \`disabled\` is not allowed at the 'table' level; row-state predicates are not meaningful when no row is in scope. Use @Authenticate / arbac for table-level access — dropping`);
+			continue;
+		}
+		if (action.opts.disabled !== void 0 || levelInfer.hasRowParam) {
+			const extendsReadable = isAsDbReadableControllerSubclass(ctor);
+			const hasOptsTable = action.opts.table != null;
+			if (!extendsReadable && !hasOptsTable) {
+				logger.warn(`${WARN_PREFIX} action "${action.name}" declares a gate or row injection but the controller does not extend AsDbReadableController and \`opts.table\` is not provided. Either extend AsDbReadableController / AsDbController or pass \`opts.table\` on @DbAction — dropping`);
+				continue;
+			}
+		}
 		const postEntry = handlers.find((h) => h.handler.type === "HTTP" && h.handler.method === "POST");
 		if (!postEntry) {
 			logger.warn(`${WARN_PREFIX} action "${action.name}" requires @Post(...); no POST handler bound to ${methodName} — dropping`);
@@ -280,40 +352,32 @@ function collectMethodActions(ctor, overview, logger, out) {
 			processor: "backend",
 			value: path
 		};
-		copyOptionalFields(info, action.opts);
+		emitInfo(info, action.opts, action.name, logger);
 		out.push(info);
 	}
 }
 function inferMethodLevel(params, actionName, logger) {
-	let hasPk = false;
-	let hasPks = false;
-	let hasBody = false;
-	for (const p of params) {
-		const kind = p[MOOST_DB_ACTION_PARAM];
-		if (kind === "pk") hasPk = true;
-		else if (kind === "pks") hasPks = true;
-		if (p.paramSource === "BODY") hasBody = true;
-	}
-	if (hasPk && hasPks) {
-		logger.warn(`${WARN_PREFIX} action "${actionName}" has both @DbActionPK and @DbActionPKs — dropping`);
+	const scan = scanParamLevel(params);
+	if (scan.single && scan.multi) {
+		logger.warn(`${WARN_PREFIX} action "${actionName}" mixes single-cardinality and multi-cardinality decorators (@DbActionPK / @DbActionRow vs @DbActionPKs / @DbActionRows) — dropping`);
 		return null;
 	}
-	const level = hasPk ? "row" : hasPks ? "rows" : "table";
 	return {
-		level,
-		bodyConflict: hasBody && level !== "table"
+		level: scan.level,
+		bodyConflict: scan.hasBody && scan.level !== "table",
+		hasRowParam: scan.hasRowParam
 	};
 }
 function collectClassActions(ctor, logger, out) {
 	const list = getMoostMate().read(ctor)?.[MOOST_DB_ACTIONS];
 	if (!list) return;
-	for (const { name, entry, forcedLevel } of list) {
-		const built = buildClassEntry(name, entry, forcedLevel, logger);
+	for (const { name, entry } of list) {
+		const built = buildClassEntry(name, entry, logger);
 		if (built) out.push(built);
 	}
 }
-function buildClassEntry(name, entry, forcedLevel, logger) {
-	const level = forcedLevel ?? entry.level;
+function buildClassEntry(name, entry, logger) {
+	const level = entry.level;
 	if (!level) {
 		logger.warn(`${WARN_PREFIX} class-level action "${name}" requires a level — dropping. Use @DbTableActions/@DbRowActions/@DbRowsActions or set "level" explicitly.`);
 		return null;
@@ -322,6 +386,10 @@ function buildClassEntry(name, entry, forcedLevel, logger) {
 		logger.warn(`${WARN_PREFIX} class-level action "${name}" requires a label — dropping`);
 		return null;
 	}
+	if (level === "table" && entry.disabled !== void 0) {
+		logger.warn(`${WARN_PREFIX} class-level action "${name}" — \`disabled\` is not allowed at the 'table' level — dropping`);
+		return null;
+	}
 	const processor = entry.processor;
 	let value;
 	if (processor === "navigate" || processor === "backend") {
@@ -349,7 +417,7 @@ function buildClassEntry(name, entry, forcedLevel, logger) {
 		processor,
 		value
 	};
-	copyOptionalFields(info, entry);
+	emitInfo(info, entry, name, logger);
 	return info;
 }
 function applyDefaultPerLevel(actions, logger) {
@@ -363,6 +431,26 @@ function applyDefaultPerLevel(actions, logger) {
 		} else winners.set(a.level, a.name);
 	}
 }
+/**
+* Emit structural-copy fields plus `disabled` (stringified) and
+* `requiredFields` (forwarded verbatim — server doesn't auto-derive).
+* `requiredFields` without `disabled` is dropped with a warning before the
+* structural copy runs, so method-decorator and class-level-dict origins
+* stay symmetric.
+*/
+function emitInfo(info, source, name, logger) {
+	const disabled = source.disabled;
+	const hasDisabled = typeof disabled === "function";
+	let requiredFields = source.requiredFields;
+	if (!hasDisabled && requiredFields !== void 0) {
+		logger.warn(`${WARN_PREFIX} action "${name}" has \`requiredFields\` without \`disabled\` — \`requiredFields\` is purely a UI hint and meaningless without a predicate. Dropping \`requiredFields\` from /meta.`);
+		requiredFields = void 0;
+	}
+	copyOptionalFields(info, source);
+	if (Array.isArray(info.promptText)) info.promptText = info.promptText.slice();
+	if (hasDisabled) info.disabled = disabled.toString();
+	if (Array.isArray(requiredFields)) info.requiredFields = requiredFields.slice();
+}
 function copyOptionalFields(info, source) {
 	for (const key of OPTIONAL_FIELDS) {
 		const value = source[key];
@@ -1005,6 +1093,7 @@ AsDbReadableController = __decorate([
 	__decorateParam(0, Inject(READABLE_DEF)),
 	__decorateMetadata("design:paramtypes", [Object, typeof (_ref$3 = typeof Moost !== "undefined" && Moost) === "function" ? _ref$3 : Object])
 ], AsDbReadableController);
+registerAsDbReadableController(AsDbReadableController);
 //#endregion
 //#region src/as-db.controller.ts
 var _ref$2, _ref2$1;
@@ -1303,6 +1392,7 @@ AsValueHelpController = __decorate([Inherit(), __decorateMetadata("design:paramt
 	String,
 	typeof (_ref$1 = typeof Moost !== "undefined" && Moost) === "function" ? _ref$1 : Object
 ])], AsValueHelpController);
+registerAsValueHelpController(AsValueHelpController);
 //#endregion
 //#region src/as-json-value-help.controller.ts
 var _ref;
@@ -1463,89 +1553,43 @@ function applySelect(rows, select) {
 	});
 }
 //#endregion
-//#region src/actions/db-action.decorator.ts
-/**
-* Mark a controller method as a database action surfaced via `/meta`.
-*
-* Metadata-only — pair with `@Post(...)` for Moost to bind the route. The
-* meta builder reads this metadata plus the bound POST path lazily and
-* emits the action with `processor: 'backend'`. Order vs.
-* `@DbActionDefault()` does not matter — both merge into the same slot.
-*
-* @example
-* ```ts
-* @Post('actions/block')
-* @DbAction('block', { label: 'Block', icon: 'i-as-block', intent: 'negative' })
-* async blockUser(@DbActionPK() id: string) { ... }
-* ```
-*/
-function DbAction(name, opts = {}) {
-	return getMoostMate().decorate((current) => {
-		const meta = current;
-		return {
-			...current,
-			[MOOST_DB_ACTION]: mergeActionMeta(meta, {
-				name,
-				opts
-			})
-		};
-	});
+//#region src/actions/action-disabled-error.ts
+function buildMessage(action, pks) {
+	if (pks !== void 0) return `Action "${action}" is disabled for ${pks.length} of the selected rows`;
+	return `Action "${action}" is disabled for this row`;
 }
-//#endregion
-//#region src/actions/db-action-default.decorator.ts
 /**
-* Sugar that flips `default: true` on the same method's `@DbAction` metadata.
-* Equivalent to passing `opts.default = true`. Decorator order does not matter.
+* 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, pk)` — the body emits `pk`.
+* - `'rows'`-level rejection: pass `(action, undefined, pks)` — the body
+*   emits `pks` (the FULL list of failing PKs in reject mode; the FULL list
+*   of request PKs in skip mode with zero survivors).
 */
-function DbActionDefault() {
-	return getMoostMate().decorate((current) => {
-		const meta = current;
-		return {
-			...current,
-			[MOOST_DB_ACTION]: mergeActionMeta(meta, { opts: { default: true } })
+var ActionDisabledError = class extends HttpError {
+	name = "ActionDisabledError";
+	constructor(action, pk, pks) {
+		const body = {
+			name: "ActionDisabledError",
+			message: buildMessage(action, pks),
+			statusCode: 409,
+			action
 		};
-	});
-}
+		if (pks !== void 0) body.pks = pks;
+		else if (pk !== void 0) body.pk = pk;
+		super(409, body);
+	}
+};
 //#endregion
-//#region src/actions/pk-source.ts
-/**
-* Extract the PK validation source from a controller instance. Looks for
-* `readable` (set by {@link AsDbReadableController}) or `table` (set by
-* {@link AsDbController}).
-*
-* If the controller has no typed table attached (e.g. a value-help
-* controller, or a plain Moost controller without `@TableController`),
-* throws an HTTP 500 — this is a **server misconfiguration**, not a client
-* error. The body parser has nothing to validate against, so the request
-* cannot proceed. Use `@Body()` and parse the PK manually if you need to
-* accept PK-shaped bodies on a controller without an attached table.
-*/
-function resolvePkSource(controller) {
-	const c = controller;
-	const candidate = c.readable ?? c.table;
-	if (!isPkValidationSource(candidate)) throw new HttpError(500, "@DbActionPK/@DbActionPKs requires a controller with an attached table (via @TableController / @ReadableController). Use @Body() instead if your controller has no typed table.");
-	return candidate;
-}
+//#region src/actions/pk-validation.ts
 function isPkValidationSource(value) {
 	if (!value || typeof value !== "object") return false;
 	const v = value;
 	return Array.isArray(v.primaryKeys) && Array.isArray(v.fieldDescriptors);
 }
 /**
-* Build a parameter decorator that parses the JSON request body, validates
-* it against the bound table's PK schema with `validate`, and tags the param
-* so {@link discoverActions} can infer the action's `level`.
-*/
-function createPkParamDecorator(kind, validate, resolverName) {
-	return ApplyDecorators(getMoostMate().decorate(MOOST_DB_ACTION_PARAM, kind), Resolve(async () => {
-		const body = await useBody().parseBody();
-		validate(body, resolvePkSource(useControllerContext().getController()));
-		return body;
-	}, resolverName));
-}
-//#endregion
-//#region src/actions/pk-validation.ts
-/**
 * Validate a JSON-decoded body against a single-row PK shape (scalar or
 * composite). Throws {@link ValidatorError} with structured `errors` so the
 * existing validation interceptor returns HTTP 400.
@@ -1630,6 +1674,229 @@ function isPlainObject(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //#endregion
+//#region src/actions/pk-cache.ts
+const boundTableKey = key("atscript_db_action_bound_table");
+function getActionTable(ctx) {
+	if (ctx.has(boundTableKey)) {
+		const fromSlot = ctx.get(boundTableKey);
+		if (fromSlot) return fromSlot;
+	}
+	const ctrl = useControllerContext(ctx).getController();
+	if (ctrl) {
+		const t = ctrl.readable ?? ctrl.table;
+		if (t) return t;
+	}
+	return null;
+}
+function noTableError(ctx) {
+	const cc = useControllerContext(ctx);
+	const ctrl = cc.getController();
+	const methodName = cc.getMethod();
+	let actionName;
+	if (ctrl && methodName) actionName = getMoostMate().read(ctrl.constructor, methodName)?.[MOOST_DB_ACTION]?.name;
+	return new HttpError(500, `${WARN_PREFIX} ${actionName ? `"${actionName}"` : "<unknown>"}: controller has no readable/table property and the action declares no opts.table. Either expose readable/table on the controller, extend AsDbReadableController, or pass opts.table on @DbAction.`);
+}
+async function resolveValidatedPk(ctx, validate) {
+	const table = getActionTable(ctx);
+	if (!isPkValidationSource(table)) throw noTableError(ctx);
+	const body = await useBody(ctx).parseBody();
+	validate(body, table);
+	return body;
+}
+const dbActionPkSlot = cached((ctx) => resolveValidatedPk(ctx, validateSinglePk));
+const dbActionPksSlot = cached(async (ctx) => {
+	return await resolveValidatedPk(ctx, validateMultiPk);
+});
+const useDbActionPk = defineWook((ctx) => ({ load: () => ctx.get(dbActionPkSlot) }));
+const useDbActionPks = defineWook((ctx) => ({ load: () => ctx.get(dbActionPksSlot) }));
+//#endregion
+//#region src/actions/row-cache.ts
+function asFetchTable(value) {
+	if (!value || typeof value !== "object") return null;
+	const v = value;
+	return Array.isArray(v.primaryKeys) && typeof v.findById === "function" && typeof v.findMany === "function" ? v : null;
+}
+function noTable() {
+	throw new HttpError(500, `${WARN_PREFIX} cached row wook: no bound table`);
+}
+async function loadRow(ctx) {
+	const pk = await ctx.get(dbActionPkSlot);
+	const row = await (asFetchTable(getActionTable(ctx)) ?? noTable()).findById(pk);
+	if (row == null) throw new HttpError(404, "Row not found for action PK");
+	return row;
+}
+async function loadRows(ctx) {
+	const pks = await ctx.get(dbActionPksSlot);
+	const table = asFetchTable(getActionTable(ctx)) ?? noTable();
+	if (pks.length === 0) return [];
+	const { primaryKeys } = table;
+	const rows = await table.findMany({ filter: buildPksFilter(pks, primaryKeys) });
+	if (primaryKeys.length === 1) {
+		const field = primaryKeys[0];
+		const byKey = /* @__PURE__ */ new Map();
+		for (const row of rows) byKey.set(row[field], row);
+		const ordered = [];
+		for (const pk of pks) {
+			const found = byKey.get(pk);
+			if (found !== void 0) ordered.push(found);
+		}
+		return ordered;
+	}
+	const byKey = /* @__PURE__ */ new Map();
+	for (const row of rows) byKey.set(compositeKey(row, primaryKeys), row);
+	const ordered = [];
+	for (const pk of pks) {
+		const found = byKey.get(compositeKey(pk, primaryKeys));
+		if (found !== void 0) ordered.push(found);
+	}
+	return ordered;
+}
+function buildPksFilter(pks, primaryKeys) {
+	if (primaryKeys.length === 1) return { [primaryKeys[0]]: { $in: pks } };
+	return { $or: pks.map((pk) => {
+		const obj = pk;
+		const clause = {};
+		for (const field of primaryKeys) clause[field] = obj[field];
+		return clause;
+	}) };
+}
+function compositeKey(obj, primaryKeys) {
+	let out = "";
+	for (const f of primaryKeys) {
+		if (out !== "") out += "\0";
+		const v = obj[f];
+		if (v === null) out += "
n";
+		else if (v === void 0) out += "
u";
+		else if (typeof v === "string") out += `s\x02${v}`;
+		else if (typeof v === "number") out += `n\x02${v}`;
+		else if (typeof v === "boolean") out += `b\x02${v}`;
+		else out += `j\x02${JSON.stringify(v)}`;
+	}
+	return out;
+}
+const dbActionRowSlot = cached((ctx) => loadRow(ctx));
+const dbActionRowsSlot = cached((ctx) => loadRows(ctx));
+const useDbActionRow = defineWook((ctx) => ({ load: () => ctx.get(dbActionRowSlot) }));
+const useDbActionRows = defineWook((ctx) => ({ load: () => ctx.get(dbActionRowsSlot) }));
+//#endregion
+//#region src/actions/gate-interceptor.ts
+const GATE_PRIORITY = TInterceptorPriority.AFTER_GUARD;
+function injectBoundTable(table) {
+	const ctx = current();
+	if (ctx.has(boundTableKey)) return;
+	const controller = useControllerContext(ctx).getController();
+	if (isAsDbReadableControllerInstance(controller)) {
+		ctx.set(boundTableKey, controller.readable);
+		return;
+	}
+	if (table != null) ctx.set(boundTableKey, table);
+}
+function buildGateInterceptor(opts) {
+	const { action, level, disabled, onDisabledRows, table } = opts;
+	return defineBeforeInterceptor(async () => {
+		injectBoundTable(table);
+		const ctx = current();
+		if (level === "row") {
+			if (disabled(await ctx.get(dbActionRowSlot))) throw new ActionDisabledError(action, await ctx.get(dbActionPkSlot));
+			return;
+		}
+		const pks = await ctx.get(dbActionPksSlot);
+		const rows = await ctx.get(dbActionRowsSlot);
+		const failingPks = [];
+		const passingRows = [];
+		const passingPks = [];
+		for (let i = 0; i < rows.length; i++) if (disabled(rows[i])) failingPks.push(pks[i]);
+		else {
+			passingRows.push(rows[i]);
+			passingPks.push(pks[i]);
+		}
+		if (onDisabledRows === "skip") {
+			if (passingRows.length === 0) throw new ActionDisabledError(action, void 0, [...pks]);
+			if (failingPks.length > 0) {
+				ctx.set(dbActionRowsSlot, Promise.resolve(passingRows));
+				ctx.set(dbActionPksSlot, Promise.resolve(passingPks));
+			}
+			return;
+		}
+		if (failingPks.length > 0) throw new ActionDisabledError(action, void 0, failingPks);
+	}, GATE_PRIORITY);
+}
+/** Thin interceptor for `@DbActionRow*` without `disabled` — injects only the bound table. */
+function buildThinInterceptor(opts) {
+	const { table } = opts;
+	return defineBeforeInterceptor(() => {
+		injectBoundTable(table);
+	}, GATE_PRIORITY);
+}
+//#endregion
+//#region src/actions/db-action.decorator.ts
+/**
+* Mark a controller method as a database action surfaced via `/meta`. Writes
+* `MOOST_DB_ACTION` metadata and registers a Moost interceptor when needed
+* (gate when `disabled` is set, thin bound-table injector when only
+* `@DbActionRow*` is present). Stacking two `@DbAction` on the same method
+* is undefined and emits a warning.
+*/
+function DbAction(name, opts = {}) {
+	const mate = getMoostMate();
+	return ((target, propertyKey, descriptor) => {
+		const priorName = mate.read(target, propertyKey)?.[MOOST_DB_ACTION]?.name;
+		if (priorName) console.warn(`${WARN_PREFIX} stacking @DbAction on the same method is undefined; declare one per method. Detected: "${priorName}" and "${name}".`);
+		mate.decorate((current) => {
+			const meta = current;
+			return {
+				...current,
+				[MOOST_DB_ACTION]: mergeActionMeta(meta, {
+					name,
+					opts
+				})
+			};
+		})(target, propertyKey, descriptor);
+		if (isAsValueHelpControllerSubclass(typeof target === "function" ? target : target.constructor)) return descriptor;
+		const scan = scanParamLevel(mate.read(target, propertyKey)?.params ?? []);
+		if (!!opts.disabled && (scan.level === "row" || scan.level === "rows")) Intercept(buildGateInterceptor({
+			action: name,
+			level: scan.level,
+			disabled: opts.disabled,
+			onDisabledRows: opts.onDisabledRows ?? "reject",
+			table: opts.table
+		}))(target, propertyKey, descriptor);
+		else if (scan.hasRowParam) Intercept(buildThinInterceptor({ table: opts.table }))(target, propertyKey, descriptor);
+		return descriptor;
+	});
+}
+//#endregion
+//#region src/actions/db-action-default.decorator.ts
+/**
+* Sugar that flips `default: true` on the same method's `@DbAction` metadata.
+* Equivalent to passing `opts.default = true`. Decorator order does not matter.
+*/
+function DbActionDefault() {
+	return getMoostMate().decorate((current) => {
+		const meta = current;
+		return {
+			...current,
+			[MOOST_DB_ACTION]: mergeActionMeta(meta, { opts: { default: true } })
+		};
+	});
+}
+//#endregion
+//#region src/actions/pk-source.ts
+/**
+* Build a parameter decorator that reads its value from the cached PK wook
+* (single or multi). Validation runs inside the wook factory exactly once
+* per request, regardless of how many readers consume the value (`@DbActionPK*`
+* resolver, gate interceptor, cached row wook, in-handler composables).
+*
+* Marks the param so {@link discoverActions} can infer the action's `level`.
+*/
+function createPkParamDecorator(kind) {
+	const mate = getMoostMate();
+	const slot = kind === "pk" ? dbActionPkSlot : dbActionPksSlot;
+	const resolverName = kind === "pk" ? "dbActionPk" : "dbActionPks";
+	return ApplyDecorators(mate.decorate(MOOST_DB_ACTION_PARAM, kind), Resolve(async () => current().get(slot), resolverName));
+}
+//#endregion
 //#region src/actions/db-action-pk.decorator.ts
 /**
 * Parameter resolver that reads the primary key from the JSON request body
@@ -1644,9 +1911,13 @@ function isPlainObject(value) {
 *
 * Marks the param so {@link discoverActions} can infer the action's `level`
 * as `'row'`.
+*
+* Implementation note: the resolver is a thin reader of the cached PK wook
+* — validation logic lives in the wook factory, which runs once per request
+* regardless of how many readers consume the value.
 */
 function DbActionPK() {
-	return createPkParamDecorator("pk", validateSinglePk, "dbActionPk");
+	return createPkParamDecorator("pk");
 }
 //#endregion
 //#region src/actions/db-action-pks.decorator.ts
@@ -1659,9 +1930,44 @@ function DbActionPK() {
 *
 * Validation is strict — no type coercion. Marks the param so
 * {@link discoverActions} can infer the action's `level` as `'rows'`.
+*
+* In `'rows'` skip mode the resolved value reflects the gate interceptor's
+* filtered subset (the cached PK slot is overwritten in place); see
+* {@link dbActionPksSlot} for precedence details.
 */
 function DbActionPKs() {
-	return createPkParamDecorator("pks", validateMultiPk, "dbActionPks");
+	return createPkParamDecorator("pks");
+}
+//#endregion
+//#region src/actions/db-action-row.decorator.ts
+function createRowParamDecorator(metaKey, slot, resolverName) {
+	return ApplyDecorators(getMoostMate().decorate(metaKey, true), Resolve(async () => current().get(slot), resolverName));
+}
+/**
+* Parameter decorator that injects the row whose PK was supplied in the
+* request body. Reads from the cached row wook (fetched once per request,
+* shared with the gate interceptor when `disabled` is set).
+*
+* Marks the param so {@link discoverActions} infers the action's `level` as
+* `'row'`. Co-occurrence with `@DbActionRows()` (or any multi-cardinality
+* decorator) drops the action with a warning.
+*
+* In `'skip'` mode this returns the gate's filtered row; the original
+* request-body row is not retrievable.
+*/
+function DbActionRow() {
+	return createRowParamDecorator(MOOST_DB_ACTION_ROW, dbActionRowSlot, "dbActionRow");
+}
+/**
+* Parameter decorator that injects the rows-array fetched by primary keys
+* from the request body. Reads from the cached row-array wook.
+*
+* Marks the param so {@link discoverActions} infers the action's `level` as
+* `'rows'`. In `'rows'` + `'skip'` mode the resolved value contains only the
+* gate's surviving rows.
+*/
+function DbActionRows() {
+	return createRowParamDecorator(MOOST_DB_ACTION_ROWS, dbActionRowsSlot, "dbActionRows");
 }
 //#endregion
 //#region src/actions/db-actions.decorator.ts
@@ -1697,11 +2003,16 @@ function DbRowsActions(dict) {
 }
 function classLevelActions(dict, forcedLevel) {
 	const entries = [];
-	for (const [name, entry] of Object.entries(dict)) entries.push({
-		name,
-		entry,
-		forcedLevel
-	});
+	for (const [name, entry] of Object.entries(dict)) {
+		const merged = forcedLevel ? {
+			...entry,
+			level: forcedLevel
+		} : entry;
+		entries.push({
+			name,
+			entry: merged
+		});
+	}
 	return getMoostMate().decorate((current) => {
 		const existing = current["atscript_db_actions"] ?? [];
 		return {
@@ -1711,4 +2022,4 @@ function classLevelActions(dict, forcedLevel) {
 	});
 }
 //#endregion
-export { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, DbActionPK, DbActionPKs, DbActions, DbRowActions, DbRowsActions, DbTableActions, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, discoverActions, validationErrorTransform };
+export { ActionDisabledError, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, DbActionPK, DbActionPKs, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, discoverActions, useDbActionPk, useDbActionPks, useDbActionRow, useDbActionRows, validationErrorTransform };