@atscript/moost-db 0.1.57 → 0.1.59

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 };
@@ -97,7 +98,7 @@ var SelectControlDto = class {
 		throwFeatureDisabled("JSON Schema", "jsonSchema", "emit.jsonSchema");
 	}
 };
-defineAnnotatedType("object", QueryControlsDto).prop("$skip", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$count", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$search", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$vector", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$threshold", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type);
+defineAnnotatedType("object", QueryControlsDto).prop("$skip", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$count", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$search", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$vector", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$threshold", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type).prop("$actions", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type);
 defineAnnotatedType("object", PagesControlsDto).prop("$page", defineAnnotatedType().designType("string").tags("string").annotate("expect.pattern", {
 	pattern: "^\\d+$",
 	flags: "u",
@@ -106,8 +107,8 @@ defineAnnotatedType("object", PagesControlsDto).prop("$page", defineAnnotatedTyp
 	pattern: "^\\d+$",
 	flags: "u",
 	message: "Expected positive number"
-}, true).optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$search", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$vector", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$threshold", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type);
-defineAnnotatedType("object", GetOneControlsDto).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type);
+}, true).optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$search", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$vector", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$threshold", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type).prop("$actions", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type);
+defineAnnotatedType("object", GetOneControlsDto).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type).prop("$actions", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type);
 defineAnnotatedType("object", WithRelationDto).prop("name", defineAnnotatedType().designType("string").tags("string").$type).prop("filter", defineAnnotatedType().refTo(WithFilterDto).optional().$type).prop("controls", defineAnnotatedType().refTo(WithRelationControlsDto).optional().$type).prop("insights", defineAnnotatedType().refTo(WithFilterDto).optional().$type);
 defineAnnotatedType("object", WithRelationControlsDto).prop("$skip", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$with", defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithRelationDto).$type).optional().$type);
 defineAnnotatedType("object", WithFilterDto).propPattern(/./, defineAnnotatedType("union").item(defineAnnotatedType().designType("string").tags("string").$type).item(defineAnnotatedType().designType("number").tags("number").$type).item(defineAnnotatedType().designType("boolean").tags("boolean").$type).item(defineAnnotatedType().designType("null").tags("null").$type).item(defineAnnotatedType().refTo(WithFilterDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().refTo(WithFilterDto).$type).$type).$type);
@@ -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. */
+/** Param-level metadata key — written by `@DbActionID()` / `@DbActionIDs()`. 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,39 +231,70 @@ 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 === "id") single = true;
+		else if (kind === "ids") 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. */
+/** Structural-copy fields; `disabled` is handled separately in {@link emitInfo} (function-to-string transform). */
 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.
-* Reads class + method metadata via `getMoostMate()` and resolves bound POST
-* paths through the Moost controller overview.
-*
-* Result is memoized per controller constructor — discovery walks every
-* handler entry and reads decorator metadata, which is wasted work to repeat
-* across instances.
-*/
+const rowLevelActionsCache = /* @__PURE__ */ new WeakMap();
+/** Discover actions on a controller, memoized per ctor. `info`-only callers map `e => e.info`. */
 function discoverActions(controllerCtor, app, logger) {
 	const cached = actionsCache.get(controllerCtor);
 	if (cached) return cached;
 	const overview = app.getControllersOverview?.()?.find((o) => o.type === controllerCtor);
 	const out = [];
-	collectMethodActions(controllerCtor, overview, logger, out);
-	collectClassActions(controllerCtor, logger, out);
+	const seen = /* @__PURE__ */ new Set();
+	collectMethodActions(controllerCtor, overview, logger, out, seen);
+	collectClassActions(controllerCtor, logger, out, seen);
 	applyDefaultPerLevel(out, logger);
 	actionsCache.set(controllerCtor, out);
 	return out;
 }
-function collectMethodActions(ctor, overview, logger, out) {
+/** Row/rows-level subset of {@link discoverActions}; memoized per ctor. */
+function discoverRowLevelActions(controllerCtor, app, logger) {
+	const cached = rowLevelActionsCache.get(controllerCtor);
+	if (cached) return cached;
+	const filtered = discoverActions(controllerCtor, app, logger).filter((e) => e.info.level === "row" || e.info.level === "rows");
+	rowLevelActionsCache.set(controllerCtor, filtered);
+	return filtered;
+}
+function collectMethodActions(ctor, overview, logger, out, seen) {
 	if (!overview) return;
 	const byMethod = /* @__PURE__ */ new Map();
 	for (const h of overview.handlers) {
@@ -255,9 +313,25 @@ 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 @DbActionID*/@DbActionIDs/@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 && !isNonEmptyStringArray(action.opts.requiredFields)) {
+			logger.warn(`${WARN_PREFIX} action "${action.name}" — \`disabled\` requires a non-empty \`requiredFields\` array (the predicate's field dependencies must be declared explicitly) — 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`);
@@ -273,6 +347,10 @@ function collectMethodActions(ctor, overview, logger, out) {
 			logger.warn(`${WARN_PREFIX} action "${action.name}" requires a label (opts.label or @Label) — dropping`);
 			continue;
 		}
+		if (seen.has(action.name)) {
+			logger.warn(`${WARN_PREFIX} duplicate action name "${action.name}" within controller — dropping the second declaration`);
+			continue;
+		}
 		const info = {
 			name: action.name,
 			label,
@@ -280,40 +358,46 @@ function collectMethodActions(ctor, overview, logger, out) {
 			processor: "backend",
 			value: path
 		};
-		copyOptionalFields(info, action.opts);
-		out.push(info);
+		emitInfo(info, action.opts);
+		seen.add(action.name);
+		out.push({
+			info,
+			raw: action.opts
+		});
 	}
 }
 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 (@DbActionID / @DbActionRow vs @DbActionIDs / @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) {
+function collectClassActions(ctor, logger, out, seen) {
 	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);
-		if (built) out.push(built);
+	for (const { name, entry } of list) {
+		if (seen.has(name)) {
+			logger.warn(`${WARN_PREFIX} duplicate action name "${name}" within controller — dropping the second declaration`);
+			continue;
+		}
+		const built = buildClassEntry(name, entry, logger);
+		if (built) {
+			seen.add(name);
+			out.push({
+				info: built,
+				raw: entry
+			});
+		}
 	}
 }
-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 +406,14 @@ 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;
+	}
+	if (entry.disabled !== void 0 && !isNonEmptyStringArray(entry.requiredFields)) {
+		logger.warn(`${WARN_PREFIX} class-level action "${name}" — \`disabled\` requires a non-empty \`requiredFields\` array (the predicate's field dependencies must be declared explicitly) — dropping`);
+		return null;
+	}
 	const processor = entry.processor;
 	let value;
 	if (processor === "navigate" || processor === "backend") {
@@ -349,26 +441,37 @@ function buildClassEntry(name, entry, forcedLevel, logger) {
 		processor,
 		value
 	};
-	copyOptionalFields(info, entry);
+	emitInfo(info, entry);
 	return info;
 }
-function applyDefaultPerLevel(actions, logger) {
+function applyDefaultPerLevel(envelopes, logger) {
 	const winners = /* @__PURE__ */ new Map();
-	for (const a of actions) {
-		if (!a.default) continue;
-		const existing = winners.get(a.level);
+	for (const { info } of envelopes) {
+		if (!info.default) continue;
+		const existing = winners.get(info.level);
 		if (existing) {
-			a.default = false;
-			logger.warn(`${WARN_PREFIX} duplicate default action at level "${a.level}": "${existing}" wins, "${a.name}" demoted`);
-		} else winners.set(a.level, a.name);
+			info.default = false;
+			logger.warn(`${WARN_PREFIX} duplicate default action at level "${info.level}": "${existing}" wins, "${info.name}" demoted`);
+		} else winners.set(info.level, info.name);
 	}
 }
+/** Emit structural-copy fields plus stringified `disabled`. `requiredFields` is server-internal (never on the wire). */
+function emitInfo(info, source) {
+	const disabled = source.disabled;
+	const hasDisabled = typeof disabled === "function";
+	copyOptionalFields(info, source);
+	if (Array.isArray(info.promptText)) info.promptText = info.promptText.slice();
+	if (hasDisabled) info.disabled = disabled.toString();
+}
 function copyOptionalFields(info, source) {
 	for (const key of OPTIONAL_FIELDS) {
 		const value = source[key];
 		if (value !== void 0) info[key] = value;
 	}
 }
+function isNonEmptyStringArray(value) {
+	return Array.isArray(value) && value.length > 0 && value.every((v) => typeof v === "string");
+}
 //#endregion
 //#region \0@oxc-project+runtime@0.120.0/helpers/decorateMetadata.js
 function __decorateMetadata(k, v) {
@@ -551,6 +654,7 @@ let AsReadableController = class AsReadableController {
 			vectorSearchable: false,
 			searchIndexes: [],
 			primaryKeys: [],
+			preferredId: [],
 			relations: [],
 			fields: {},
 			type: this.getSerializedType(),
@@ -564,7 +668,7 @@ let AsReadableController = class AsReadableController {
 	* controllers — see {@link AsValueHelpController#buildMetaResponse}.
 	*/
 	buildActions() {
-		return discoverActions(this.constructor, this.app, this.logger);
+		return discoverActions(this.constructor, this.app, this.logger).map((e) => e.info);
 	}
 	/**
 	* Declares the built-in CRUD operations this controller exposes. Subclasses
@@ -599,6 +703,80 @@ AsReadableController = __decorate([UseValidationErrorTransform(), __decorateMeta
 	Object
 ])], AsReadableController);
 //#endregion
+//#region src/actions/verdict.ts
+/** Assert that a `disabled` predicate returned a `boolean[]` 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`);
+}
+//#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;
+}
+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 = [];
+		for (let j = 0; j < candidates.length; j++) {
+			const v = verdicts[j];
+			if (v === void 0) {
+				names.push(candidates[j].envelope.info.name);
+				continue;
+			}
+			if (!v[i]) names.push(candidates[j].envelope.info.name);
+		}
+		row.$actions = names;
+	}
+	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/decorators.ts
 /**
 * DI token under which the {@link AtscriptDbReadable} instance
@@ -693,10 +871,17 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	/** Reference to the underlying readable (table or view). */
 	readable;
 	_gates;
+	_preferredIdSet;
+	_compositeIdShapes;
+	_overlayIsNoOp;
 	constructor(readable, app) {
 		super(readable.type, readable.tableName, app, readable.isView ? "view" : "table");
 		this.readable = readable;
 		this._gates = this._buildGates();
+		this._preferredIdSet = new Set(readable.preferredId ?? []);
+		this._compositeIdShapes = (readable.identifications ?? []).filter((id) => id.fields.length >= 2);
+		const defaultOverlay = AsReadableController.prototype.applyMetaOverlay;
+		this._overlayIsNoOp = this.applyMetaOverlay === defaultOverlay;
 	}
 	_buildGates() {
 		const meta = this.readable.type.metadata;
@@ -764,16 +949,169 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	transformProjection(projection) {
 		return projection;
 	}
+	widenPreferredIdProjection(projection) {
+		if (this._preferredIdSet.size === 0 || projection === void 0) return projection;
+		if (Array.isArray(projection)) return this._widenArrayProjection(projection);
+		return this._widenMapProjection(projection);
+	}
+	_widenArrayProjection(projection) {
+		const stringItems = /* @__PURE__ */ new Set();
+		for (const item of projection) if (typeof item === "string") stringItems.add(item);
+		let allPresent = true;
+		for (const field of this._preferredIdSet) if (!stringItems.has(field)) {
+			allPresent = false;
+			break;
+		}
+		if (allPresent) return projection;
+		const out = [...projection];
+		for (const field of this._preferredIdSet) if (!stringItems.has(field)) out.push(field);
+		return out;
+	}
+	_widenMapProjection(projection) {
+		const entries = Object.entries(projection);
+		if (entries.length === 0) return projection;
+		const included = /* @__PURE__ */ new Set();
+		const excluded = /* @__PURE__ */ new Set();
+		for (const [k, v] of entries) if (v === 1 || v === true) included.add(k);
+		else if (v === 0 || v === false) excluded.add(k);
+		if (included.size > 0 && excluded.size > 0) return new HttpError(400, "Mixed inclusion/exclusion $select maps are not supported");
+		if (excluded.size === 0) {
+			let allPresent = true;
+			for (const field of this._preferredIdSet) if (!included.has(field)) {
+				allPresent = false;
+				break;
+			}
+			if (allPresent) return projection;
+			const widened = {};
+			for (const k of included) widened[k] = 1;
+			for (const field of this._preferredIdSet) widened[field] = 1;
+			return widened;
+		}
+		const widened = {};
+		for (const fd of this.readable.fieldDescriptors) if (!fd.ignored && !excluded.has(fd.path)) widened[fd.path] = 1;
+		for (const field of this._preferredIdSet) widened[field] = 1;
+		return widened;
+	}
+	/** WHY: the URL parser only auto-coerces `$count`; every other boolean control reaches us as `"true"`/`"1"` and would fail DTO validation. */
+	_coerceActionsControl(controls) {
+		const v = controls.$actions;
+		if (typeof v === "string") controls.$actions = v === "true" || v === "1" || v === "";
+	}
+	/** Normalize a post-`widenPreferredIdProjection` $select into `string[] | null` (`null` = all fields). */
+	_resolveProjectionForAugmenter(select) {
+		if (select === void 0) return null;
+		if (Array.isArray(select)) {
+			const out = [];
+			const seen = /* @__PURE__ */ new Set();
+			for (const item of select) if (typeof item === "string" && !seen.has(item)) {
+				seen.add(item);
+				out.push(item);
+			}
+			return out;
+		}
+		const obj = select;
+		const included = [];
+		const excluded = [];
+		for (const [k, v] of Object.entries(obj)) if (v === 1 || v === true) included.push(k);
+		else if (v === 0 || v === false) excluded.push(k);
+		if (included.length > 0 && excluded.length === 0) return included;
+		if (excluded.length > 0 && included.length === 0) {
+			const excludedSet = new Set(excluded);
+			const out = [];
+			for (const fd of this.readable.fieldDescriptors) if (!fd.ignored && !excludedSet.has(fd.path)) out.push(fd.path);
+			return out;
+		}
+		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. */
+	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.meta();
+		const allowedNames = new Set(overlayMeta.actions.map((a) => a.name));
+		const filtered = rowLevelEnvelopes.filter((e) => allowedNames.has(e.info.name));
+		return filtered.length === 0 ? null : filtered;
+	}
+	/** Returns a widened `$select` only when at least one `requiredFields` entry is missing; `null` means "no widening needed". */
+	_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)) continue;
+				if (resultSet === null) {
+					resultSet = new Set(baseSelect);
+					result = [...baseSelect];
+				}
+				resultSet.add(f);
+				result.push(f);
+			}
+		}
+		return result;
+	}
+	async _prepareAugmentation(controls, select) {
+		if (!controls.$actions) return null;
+		const envelopes = await this._resolveAugmentEnvelopes();
+		if (envelopes === null) return null;
+		const resolvedProjection = this._resolveProjectionForAugmenter(select);
+		return {
+			envelopes,
+			resolvedProjection,
+			widenedSelect: resolvedProjection === null ? null : this._widenSelectForActions(envelopes, resolvedProjection)
+		};
+	}
+	async _resolveReadStrategy(controls) {
+		const searchTerm = controls.$search;
+		const indexName = controls.$index;
+		const vectorField = controls.$vector;
+		if (vectorField !== void 0 && searchTerm) return {
+			kind: "vector",
+			vector: await this.computeEmbedding(searchTerm, vectorField || void 0),
+			vectorField
+		};
+		if (searchTerm && this.readable.isSearchable()) return {
+			kind: "search",
+			term: searchTerm,
+			index: indexName
+		};
+		return { kind: "plain" };
+	}
+	/**
+	* Shared `query` / `pages` pipeline: prepare actions augmentation + read
+	* strategy in parallel, pre-widen $select for `requiredFields`, run
+	* `exec`, and augment `result.data` with `$actions` when the request set
+	* `$actions=true`. Caller dispatches the strategy to its read-method
+	* family (count vs no-count).
+	*/
+	async _runReadWithActions(queryObj, controls, select, exec) {
+		const [prep, strategy] = await Promise.all([this._prepareAugmentation(controls, select), this._resolveReadStrategy(controls)]);
+		const result = await exec(prep?.widenedSelect ? {
+			...queryObj,
+			controls: {
+				...queryObj.controls,
+				$select: prep.widenedSelect
+			}
+		} : queryObj, strategy);
+		if (!prep) return result;
+		result.data = augmentRowsWithActions({
+			envelopes: prep.envelopes,
+			rows: result.data,
+			resolvedProjection: prep.resolvedProjection
+		});
+		return result;
+	}
 	/**
 	* Extracts a composite identifier object from query params.
 	* Tries composite primary key first, then compound unique indexes.
 	*/
 	extractCompositeId(query) {
-		const pkFields = this.readable.primaryKeys;
-		if (pkFields.length > 1) {
+		for (const id of this._compositeIdShapes) {
 			const idObj = {};
 			let allPresent = true;
-			for (const field of pkFields) {
+			for (const field of id.fields) {
 				if (query[field] === void 0) {
 					allPresent = false;
 					break;
@@ -782,19 +1120,6 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			}
 			if (allPresent) return idObj;
 		}
-		for (const index of this.readable.indexes.values()) {
-			if (index.type !== "unique" || index.fields.length < 2) continue;
-			const idObj = {};
-			let allPresent = true;
-			for (const indexField of index.fields) {
-				if (query[indexField.name] === void 0) {
-					allPresent = false;
-					break;
-				}
-				idObj[indexField.name] = query[indexField.name];
-			}
-			if (allPresent) return idObj;
-		}
 		return new HttpError(400, "Query params do not match any composite primary key or compound unique index");
 	}
 	/**
@@ -803,6 +1128,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	async query(url) {
 		const parsed = this.parseQueryString(url);
 		const controls = parsed.controls;
+		this._coerceActionsControl(controls);
 		if (controls.$groupBy?.length) {
 			if (controls.$with?.length) return new HttpError(400, "Cannot combine $with and $groupBy in the same query");
 			if (parsed.insights) {
@@ -820,17 +1146,16 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		if (error) return error;
 		const gateError = this.checkGates(parsed.filter, controls, this._gates);
 		if (gateError) return gateError;
-		const [filter, select] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
+		const [filter, rawSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
 		if (controls.$count) return this.readable.count({
 			filter,
 			controls: {
 				...controls,
-				$select: select
+				$select: rawSelect
 			}
 		});
-		const searchTerm = controls.$search;
-		const indexName = controls.$index;
-		const vectorField = controls.$vector;
+		const select = this.widenPreferredIdProjection(rawSelect);
+		if (select instanceof HttpError) return select;
 		const threshold = controls.$threshold ? Number(controls.$threshold) : void 0;
 		const queryObj = {
 			filter,
@@ -841,19 +1166,20 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 				$threshold: threshold
 			}
 		};
-		if (vectorField !== void 0 && searchTerm) {
-			const vector = await this.computeEmbedding(searchTerm, vectorField || void 0);
-			if (vectorField) return this.readable.vectorSearch(vectorField, vector, queryObj);
-			return this.readable.vectorSearch(vector, queryObj);
-		}
-		if (searchTerm && this.readable.isSearchable()) return this.readable.search(searchTerm, queryObj, indexName);
-		return this.readable.findMany(queryObj);
+		return (await this._runReadWithActions(queryObj, controls, select, async (q, strategy) => {
+			switch (strategy.kind) {
+				case "vector": return { data: await (strategy.vectorField ? this.readable.vectorSearch(strategy.vectorField, strategy.vector, q) : this.readable.vectorSearch(strategy.vector, q)) };
+				case "search": return { data: await this.readable.search(strategy.term, q, strategy.index) };
+				case "plain": return { data: await this.readable.findMany(q) };
+			}
+		})).data;
 	}
 	/**
 	* **GET /pages** — returns paginated records with metadata.
 	*/
 	async pages(url) {
 		const parsed = this.parseQueryString(url);
+		this._coerceActionsControl(parsed.controls);
 		const error = this.validateParsed(parsed, "pages");
 		if (error) return error;
 		const controls = parsed.controls;
@@ -862,10 +1188,9 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		const page = Math.max(Number(controls.$page || 1), 1);
 		const size = Math.max(Number(controls.$size || 10), 1);
 		const skip = (page - 1) * size;
-		const [filter, select] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
-		const searchTerm = controls.$search;
-		const indexName = controls.$index;
-		const vectorField = controls.$vector;
+		const [filter, rawSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
+		const select = this.widenPreferredIdProjection(rawSelect);
+		if (select instanceof HttpError) return select;
 		const threshold = controls.$threshold ? Number(controls.$threshold) : void 0;
 		const query = {
 			filter,
@@ -877,13 +1202,13 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 				$threshold: threshold
 			}
 		};
-		let result;
-		if (vectorField !== void 0 && searchTerm) {
-			const vector = await this.computeEmbedding(searchTerm, vectorField || void 0);
-			if (vectorField) result = await this.readable.vectorSearchWithCount(vectorField, vector, query);
-			else result = await this.readable.vectorSearchWithCount(vector, query);
-		} else if (searchTerm && this.readable.isSearchable()) result = await this.readable.searchWithCount(searchTerm, query, indexName);
-		else result = await this.readable.findManyWithCount(query);
+		const result = await this._runReadWithActions(query, controls, select, async (q, strategy) => {
+			switch (strategy.kind) {
+				case "vector": return strategy.vectorField ? this.readable.vectorSearchWithCount(strategy.vectorField, strategy.vector, q) : this.readable.vectorSearchWithCount(strategy.vector, q);
+				case "search": return this.readable.searchWithCount(strategy.term, q, strategy.index);
+				case "plain": return this.readable.findManyWithCount(q);
+			}
+		});
 		return {
 			data: result.data,
 			page,
@@ -897,15 +1222,14 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	*/
 	async getOne(id, url) {
 		const parsed = this.parseQueryString(url);
+		this._coerceActionsControl(parsed.controls);
 		if (Object.keys(parsed.filter).length > 0) return new HttpError(400, "Filtering is not allowed for \"one\" endpoint");
 		const error = this.validateParsed(parsed, "getOne");
 		if (error) return error;
-		const select = await this.transformProjection(parsed.controls.$select);
-		const controls = {
-			...parsed.controls,
-			$select: select
-		};
-		return this.returnOne(this.readable.findById(id, { controls }));
+		const rawSelect = await this.transformProjection(parsed.controls.$select);
+		const select = this.widenPreferredIdProjection(rawSelect);
+		if (select instanceof HttpError) return select;
+		return this._findByIdAndAugment(id, parsed.controls, select);
 	}
 	/**
 	* **GET /one?field1=val1&field2=val2** — retrieves a single record by composite key
@@ -915,12 +1239,29 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		const idObj = this.extractCompositeId(query);
 		if (idObj instanceof HttpError) return idObj;
 		const parsed = this.parseQueryString(url);
-		const select = await this.transformProjection(parsed.controls.$select);
+		this._coerceActionsControl(parsed.controls);
+		const rawSelect = await this.transformProjection(parsed.controls.$select);
+		const select = this.widenPreferredIdProjection(rawSelect);
+		if (select instanceof HttpError) return select;
+		return this._findByIdAndAugment(idObj, parsed.controls, select);
+	}
+	async _findByIdAndAugment(id, parsedControls, select) {
+		const prep = await this._prepareAugmentation(parsedControls, select);
+		const initialSelect = prep?.widenedSelect ?? select;
 		const controls = {
-			...parsed.controls,
-			$select: select
+			...parsedControls,
+			$select: initialSelect
 		};
-		return this.returnOne(this.readable.findById(idObj, { controls }));
+		const row = await this.readable.findById(id, { controls });
+		const item = await this.returnOne(Promise.resolve(row));
+		if (item instanceof HttpError) return item;
+		if (!prep) return item;
+		const [augmented] = augmentRowsWithActions({
+			envelopes: prep.envelopes,
+			rows: [item],
+			resolvedProjection: prep.resolvedProjection
+		});
+		return augmented;
 	}
 	/**
 	* **GET /meta** — returns table/view metadata for UI.
@@ -954,6 +1295,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			vectorSearchable: this.readable.isVectorSearchable(),
 			searchIndexes: this.readable.getSearchIndexes(),
 			primaryKeys: [...this.readable.primaryKeys],
+			preferredId: [...this.readable.preferredId],
 			relations,
 			fields,
 			type: this.getSerializedType(),
@@ -1005,6 +1347,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;
@@ -1251,6 +1594,7 @@ let AsValueHelpController = class AsValueHelpController extends AsReadableContro
 			vectorSearchable: false,
 			searchIndexes: [],
 			primaryKeys: this.primaryKey ? [this.primaryKey] : [],
+			preferredId: this.primaryKey ? [this.primaryKey] : [],
 			relations: [],
 			fields,
 			type: this.getSerializedType(),
@@ -1303,6 +1647,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,151 +1808,120 @@ function applySelect(rows, select) {
 	});
 }
 //#endregion
-//#region src/actions/db-action.decorator.ts
+//#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`;
+}
 /**
-* 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.
+* 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}.
 *
-* @example
-* ```ts
-* @Post('actions/block')
-* @DbAction('block', { label: 'Block', icon: 'i-as-block', intent: 'negative' })
-* async blockUser(@DbActionPK() id: string) { ... }
-* ```
+* - `'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).
 */
-function DbAction(name, opts = {}) {
-	return getMoostMate().decorate((current) => {
-		const meta = current;
-		return {
-			...current,
-			[MOOST_DB_ACTION]: mergeActionMeta(meta, {
-				name,
-				opts
-			})
+var ActionDisabledError = class extends HttpError {
+	name = "ActionDisabledError";
+	constructor(action, id, ids) {
+		const body = {
+			name: "ActionDisabledError",
+			message: buildMessage(action, ids),
+			statusCode: 409,
+			action
 		};
-	});
-}
+		if (ids !== void 0) body.ids = ids;
+		else if (id !== void 0) body.id = id;
+		super(409, body);
+	}
+};
 //#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 } })
-		};
-	});
+//#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) {
+	let ctrl;
+	let methodName;
+	try {
+		const cc = useControllerContext(ctx);
+		ctrl = cc.getController();
+		methodName = cc.getMethod();
+	} catch {
+		return;
+	}
+	if (!ctrl || !methodName) return void 0;
+	return getMoostMate().read(ctrl.constructor, methodName)?.[MOOST_DB_ACTION];
 }
 //#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/id-validation.ts
+const SOURCE_CACHE = /* @__PURE__ */ new WeakMap();
+function getSourceCache(source) {
+	let cache = SOURCE_CACHE.get(source);
+	if (cache) return cache;
+	const identifications = source.getIdentifications();
+	const byKeySig = /* @__PURE__ */ new Map();
+	for (const ident of identifications) byKeySig.set(fieldsSig(ident.fields), ident);
+	const fieldByName = /* @__PURE__ */ new Map();
+	for (const fd of source.fieldDescriptors) fieldByName.set(fd.path, fd);
+	cache = {
+		byKeySig,
+		fieldByName,
+		formatted: identifications.map((id) => `[${id.fields.join(", ")}]`).join(", ")
+	};
+	SOURCE_CACHE.set(source, cache);
+	return cache;
 }
-function isPkValidationSource(value) {
+function fieldsSig(fields) {
+	return fields.toSorted().join("");
+}
+function isIdValidationSource(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));
+	return typeof v.getIdentifications === "function" && Array.isArray(v.fieldDescriptors);
 }
-//#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.
-*/
-function validateSinglePk(body, source, path = "") {
-	const errors = collectPkErrors(body, source, path);
+function validateSingleId(body, source, path = "") {
+	const errors = collectIdErrors(body, source, path);
 	if (errors.length > 0) throw new ValidatorError(errors);
+	return body;
 }
-/**
-* Validate a JSON-decoded body against an array of PK shapes (`@DbActionPKs`).
-* The body MUST be an array; each element is validated against the PK schema.
-*/
-function validateMultiPk(body, source) {
+function validateMultiId(body, source) {
 	if (!Array.isArray(body)) throw new ValidatorError([{
 		path: "",
-		message: "Expected JSON array of primary keys",
+		message: "Expected JSON array of identifier objects",
 		details: []
 	}]);
 	const errors = [];
-	for (let i = 0; i < body.length; i++) errors.push(...collectPkErrors(body[i], source, `[${i}]`));
+	for (let i = 0; i < body.length; i++) errors.push(...collectIdErrors(body[i], source, `[${i}]`));
 	if (errors.length > 0) throw new ValidatorError(errors);
+	return body;
 }
-function collectPkErrors(value, source, pathPrefix) {
-	const pkFields = source.primaryKeys;
-	if (pkFields.length === 0) return [{
+function collectIdErrors(value, source, pathPrefix) {
+	if (!isPlainObject(value)) return [{
+		path: pathPrefix,
+		message: "Expected JSON object for row identifier",
+		details: []
+	}];
+	const cache = getSourceCache(source);
+	if (cache.byKeySig.size === 0) return [{
+		path: pathPrefix,
+		message: "Table has no identifier configured",
+		details: []
+	}];
+	const match = cache.byKeySig.get(fieldsSig(Object.keys(value)));
+	if (!match) return [{
 		path: pathPrefix,
-		message: "Table has no primary key configured",
+		message: `Identifier fields must exactly match one of: ${cache.formatted}`,
 		details: []
 	}];
 	const errors = [];
-	if (pkFields.length === 1) {
-		const err = checkScalar(value, findFieldDescriptor(source, pkFields[0]), pathPrefix);
-		if (err) errors.push(err);
-		return errors;
-	}
-	if (!isPlainObject(value)) {
-		errors.push({
-			path: pathPrefix,
-			message: "Expected JSON object for composite primary key",
-			details: []
-		});
-		return errors;
-	}
-	for (const fieldName of pkFields) {
+	for (const fieldName of match.fields) {
 		const sub = pathPrefix ? `${pathPrefix}.${fieldName}` : fieldName;
-		if (!(fieldName in value)) {
-			errors.push({
-				path: sub,
-				message: `Missing primary-key field "${fieldName}"`,
-				details: []
-			});
-			continue;
-		}
-		const fd = findFieldDescriptor(source, fieldName);
-		const err = checkScalar(value[fieldName], fd, sub);
+		const err = checkScalar(value[fieldName], cache.fieldByName.get(fieldName), sub);
 		if (err) errors.push(err);
 	}
 	return errors;
 }
-function findFieldDescriptor(source, name) {
-	for (const fd of source.fieldDescriptors) if (fd.path === name) return fd;
-}
 function checkScalar(value, fd, path) {
 	const expected = fd?.designType ?? "string";
 	if (expected === "string" && typeof value !== "string") return scalarMismatch(path, expected, value);
@@ -1617,7 +1931,7 @@ function checkScalar(value, fd, path) {
 function scalarMismatch(path, expected, value) {
 	return {
 		path,
-		message: `Expected primary-key value to be ${expected}, got ${describe(value)}`,
+		message: `Expected identifier value to be ${expected}, got ${describe(value)}`,
 		details: []
 	};
 }
@@ -1630,38 +1944,333 @@ function isPlainObject(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //#endregion
-//#region src/actions/db-action-pk.decorator.ts
+//#region src/actions/id-cache.ts
+const boundTableKey = key("atscript_db_action_bound_table");
+function getActionTable(ctx) {
+	const fromSlot = ctx.has(boundTableKey) ? ctx.get(boundTableKey) : void 0;
+	if (fromSlot) return fromSlot;
+	const ctrl = useControllerContext(ctx).getController();
+	return ctrl?.readable ?? ctrl?.table ?? null;
+}
+function noTableError(ctx) {
+	const actionName = readCurrentActionMeta(ctx)?.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 resolveValidatedId(ctx, validate) {
+	const table = getActionTable(ctx);
+	if (!isIdValidationSource(table)) throw noTableError(ctx);
+	const body = await useBody(ctx).parseBody();
+	validate(body, table);
+	return body;
+}
+const dbActionIdSlot = cached((ctx) => resolveValidatedId(ctx, validateSingleId));
+const dbActionIdsSlot = cached(async (ctx) => {
+	return await resolveValidatedId(ctx, validateMultiId);
+});
+const useDbActionId = defineWook((ctx) => ({ load: () => ctx.get(dbActionIdSlot) }));
+const useDbActionIds = defineWook((ctx) => ({ load: () => ctx.get(dbActionIdsSlot) }));
+//#endregion
+//#region src/actions/row-cache.ts
+function asFetchTable(value) {
+	if (!value || typeof value !== "object") return null;
+	const v = 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;
+}
+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) for (const f of action) fields.add(f);
+	return fields;
+}
+async function loadRow(ctx) {
+	const id = await ctx.get(dbActionIdSlot);
+	const table = asFetchTable(getActionTable(ctx));
+	if (!table) throw noTableError(ctx);
+	const fields = seedActionFields(ctx, table);
+	for (const k of Object.keys(id)) fields.add(k);
+	const row = await table.findOne({
+		filter: id,
+		controls: { $select: [...fields] }
+	});
+	if (row == null) throw new HttpError(404, "Row not found for action identifier");
+	return row;
+}
+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: { $or: dedupedIds },
+		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]));
+}
+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") {
+			const verdicts = disabled([await ctx.get(dbActionRowSlot)]);
+			assertVerdictLength(action, verdicts, 1);
+			if (verdicts[0]) throw new ActionDisabledError(action, await ctx.get(dbActionIdSlot));
+			return;
+		}
+		const ids = await ctx.get(dbActionIdsSlot);
+		const rows = await ctx.get(dbActionRowsSlot);
+		const existingRows = [];
+		for (const row of rows) if (row !== void 0) existingRows.push(row);
+		const verdicts = disabled(existingRows);
+		assertVerdictLength(action, verdicts, existingRows.length);
+		const failingIds = [];
+		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 {
+				passingRows.push(row);
+				passingIds.push(ids[i]);
+			}
+		}
+		if (onDisabledRows === "skip") {
+			if (passingRows.length === 0) throw new ActionDisabledError(action, void 0, [...ids]);
+			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);
+	}, 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.
+*
+* Generic over `TRow` (annotate at the call site: `@DbAction<Order>(...)`)
+* and `R` (the literal `requiredFields` tuple, inferred via `const R`).
+* The `disabled` predicate's `rows` argument is type-narrowed to
+* `Pick<FlatOf<TRow>, R[number]>[]`.
+*/
+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 ?? []);
+		const rawOpts = opts;
+		if (typeof rawOpts.disabled === "function" && (scan.level === "row" || scan.level === "rows")) Intercept(buildGateInterceptor({
+			action: name,
+			level: scan.level,
+			disabled: rawOpts.disabled,
+			onDisabledRows: rawOpts.onDisabledRows ?? "reject",
+			table: rawOpts.table
+		}))(target, propertyKey, descriptor);
+		else if (scan.hasRowParam) Intercept(buildThinInterceptor({ table: rawOpts.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/id-source.ts
 /**
-* Parameter resolver that reads the primary key from the JSON request body
-* and validates it against the bound table's PK schema.
+* Build a parameter decorator that reads its value from the cached ID wook
+* (single or multi). Validation runs inside the wook factory exactly once
+* per request, regardless of how many readers consume the value (`@DbActionID*`
+* resolver, gate interceptor, cached row wook, in-handler composables).
+*
+* Marks the param so {@link discoverActions} can infer the action's `level`.
+*/
+function createIdParamDecorator(kind) {
+	const mate = getMoostMate();
+	const resolverName = kind === "id" ? "dbActionId" : "dbActionIds";
+	const resolver = kind === "id" ? async () => current().get(dbActionIdSlot) : async () => current().get(dbActionIdsSlot);
+	return ApplyDecorators(mate.decorate(MOOST_DB_ACTION_PARAM, kind), Resolve(resolver, resolverName));
+}
+//#endregion
+//#region src/actions/db-action-id.decorator.ts
+/**
+* Parameter resolver that reads a row identifier from the JSON request body
+* and validates it against the bound table's legitimate identifiers.
+*
+* Body shape is always a JSON object — no scalar form. The object's key set
+* MUST exactly match one of the table's legitimate identifications:
 *
-* - Single-field PK → JSON-encoded scalar (`"abc"`, `42`, `true`).
-* - Composite PK → JSON object with all PK fields.
+* - Single-field PK → `{ id: "abc" }` (or whatever the PK prop is named).
+* - Composite PK → `{ tenantId: "...", userId: "..." }`.
+* - Single-field unique index → `{ slug: "alpha" }`.
+* - Compound unique index → `{ tenantId: "...", slug: "..." }`.
 *
-* Validation is strict — no type coercion. Mismatches throw a
+* Strict — unknown fields are rejected, no type coercion. Mismatches throw a
 * `ValidatorError` which the existing validation interceptor surfaces as
 * HTTP 400 with the same envelope as DTO failures.
 *
 * 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 ID 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");
+function DbActionID() {
+	return createIdParamDecorator("id");
 }
 //#endregion
-//#region src/actions/db-action-pks.decorator.ts
+//#region src/actions/db-action-ids.decorator.ts
 /**
-* Parameter resolver that reads a JSON array of primary keys from the request
-* body and validates each entry against the bound table's PK schema.
+* Parameter resolver that reads a JSON array of row identifiers from the
+* request body and validates each entry against the bound table.
+*
+* Body shape is always a JSON array of objects — no scalar form. Each
+* element's key set MUST exactly match one of the table's legitimate
+* identifications (PK or any unique index). Elements MAY mix shapes:
+* `[{ id: "1" }, { slug: "alpha" }]` is valid when both `id` is the PK
+* and `slug` is a unique index.
 *
-* - Scalar PK → JSON array of scalars (`["a","b","c"]`).
-* - Composite PK → JSON array of objects.
+* Strict — unknown fields are rejected, no type coercion. Marks the param
+* so {@link discoverActions} can infer the action's `level` as `'rows'`.
 *
-* 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 ID slot is overwritten in place); see
+* {@link dbActionIdsSlot} for precedence details.
 */
-function DbActionPKs() {
-	return createPkParamDecorator("pks", validateMultiPk, "dbActionPks");
+function DbActionIDs() {
+	return createIdParamDecorator("ids");
+}
+//#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 identifier was supplied in
+* the request body.
+*
+* 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 fetched by the identifiers
+* supplied in the request body.
+*
+* 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
@@ -1672,10 +2281,9 @@ function DbActionPKs() {
 * the level-pinned shortcuts (`@DbTableActions`, `@DbRowActions`,
 * `@DbRowsActions`) to avoid repeating `level`.
 *
-* The dictionary key serves as the action `name`. Entries do NOT bind any
-* HTTP route — the meta builder surfaces them in `/meta` only. For
-* `processor: 'backend'`, the dev-supplied `value` MUST point to a real
-* `@Post`-bound endpoint accepting the level-determined body shape.
+* Generic over `TRow` (annotate at the call site: `@DbActions<Order>(...)`)
+* and `D` (the literal dict, captured via `const D`). Each entry's
+* `disabled` predicate is type-narrowed by its own `requiredFields` literal.
 *
 * Multiple `@DbActions` (and shortcut) decorators on the same class
 * accumulate.
@@ -1697,11 +2305,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 +2324,19 @@ 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 };
+//#region src/actions/per-row.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.
+*
+* ```ts
+* @DbAction<Order>('archive', {
+*   requiredFields: ['status'],
+*   disabled: perRow(r => r.status === 'archived'),
+* })
+* ```
+*/
+const perRow = (fn) => (rows) => rows.map(fn);
+//#endregion
+export { ActionDisabledError, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, DbActionID, DbActionIDs, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, discoverActions, perRow, useDbActionId, useDbActionIds, useDbActionRow, useDbActionRows, validationErrorTransform };